Documentation added tutorials-evaluating-script-structure.rst (#612)

* Documentation: Evaluating Script Structure

added on request

* added index entry

* Documentation: Composing Channels, Composing Colors

* fixed the * issues, added name to contributors.txt

.gitignore

@@ -221,6 +221,7 @@ bigtosmall.txt
 #Documentation/source/_group*
 #Documentation/source/_prefs.rst
 #Documentation/source/plugins
+Documentation/source/_build
 .qmake.stash
 App/Natron
 BreakpadClient.xcodeproj/
@@ -275,3 +276,5 @@ Gui/Resources/etc/fonts/fonts.conf
 
 # VS Code
 .vscode/
+
+

CONTRIBUTORS.txt

@@ -29,6 +29,11 @@ Francesco Paglia <fPaglia@github>
 rcspam <rcspam@github>
 Jean-Christophe Levet
 
+#Documentation (not everyone listed):
+
+Marc-André Gasser <magdesign@github>
+Martin Constable
+
 
 Version 1.0:
 -----------

Documentation/source/guide/compositing-channels.rst

@@ -1,8 +1,21 @@
 .. for help on writing/extending this file, see the reStructuredText cheatsheet
    http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
    
-Channels (empty)
-================
+Channels
+========
+
+Everything in digital art is channel information and Natron can manage many more than the standard red, green, blue and alpha channels.
+This is particularly important when 3D rendered output is composited typically consists of such channels as reflection, ambient occlusion, motion etc.
+It is also important in the management of alphas that typically need intense management within the composting workflow.
+
+
+:ref:`net.sf.openfx.ShufflePlugin`
+
+
+
+
+
+
 
 .. toctree::
    :maxdepth: 2

Documentation/source/guide/compositing-color.rst

@@ -1,8 +1,103 @@
 .. for help on writing/extending this file, see the reStructuredText cheatsheet
    http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
    
-Working with color (empty)
-==========================
+Working with color
+==================
+How to use Natron color correction nodes and tools to adjust the appearance of the images in your composites.
+When starting out, this information provides a good overview of Natron scopes and color-correction nodes,
+however not all options are covered here.
+
+
+
+The nodes
+---------
+Really important nodes are marked with an asterix:
+
+
+
+**Add***
+
+This node affects all values within the image in the same way: literally adding to them.
+Positive values will brighten all parts of the image. As a stand alone color manipulation it is of limited use, though it is ideal for lightening the blacks of distant objects.
+
+
+**Multiply***
+
+It can be used to brighten or darken an image, or to fix a color cast. In maths, Multiply has no effect upon zero (black). Hence, the Multiply node will have no effect upon the blacks of an image.
+
+**Clamp**
+
+The Clamp node, like the ColorLookup node, is not explicitly designed to provide feedback on images, however it can easily be used to do so.
+It functions in much the same way as the ClipTest node: it flattens out the user-defined lower and upper lightness range of the image and,
+if you tick MinClampTo and MaxClampTo, can replace these values with user defined colors.
+Properly used it can provide clearer information than the ClipTest node.
+
+
+**ColorLookup***
+
+A color lookup is what image editors Curves tool does.
+It is a very powerful tool, capable of replicating the function of many other color nodes.
+Its disadvantage is that it requires more processing than many of those nodes.
+The curve of a color lookup can also be a bit more difficult to read than nodes featuring sliders.
+
+**ColorSpace**
+
+Engineers think of color as existing in things called spaces which are mathematical, 3D models the purpose of which is to organise them. Different color spaces serve different purposes: some are meant for printing, some are meant for screen-based work, some are meant for TV. The ColorSpace can move an image from one color space to another. The neat thing about this is that it makes it possible to use channels from exotic color spaces as masks to simple RGB operations or to perform adjustments on images to produce results that would have been impossible in ordinary RGB space. The workflow is: convert from Natron default Linear color space into the color space of your choice, perform your funky magic, then convert back to linear.
+The saturation channel of HSL can, for example, have a contrast adjustment applied to it which could desaturate the less saturated parts of an image and super saturate the remainder. Woot! Try that in Photoshop!
+Lab color space is another useful fellow. It is the quantum physics of the color world and I shall but kiss the shadow of it's vast and complex form. The fascinating thing about this space is that it separates the lightness values of an image (the L channel) from it's hue and saturation (the a and b channel combined). HSL also does this but not nearly so well. You can take the a and b and move them into those of another image.
+The effect of this is similar to image editors hue blend mode. I have found it useful to augment the colorfulness of a dull sky by using the blurred color values from a vivid sunset.
+Try also blurring the a and b channels. This will blur only the hue and saturation components of an image and leave its lightness values alone.
+A novel use for the ColorSpace node can be found in the Assets page (see the Double Rainbows asset).
+
+**ColorCorrect***
+
+Artists have for thousands of years been separating the lightness values of their paintings into three bands: shadows, midtones and highlights. The ColorCorrect node is a collection of operations that not only can effect the entire image but can address separately these three ranges 
+
+**Gamma**
+
+This raises or lowers the middle-ish point of the color curve. The default value is one, with smaller numbers darkening the lower registers and higher numbers lightening them. There is a Gamma node but I find that stand-alone gamma adjustments are best done using ColorLookup so as to give you flexibility over where the ‘grab point‘ of your curve is. Both ColorCorrect and Grade have built in Gamma value sliders.
+
+**Grade***
+
+This node is a collection of operations that combine to work upon the lightness and hue values of an image. It is mostly a fixer: used for correcting and matching, though of course it can also be used for more aesthetically lavish purposes.
+
+**Histogram**
+
+**HueCorrect***
+
+This can be a very tricky node to get to know.
+We can conclude that the perception of the amount of hue within a color (its chroma) is linked to two things: saturation and lightness.
+When adjusting color it is important to have separate control over these values, which is something that the HueCorrect node offers.
+This effect it masks by two further values: hue and saturation. Its interface offers control over nine values:
+
+Saturation (sat)
+This can change the saturation value of an image, with respect to particular regions of hue.
+
+Luminance (lum)
+This can change the luminosity (i.e. brightness) value of an image, with respect to particular regions of hue.
+
+Luminance components (red, blue, green)
+This can change the r, g and b channels of an image, with respect to particular regions of hue.
+
+Suppression (r_sup, g_sup, b_sup)
+This is similar to adjusting the luminance components, but instead of nullifying them (replacing them with black), replaces them with white.
+
+Saturation threshold (sat_thrsh)
+This only effects the image if first the 'Luminance' or 'Luminance components' have been adjusted. Adjustments to this value will act as 'per hue' saturation level mask to the effect.
+
+
+**HSVTool**
+
+The HSVTool has three functions: Color replacement, Color adjust, Hue keyer
+
+
+**Saturation***
+
+A color becomes a grey if its RGB values are all identical.
+The Saturation node desaturates an image by averaging its RGB channels.
+More localised control over saturation is offered by the HueCorrect node.
+
+
 
 .. toctree::
    :maxdepth: 2

Documentation/source/guide/compositing-projects-setup.rst

@@ -1,6 +1,10 @@
 .. for help on writing/extending this file, see the reStructuredText cheatsheet
    http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
 
+
+.. _compositing-projects-setup:
+
+
 Project setup
 =============
 

Documentation/source/guide/tutorials-evaluating-script-structure.rst

@@ -0,0 +1,206 @@
+.. for help on writing/extending this file, see the reStructuredText cheatsheet
+   http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
+   
+   .. _evaluating-script-structure:
+
+   
+Evaluating Script Structure
+===========================
+tutorials-compositing-projects-setup
+Natron is a very 'adult' application that lets you handle your material in any way that you wish.
+It will not give you a warning beep or forbid you from doing anything.
+For this reason it is very easy to accidentally do things in the 'wrong' way. 
+This is a short (non comprehensive) list of common 'bad practice' items.
+Of course, sometimes these 'rules' may be broken, but only as an exception.
+
+
+
+File Do's and Dont's
+--------------------
+
+Folders and files should be well managed: consistently and rationally named.
+
+
+**Always set the format and FPS in settings before you start**
+
+
+The format once set (see :ref:`compositing-projects-setup`) , will determine all default formats after that.
+This is very important as a wrongly set format can cause the format of all default nodes to be set to something other than the format that you are working in.
+This can be infuriating and make script maintains every difficult.
+
+
+
+Manage folders and files
+-------------------------
+
+**Donʼt use absolute file paths**
+
+An absolute path is one that specifies the location of the file with respect to the computer 
+e.g.``My_Computer/school/lesson_one/asset.jpg``.
+A relative path is one that defines the location relative to a file or a folder.
+
+An absolute path 'breaks' when the project folder is moved to a new computer, and each filepath will then have to be manually repaired.
+A relative path, on the other hand, is far more durable.
+
+There are two flavours of relative paths:
+those that look 'downstream' (i.e. into the same folder in which the Natron file is located, or other folders within it) or 'upstream' (i.e. in the parent folders of the folders in which the Natron file is located).
+
+.. image:: _images/tutorials-evaluating-script-structure-file_stream.png
+ :width: 600px
+
+
+For downstream, the following relative filepath is recommend.
+This writes or reads into a folder called 'sources', which is located in the same folder as the Natron file. 
+The image below illustrates this relationship:
+
+``[file dirname [value root.name]]/sources/Asset_Name.jpg`` 
+
+.. image:: _images/tutorials-evaluating-script-structure-file_relative.png
+ :width: 600px
+
+For upstream, the following relative filepath is recommend.
+This writes or reads into a folder called 'comp-out', which is located 'upstream' to the Natron file.
+The image below illustrates this relationship. To go further upstream, the value end-n needs to be increased.
+
+``[join [lrange [split [file dirname [knob root.name]] "/"] 0 end-1] "/"]/comp-out/01_01_qua_v1.jpg``
+
+.. image:: _images/tutorials-evaluating-script-structure-file_relative2.png
+ :width: 600px
+
+
+Read node movies should be formatted as image sequences
+-------------------------------------------------------
+
+Movies rendered as QuickTime files can sometimes be difficult to perform time edits upon.
+It is highly recommended that movies read into Natron should be rendered first as image sequences (see :ref:`tutorials-imagesequence`).
+
+
+Script Housekeeping Do's and Dont's
+-----------------------------------
+
+Comb your hair and clean your shoes.
+
+**Consider masking stills in Gimp or Krita.**
+
+A Natron roto is not always a good way to mask a still image. Consider masking in Gimp/Krita instead: for complex shapes they are quicker to make and better.
+Save the result as tiff or png.
+
+**Avoid side masking a merge node**
+
+Side masks are for things like color corrections, filters etc. They are not to be used to determine transparency in a Merge node.
+If the same shape that you were recklessly going to use as a layer mask can be added to the Merge feeds as a Matte value.
+
+**Observe the primacy of the B feed**
+
+A script can be bothersome to manage if B feed primacy is not observed.
+
+**Avoid feeding more than two inputs into a merge node**
+
+Though the Merge node will accept many inputs, it does not do so in a way that is consistent and predictable. Consider instead stacking a whole bunch of merge nodes on top of each other.
+
+**Avoid using too many points when you roto**
+
+Too many points in a roto can be difficult to edit and hell to animate. Use as few as you can.
+
+**Avoid recycling masks**
+
+Two or more sequential nodes masked by the same channel can sometimes cause problems.
+Better instead to use a KeyMix.
+
+
+Color Grading Do's and Dont's
+=============================
+Some general rules to follow in color grading:
+
+**Use HSL 'color thinking' space**
+
+Color is a volume, with a single color value being a point in that volume.
+Describing a point within a volume requires at least three coordinates (e.g. x, y and z).
+Such a three point system is referred to as a color space. In digital imaging the color space most commonly used is red, green and blue (RGB).
+This may be referred to as our 'working' space. However, when artists are thinking about color they traditionally refer to hue, saturation and lightness (HSL) color space. This is more perceptually agreeable that RGB... artists find it far easier to make aesthetic judgments in this space.
+
++-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|HUE        |This can be understood as the 'name space' of the color (i.e. whether it is a blue, green, pink etc).                                                                                                               |
++-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|Saturation |This refers to the intensity (or purity) of the color. Hence black, white and grey all have zero saturation value. Hue and saturation together make up the chroma component of the color.                           |
++-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|Lightness  |The lightness values of an image is what we are left looking at if we pull the saturation of an image down to zero. To see the lightness values of an image, hover the cursor over the viewer and press the 'Y' key.|
++-----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Both lightness and saturation are expressed in terms of intensity. They are bound by terminal extremes (maximum and minimum).
+They are also related: zero or maximum lightness (i.e. Black and white) both result in zero saturation.
+Hue is traditionally expressed as values arranged around a wheel (i.e. A color wheel).
+
+
+When color grading, it is usual to first address lightness, followed by hue, then saturation.
+Sometimes an adjustment to one will result in a slight perpetual change to another.
+
+**Respect the difference between R, G and B**
+
+As already stated, the working space of digital color grading is RGB.
+These channel are not identical in what they express:
+
++-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|Red        |This is where details live. Look at the red channel, and see how even-form it is and how well it contains all the fine features of the image.                                                                                                                                                      |
++-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|Green      |Green is where the lightness values of the image live. Look at the green channel and see how closely it matches the lightness values of the image. When making a hue adjustment, it is customary to leave the green channel alone, as any adjustment to it could effect the lightness of the image.|
++-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|Blue       |Blue is where the large masses of the image lives. It also has the reputation of being the naughty channel, being much inclined to noisiness.                                                                                                                                                      |
++-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+**Color grade in order**
+
+Color grading may be divided into three stages, delivered in the following order:
+
+   1. Color correction
+   2. Color matching
+   3. Color stylization
+
+**Splitting up compound color edits**
+
+Complex color edits are best split up into small components. For example, don't try to adjust the lightness and the hue in one operation. Splitting up such compound adjustments into smaller chunks makes them easier to edit and troubleshoot.
+
+**Consider using simple color tools before using complex ones**
+
+Fancy nodes with lots of sliders might look fun to play with but are they necessary?
+You will find that for a lot of color correction work simple nodes like Multiply or Saturation is enough.
+These require less processing, but also make the script easier to read.
+
+**Donʼt leave 'fiddle' values in the parameters**
+
+When reading someone else's script, it can be very annoying to open something like a ColorCorrect to discover that a multiply has been set to .0003 (or some other random, completely ineffectual value).
+If you intend to change a value then do so. If not, then leave it at its default value.
+
+
+Merging and Premultiplication Do's and Dont's
+---------------------------------------------
+The following rules apply to any merging operation:
+
+**Don't color correct premultiplied images**
+
+Color correction should not be done on images that are premultiplied.
+To un-premultiply you may use an Unpremult node, or use the (un)premult option within the node.
+
+**Don't composite pre-multiplied images**
+
+Don't composite a FG that is not pre-multiplied
+
+**Don't Double pre-multiplication**
+
+Do not apply premultiplication twice in a row to the same image. It can damage the edges of the alpha.
+
+**Donʼt use the composite image that comes out of a keyer**
+
+Most high end keyers output a composite image (the foreground over the background). generally, this should not be used, as no color corrections can be done to the foreground. Better instead to use the keyer's alpha channel ina merging operation further down the node tree.
+
+
+
+
+
+
+
+
+
+
+
+

Documentation/source/guide/tutorials-imagesequence.rst

@@ -1,6 +1,11 @@
 .. for help on writing/extending this file, see the reStructuredText cheatsheet
    http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
 
+
+.. _tutorials-imagesequence:
+
+
+
 How To Convert Videos To Image Sequences
 ========================================
 

Documentation/source/guide/tutorials.rst

@@ -14,4 +14,4 @@ Tutorials
    tutorials-hugin
    tutorials-svgworkflow
    tutorials-AlternativeMatteExtraction
-
+   tutorials-evaluating-script-structure