Cleanup links, Nuke Transition guide (early) , Install community scri… (

#669)

* Cleanup links, Nuke Transition guide (early) , Install community scripts and plugins recomend , bugs and workaround updated

Co-authored-by: Frédéric Devernay <devernay@users.noreply.github.com>

Documentation/source/guide/Transition-fromNuke_01.rst

@@ -0,0 +1,54 @@
+.. for help on writing/extending this file, see the reStructuredText cheatsheet
+   http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
+   
+Nuke to Natron transition guide
+===============================
+
+.. toctree::
+   :maxdepth: 2
+
+This document is an very incomplete stage.
+
+
+Natron and Nuke are very similar. We will focus here on the differences between them.
+
+
+Nodes names
+-----------
+Many nodes have similar names in Natron and Nuke. Here are the the ones thar are different
+
+
+
++----------------+------------------+
+| Nuke           | Natron           |
++================+==================+
+|  CurveTool     | ImageStatistics  |
++----------------+------------------+
+|    Copy        | Shuffle          |
++----------------+------------------+
+
+
+What's not in Nuke?
+-------------------
+
+#. Cloning node groups and pyplugs is possible. This is very powerful as it mean you can apply the same complex process to different images without constantly copy / pasting when you change parameters. Beware that the nodes connexions must not be changed. Only the node parameters are be updated, not their connexions.
+#. Cloning roto nodes.
+#. Hide the unmodified parameters of a node. In Natron, click on the 4th icon from the right in the properties panel. This will make the window far more readable and help you focus on what you're working on.
+
+What's not in Natron?
+---------------------
+
+#. Mainly 3D functions are not implemented. But Natron is very good for compositing 3D images from other software. For example multi pass EXR generated by Blender or other 3D software.
+#. Some missing features can be filled by adding OpenFX plugins from other software vendors.
+
+.. note::
+   **Tip:**
+   CommunityScripts have a tool named PMCard3D and PMcamera that bring minimal 3D functionality.
+
+
+
+
+Python scripting
+----------------
+
+To get the value of a pixel in Natron, use the ImageStatistics node with a 1x1 rectangle, and retrieve the pixel value from the statMean parameter.

Documentation/source/guide/getstarted-installation.rst

@@ -13,3 +13,40 @@ This chapter will guide you through the installation of Natron on Windows, Mac a
    getstarted-installation-mac
    getstarted-installation-linux
 
+Additional Elements
+===================
+
+Community scripts
+-----------------
+
+Many scripts that bring additional functionality can be downloaded from:
+https://github.com/NatronGitHub/natron-python-scripting
+
+To install these:
+
+- Copy the content of this repository to your .Natron folder.:ref: 'Natron plug-in paths'
+- Restart Natron
+- Enjoy the new items available mostly in Tools and Edit menu.
+
+
+These tool add predefined roto shapes, multilayer EXR extraction, node connexion tools, and more.
+They will bring Natron closer to the Nuke interface.
+Albeit experimental, these scripts are a recommended download, more specifically for previous Nuke users.
+
+
+Community plugins
+-----------------
+
+Additional Python plugins (PyPlugs) can be downloaded from:
+https://github.com/NatronGitHub/natron-plugins
+
+To install these:
+
+- Copy the content of this repository to any folder of your choice.
+- Open Natron preferences from the menubar, select Plugins->PyPlugs search path->Add.. and enter the extracted file location.
+- Save preferences.
+- Restart Natron.
+- Enjoy the new tools available in the left toolbar.
+
+These tools bring animated textures for motion designers, as well as most common Nuke gizmos (DespillMadness, PushPixel,...).
+Albeit experimental these scripts are a recommended download.

Documentation/source/guide/getstarted-troubleshooting.rst

@@ -34,18 +34,33 @@ The best way to have your bug considered for fixing is to first search on the `N
 If this bug does not seem to be a known issue, then post a `new issue <https://github.com/NatronGitHub/Natron/issues/new>`_ on the Natron github, and follow strictly the guidelines to report the bug. The issue title should be as precise as possible ("Natron crash" is *not* a correct title, see existing issues for title examples). If possible, also post a project that exhibits the issue. Make the project as small as possible: remove extra assets or replace them by small JPEG sequences, checkerboards or colorwheels, etc. You can then either attach your project as a zip file to the github issue, or post a link to a file sharing service.
 
 
-Common Workarounds
-------------------
+Known Bugs and Workarounds
+--------------------------   
+
+This document is an very incomplete stage.
+the sharp\+\ number is the number of the issue on github to help keep track of bugfixes.
 
 Luckily, there are workarounds for most Natron crashes or hangs. Here are a few one worth trying, but of course your mileage may vary or you may find another workaround (which you should describe in the proper `Natron issue <https://github.com/NatronGitHub/Natron/issues>`_).
 
-#. Avoid using videos with inter-frame compression as inputs and outputs. This includes H.264 (eg AVCHD) and H.265 (HEVC) video. ProRes is OK but slow, especially for writing. DNxHR is OK. Individual frames are *best* (DPX, EXR, TIFF, PNG, JPEG, whatever suits your input video quality and bit depth). The video reader is here for convenience, but it may have difficulties decoding some videos. The video writer may also be a source of bugs, and should be avoided for long sequences: if Natron crashes in the middle, then the whole sequence has to be rendered. Extract individual frames, do your compositing, then compress the frames (and optionally mux the audio) with an external tool. To extract frames, you may use a simple Natron project or any other tool (e.g. `FFmpeg <https://www.ffmpeg.org/ffmpeg.html>`_). To compress frames to a video, there are also many tools available, e.g. `FFmpeg <https://www.ffmpeg.org/ffmpeg.html>`_, `MEncoder <https://en.wikipedia.org/wiki/MEncoder>`_, or `VirtualDub <http://virtualdub.sourceforge.net/>`_ (windows-only). This is the standard compositing workflow and the preferred method of running Natron. See the :doc:`tutorial on how to convert videos to image sequences <tutorials-imagesequence>`.
-#. If Natron hangs or crashes when rendering an image sequence (this does not work when rendering to a video), check that the rendered frames are OK, relaunch Natron and in the parameters of the Write node uncheck "Overwrite". That way, only the missing frames will be rendered.
-#. If you have a large project, or a project with heavy processing, use the :ref:`DiskCache Plugin <fr.inria.built-in.DiskCache>` at places that make sense: downstream heavy processing in the graph, or before you use the result of processing as inputs to :ref:`Roto <fr.inria.built-in.Roto>` or :ref:`RotoPaint <fr.inria.built-in.RotoPaint>`.
-#. On multicore computers (e.g. Threadripper), go to Edit => Preferences => Threading and under Number of parallel renders limit it to "8".
+- Avoid using videos with inter-frame compression as inputs and outputs. This includes H.264 (eg AVCHD) and H.265 (HEVC) video. ProRes is OK but slow, especially for writing. DNxHR is OK. Individual frames are *best* (DPX, EXR, TIFF, PNG, JPEG, whatever suits your input video quality and bit depth). The video reader is here for convenience, but it may have difficulties decoding some videos. The video writer may also be a source of bugs, and should be avoided for long sequences: if Natron crashes in the middle, then the whole sequence has to be rendered. Extract individual frames, do your compositing, then compress the frames (and optionally mux the audio) with an external tool. To extract frames, you may use a simple Natron project or any other tool (e.g. `FFmpeg <https://www.ffmpeg.org/ffmpeg.html>`_). To compress frames to a video, there are also many tools available, e.g. `FFmpeg <https://www.ffmpeg.org/ffmpeg.html>`_, `MEncoder <https://en.wikipedia.org/wiki/MEncoder>`_, or `VirtualDub <http://virtualdub.sourceforge.net/>`_ (windows-only). This is the standard compositing workflow and the preferred method of running Natron. See the :doc:`tutorial on how to convert videos to image sequences <tutorials-imagesequence>`.
+- If Natron hangs or crashes when rendering an image sequence (this does not work when rendering to a video), check that the rendered frames are OK, relaunch Natron and in the parameters of the Write node uncheck "Overwrite". That way, only the missing frames will be rendered.
+- If you have a large project, or a project with heavy processing, use the :ref:`DiskCache Plugin <fr.inria.built-in.DiskCache>` at places that make sense: downstream heavy processing in the graph, or before you use the result of processing as inputs to :ref:`Roto <fr.inria.built-in.Roto>` or :ref:`RotoPaint <fr.inria.built-in.RotoPaint>`.
+- On multicore computers (e.g. Threadripper), go to Edit => Preferences => Threading and under Number of parallel renders limit it to "8".
 
 You will quickly notice that using individual frames instead of videos for inputs and output give a *big* performance boost and will most probably solve your issues, so once you've learned how to decompress/compress any video, this will become your standard workflow. Just add extra disk space, and you're good to do serious and fluid compositing with Natron.
 
+User Interface bugs
+...................
+
+- Can't rename a node `\#664 <https://github.com/NatronGitHub/Natron/issues/664>`_: If the Properties panel does not let you rename a node try to rename with the "N" shortcut in the nodegraph. If it does not work either, it can be done in Python with ``myoldname.setLabel('newname')``
+
+Roto Node bugs
+..............
+
+- Mask input does not work `\#367 <https://github.com/NatronGitHub/Natron/issues/367>`_: This feature is not yet implemented.
+- Rotopaint clone tool: sourceTypeChoice performs the same action when set to both "background" and "foreground" `\#629 <https://github.com/NatronGitHub/Natron/issues/629>`_: Use multiple rotopaint nodes.
+
+
 
 OpenGL/GPU Rendering Issues
 ---------------------------
@@ -60,4 +75,9 @@ If the viewer displays some error message about OpenGL, then GPU rendering is pr
 
 | If you there is an error similar to ``Shadertoy3: Can not render: glGetString(GL_VERSION) failed.`` 
 | Go to File => Preferences => GPU Rendering and set No. of OpenGL Context to 5
-| Save and relaunch Natron.
+| Save and relaunch Natron.
+
+.. toctree::
+   :maxdepth: 2
+
+   known-bugs-and-workarounds

Documentation/source/guide/getstarted.rst

@@ -9,6 +9,8 @@ Getting started
 
    getstarted-about
    getstarted-installation
+   Transition-fromNuke_01
    getstarted-environment
    getstarted-troubleshooting
+   known-bugs-and-workarounds
 

Documentation/source/guide/thenodes-common-properties.rst

@@ -15,11 +15,47 @@ The properties window
 
 .. image:: _images/TheNodes-Various/nodes_properties.gif
 
+1: Clears the properties panel. It is a quick way to close everything in the properties panel.
+
+2: Minimize the panels to keep only the node names visible. One can then choose wich ones to close completely with their own close button (see 14).
+
+3: Maximum number of nodes simultaneously opened in the propoerties pane. Too many opened panes can be confusing as some are not visible anymore because of limited screen space. Too many nodes opened can also slow down the user interface.
+
+
 The Utility icons
 -----------------
 
 .. image:: _images/TheNodes-Various/nodes_utility_tools.gif
 
+1: The node icon. Just a visual clue to see what a node really is (in case its name was changed). It is the same icon used in the node Graph.
+
+2: Special settings of the nodes. If a node is often used with the same settings, these can be saved/loaded as a preset file. This function is not used very much as it can be more convenient to copy-paste the node from a dummy Natron project used as a node presets library.
+
+One can also remove animations while keeping parameter values. This complements the "Restore Defaults" button (cf. 9).
+
+3: Center the node graph on this node. This can be useful to check wich node your are about to make changes on.
+
+4: The script name of the node as it appears on the top of the box in the node graph
+
+It is considered a good practice to leave this name unchanged and change the Label in the node tab instead. It helps see what the node really does just by looking at the graph. There cannot be 2 nodes with the same name. The names cannot contain spaces.
+
+In Python, this name is accessed through the ``getLabel`` function.
+
+5: The node color as seen in the graph. Click to change. This is just a visual cue and has no effect on the resulting image.
+
+6: Overlay color. For nodes that draw helpers in the viewer, a color can be specified here. This can be used if multiple transform nodes are opened to help you tell wich one belongs wich handle.
+
+7 / 8: Undo / Redo. These functions are specific to the node. It is separate from the global Undo / Redo of Natron and thus gives you more control on your changes.
+
+9: Restore default values for this node on all parameters, and delete animations.
+
+10: Help brings you to the reference documentation for this node.
+
+11: Hide parameters without modifications.
+.. note::
+   **Tip:**
+   This button is a quick way to find what parameters were modified in a node.
+
 
 Layers Properties
 -----------------

Documentation/source/guide/thenodes-draw-ramp.rst

@@ -11,7 +11,7 @@ Ramp is what grown-ups call a gradient. The Ramp node of Natron give a butter-sm
 .. image:: _images/TheNodes-Draw/nodes_draw_ramp01.jpg
 
 Usage
---------
+-----
 
 The End colors can be changed. And the end positions can be moved in the viewer with the point 0 / Point 1 widgets visible in the viewer when the properties of the node are opened.
 

Documentation/source/guide/thenodes-image-read.rst

@@ -88,11 +88,15 @@ quicktime options:
 
 Allows multi track videos (eg. stereo files) to be split in different Layers in Natron
 
-raw file options:
+RAW file options:
 
 .. image:: _images/TheNodes-Image/read_node_decoder_raw.jpg
 
 
+PDF file options:
+
+Multi-page PDFs can be loaded in Natron. To view the different pages, add a Shuffle node after the Read node to choose the layer containing the desired page.
+
 Color
 -----
 
@@ -108,4 +112,4 @@ The file will be converted from "File colorspace" to "Output Colorspace"
      * When file and Output spaces are the same, no conversion will occur
 
 See :doc:`The readers <compositing-projects-readers>` section for more information.
-
+

Documentation/source/guide/thenodes-merge-merge.rst

@@ -0,0 +1,21 @@
+.. for help on writing/extending this file, see the reStructuredText cheatsheet
+   http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
+
+Merge Node
+==========
+
+Merge is the node that allows to stack imeges one ontop of the other.
+
+Usage
+-----
+
+Never consider RGB as being transparent by default - this is OK for unpremultiplied compositing (After Effects) but is invalid in a premultiplied compositor such as Natron or Nuke.
+
+Users still have the option to ignore the alpha channel. (new from v2.4)
+
+
+.. toctree::
+    :maxdepth: 2
+
+
+

Documentation/source/guide/thenodes-merge.rst

@@ -1,3 +1,12 @@
-
-
-Merge: never consider RGB as being transparent by default - this is OK for unpremultiplied compositing (After Effects) but is invalid in a premultiplied compositor such as Natron or Nuke. Users still have the option to ignore the alpha channel. (new from v2.4)
+.. for help on writing/extending this file, see the reStructuredText cheatsheet
+   http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
+   
+Merge Nodes Menu
+================
+
+These are the nodes located in the layered paper sheets icon of the toolbar.
+
+.. toctree::
+      :maxdepth: 2
+
+      thenodes-merge-merge

Documentation/source/guide/thenodes.rst

@@ -9,4 +9,5 @@ The Nodes
 
    thenodes-common-properties
    thenodes-image
-   thenodes-draw
+   thenodes-draw
+   thenodes-merge