10 files changed, 1042 insertions, 0 deletions

diff --git a/docs/userguide/baking_luts.rst b/docs/userguide/baking_luts.rst
new file mode 100644
index 0000000..7085bf5
--- /dev/null
+++ b/docs/userguide/baking_luts.rst
@@ -0,0 +1,359 @@
+.. _userguide-bakelut:
+
+Baking LUT's
+============
+
+Sometimes it is necessary to write a color transform as a
+lookup-table file
+
+This is usually because an application does not natively support OCIO
+(unlike, say, Nuke which various OCIO nodes), but can load a LUT of
+some kind. This would currently include applications like Autodesk
+Flame, Adobe Photoshop, SideFX's MPlay (Houdini's "Image Viewer")
+
+Remember that baking a LUT is not a perfect solution. Different LUT
+formats have various limitations. Certain applications might apply
+LUT's differently (often incorrectly), and some formats simply cannot
+accurately represent certain transforms. Others might require
+carefully selecting shaper spaces and so on.
+
+Be sure to carefully test the generated LUT in the target
+application. Burning the LUT into a test image (such as Marcie!), and
+carefully comparing to a reference is often the only way to be sure a
+LUT is correct.
+
+Config-based baking
+*******************
+
+This section assumes you have a working OCIO config.
+
+The config can either be specified by setting the OCIO environment variable::
+
+    bash$ export OCIO=~/path/to/spi-vfx/config.ocio
+
+Alternatively the config can be specified as a command-line argument
+to the ociobakelut command, ``--iconfig ~/path/to/spi-vfx/config.ocio``
+
+These examples will use the :ref:`config-spivfx` config, specifically the
+following colorspaces
+
+* ``lnf`` - scene-referred linear light colorspace (reference colorspace)
+* ``lg10`` - film log colorspace (0-1 colorspace)
+* ``srgb8`` - sRGB display colorspace
+
+Remember these are just for the examples - you can of course use any
+config and any colorspaces
+
+Log-input display LUT
++++++++++++++++++++++
+
+Say we have a ``lg10`` image in MPlay (maybe a ".cin" film scan), and
+wish to view it in our main display colorspace, ``srgb8``
+
+The available formats are listed in the ``ociobakelut --help`` - for
+MPlay, we use the "houdini" format (see :ref:`the FAQ<faq-supportedlut>`
+for a more detailed list)
+
+So, to create a LUT that transforms from ``lg10`` to ``srgb8``::
+
+    bash$ ociobakelut --format houdini --inputspace lg10 --outputspace srgb8 log_to_display.lut
+
+We could then load this LUT into MPlay and view a lg10 image
+correctly! (note that by MPlay tries to linearise ".cin" files by
+default, which can be disabled in the preferences, "Convert form 10bit
+Log")
+
+For most other applications, we could simply change the ``--format``
+
+Shaper spaces
++++++++++++++
+
+Before we create a LUT to view linear-light images, it's important to
+understand shaper-spaces and preluts.
+
+The two main types of LUT's are 1D and 3D. Such LUT formats typically
+require input values in the 0.0-1.0 range. Such a LUT would be
+unsuitable for linear-light values input images (where values are
+often over 1)
+
+To address this, various LUT formats contain a smaller "prelut" (or
+"shaper LUT") which is applied before the main LUT. This is used to
+transform the input values into a 0-1 range (typically a linear-to-log
+type transform)
+
+In terms of color-transforms, the prelut transforms from
+"input-space" to "shaper-space", then the main LUT transforms from
+"shaper-space" to "output-space"
+
+Some formats do not support such a shaper LUT - these are typically
+used in applications which do not work with floating-point images (e.g
+Lustre often works with 10-bit integer DPX's, so it's natively
+supported "--format lustre" (3DL) format has no need for a prelut)
+
+
+Linear-light input display LUT
+++++++++++++++++++++++++++++++
+
+With shaper-spaces explained, lets say we have a ``lnf`` linear light
+image in MPlay, and wish to view it in the ``srgb8`` colorspace.
+
+To create this LUT accurately, without clipping, we will use the LUT's
+prelut to transform from ``lnf`` to ``lg10``, then the 3D LUT will
+transform from ``lg10`` to ``srgb8``
+
+Sounds complicated, but the command is almost the same as before, just
+with the ``--shaperspace`` argument (and ``--inputspace`` changed, of
+course)::
+
+    bash$ ociobakelut --format houdini --inputspace lnf --shaperspace lg10 --outputspace srgb8 lin_to_display.lut
+
+Allocation-based prelut
++++++++++++++++++++++++
+
+If your :ref:`allocation variables<allocationvars>` are setup
+correctly, you can omit the ``--shaperspace`` argument, and a prelut
+will be automatically created based on the allocation vars (see the
+linked page for more information)
+
+Since the colorspaces in the config we are using (:ref:`config-spivfx`) have
+their allocation variables set correctly, we could simplify the
+``lnf`` to ``srgb8`` bake command::
+
+    bash$ ociobakelut --format houdini --inputspace lnf --outputspace srgb8 lin_to_display_allocbased.lut
+
+This command creates a very different prelut to the explicitly
+specified ``--shaperspace lg10`` in the previous example. Explicitly
+specifying a shaper can produce better results, however the
+allocation-based prelut usually works nicely, and is convinient
+
+Note that allocation-var based preluts is baker-format dependant, and
+not all formats currently implement them
+
+
+Config-free baking
+******************
+
+You can perform baking without using a OCIO config. This means you
+don't have to create a temporary config just to, say, convert from one
+LUT format to another.
+
+Converting between formats
+++++++++++++++++++++++++++
+
+Say we have a houdini LUT named ``log_to_display.lut``. To convert
+this to a Flame compatible 3dl file, simply run::
+
+    ociobakelut --format flame --lut log_to_display.lut for_flame.3dl
+
+
+Reversing a 1D LUT
+++++++++++++++++++
+
+You can apply a LUT in reverse, and write this to a new LUT (this does
+not work for 3D LUT's, but will for 1D LUT's)::
+
+    bash$ ociobakelut --format flame --invlut logtosrgb.3dl srgbtolog.3dl
+
+Creating a grade LUT
+++++++++++++++++++++
+
+You can create a LUT which applies CDL-compliant grades::
+
+    ociobakelut --format cinespace --slope 1.2 1.0 0.9 mygrade.csp
+
+Combining options
++++++++++++++++++
+
+These options can be used together, or used multiple times.
+
+For example, to perform a slope offset, then apply "mylut.csp", saving
+it out for Lustre::
+
+    bash$ ociobakelut --format lustre --slope 2.0 1.5 0.4 --lut mylut.csp output.3dl
+
+
+ICC profiles (Photoshop)
+************************
+
+Photoshop is very focused around print and graphic-design, industries
+with very different color management concerns to modern feature-film
+VFX. As such, it can be a pain to integrate.
+
+The main issue is current versions of Photoshop (CS5) are only
+practical for working with 16-bit integer images (not floating
+point/linear-light images as is common in compositing software)
+
+The second issue is there is no simple way to load a simple 1D or 3D
+LUT into Photoshop (and it's API does not make this easy either!)
+
+A working space
++++++++++++++++
+
+First, we need to decide on a colorspace to use for the images in
+Photoshop. This is the colorspace in which matte-paintings will be
+performed (likely a different colorspace that used for
+texture-painting, as these have different requirements)
+
+The working space should be a "0-1 colorspace", reversable, and for
+matte-paintings ideally allow painting values over "diffuse white" (in
+other words, to paint values over 1.0 when converted to linear-light
+in comp)
+
+This is a facility-dependant workflow choice.
+
+For this example we will use the ``vd16`` colorspace, as described by
+the :ref:`config-spivfx`
+
+Creating display LUT
+++++++++++++++++++++
+
+"Proofing profiles" in Photoshop can be used in a very similar way to
+a display LUT in applications like Nuke. This proof-profile can be
+used to apply a 3D color transform from the working-space to a
+display space (e.g transform from ``vd16`` to ``srgb8`` in the spi-vfx
+config)
+
+These proofing-profiles are ICC profiles - a rather print-specific
+technology and relatively complex format 
+
+Luckily, ``ociobakelut`` can be used to create these... but, first,
+there are some important considerations:
+
+It is important to match the ``--displayicc`` option to the profile
+used for the display.
+
+Secondly, Photoshop has a lot of print-focused color-management
+options, some of which can cause problems.
+
+Determine display ICC
++++++++++++++++++++++
+
+On OS X, launch "System Preferences", open "Displays" and click
+"Color" tab. The currently active ICC profile is selected.
+
+If you just want something simple that "probably matches" a Linux
+machine, say, it is easiest to uncheck "Show profiles for this display
+only" and select the "sRGB IEC61966-2.1" profile. You can skip the
+rest of this section in this case.
+
+.. figure::  images/ps_icc/psicc_open_current_profile.png
+    :align:   center
+
+However, if you have a specific display-profile selected (maybe
+created by monitor-calibration software), you should do the following:
+
+Click "Open Profile", and right-click the icon in the top of the window, and click the folder:
+
+.. figure::  images/ps_icc/psicc_reveal_profile.png
+    :align:   center
+
+This reveals the current profile in Finder. You can drag the file onto
+a Terminal.app window to get the full path (or, type it manually)
+
+.. TODO: Is there a standard way to find this on Windows?
+
+Create the ICC profile
+++++++++++++++++++++++
+
+Almost done now. We can write the ICC profile!
+
+The full command is, using our example colorspaces of ``vd16`` and ``srgb8``::
+
+    bash$ ociobakelut --format icc --inputspace vd16 --outputspace srgb8 --displayicc /path/to/my/monitorprofile.icc --description "vd16 to srgb8"
+
+
+The first three options are the same as any other LUT::
+
+    bash$ ociobakelut --format icc --inputspace vd16 --outputspace srgb8 [...]
+
+Then we specify the display ICC profile::
+
+    [...] --displayicc /path/to/my/monitorprofile.icc [...]
+
+We can set the description (shown in Photoshop), and as the last argument, specify::
+
+    [...] --description "vd16 to srgb8"  [...]
+
+Finally an argument for the output file:
+
+    [...] vd16_to_srgb.icc
+
+
+If you selected the "sRGB IEC61966-2.1" display profile, you can omit
+the ``--displayicc`` argument (it defaults to an standard sRGB
+profile)::
+
+    bash$ ociobakelut --format icc --inputspace vd16 --outputspace srgb8 --description "vd16 to srgb8"
+
+Loading the "display LUT"
++++++++++++++++++++++++++
+
+Last step is to load the ICC profile into Photoshop, and enable it.
+
+On OS X, these can be put into::
+
+    /Library/ColorSync/Profiles/
+
+(or the equivelant directory in your home-directory)
+
+On Windows, right-click the profile and select "Install profile"
+
+
+Then on either platform, click "View > Proof Setup > Custom..."
+
+.. figure::  images/ps_icc/psicc_proof_setup.png
+    :align:   center
+
+Select your profile from the "Device to simulate" dropdown (the name
+is what you supplied with ``--description``):
+
+.. figure::  images/ps_icc/psicc_select_profile.png
+    :align:   center
+
+As pictured, selecting "Preserve RGB numbers", and deselecting
+"Simulate Black Ink" is a good starting point (see the next section on
+"Other color settings")
+
+Finally, you can load an image in your working space, and click "View
+> Proof Colors", or hit cmd+y (or ctrl+y)
+
+When active, the profile name is shown in the window title (e.g
+".... (RGB/16#/vd16 to srgb8", where the part after the "#/" is the
+profile name, "RGB/16" indicates the current image mode)
+
+Other color settings
++++++++++++++++++++++
+
+(note this guide is based on Photoshop CS5, and written while checking
+the OS X version, although most of these apply similarly on Windows 7)
+
+It is usually possible to get a matte-painting to look identical in
+Photoshop as it does in a more VFX-friendly application such as Nuke.
+
+However, as mentioned Photoshop has a lot of color-management related
+options, many of which can impair the match between it and other
+applications. The operating system also has some controls (as seen
+before with the ColorSync display profile)
+
+The settings that require tweaking have a tendency to change with OS
+versions, Photoshop versions and the phase of the moon. The only way
+to be sure is to compare Photoshop side-by-side with a
+LUT-reference-image (ideally toggling between Photoshop and Nuke):
+
+.. figure::  images/ps_icc/psicc_itworks.png
+    :align:   center
+
+
+The most improtant settings are in the "View > Proof Setup > Custom
+..." menu.
+
+The recommended "Preserve RGB" setting works sometimes. Other times
+disabling "Preserve RGB Numbers" and selecting "Rendering Intent:
+Relative Colorimetric" can be closer.
+
+It is safest to not assign a profile to the images you are working
+on - this is done by clicking "Edit > Assign Profile", and selecting
+"Don't Color Manage This Document".
+
+In closing, of course none of this matters if you don't have a
+calibrated monitor!
diff --git a/docs/userguide/contexts.rst b/docs/userguide/contexts.rst
new file mode 100644
index 0000000..262f158
--- /dev/null
+++ b/docs/userguide/contexts.rst
@@ -0,0 +1,361 @@
+Contexts
+========
+
+OCIO's allows different LUT's or grades to be applied based on the
+current context.
+
+These contexts are usually based on environment variables, but also
+allows on-the-fly context switching in applications that operate on
+multiple shots (such as playback tools)
+
+Typically these would be used as part of the display transform, to
+apply shot-specific looks (such as a CDL color correction, or a 1D
+grade LUT)
+
+
+.. _context_per_shot_luts:
+
+A contrived example
+*******************
+
+The simplest way to explain this feature is with examples. Say we have
+two shots, ``ab-123`` and ``sf-432``, and each shot requires a
+different LUT to view. The current shot name is stored in the
+environment variable SHOT.
+
+In the OCIO config, you can use this SHOT environment variable to
+construct the LUT's path/filename. This path can be absolute (e.g
+``/example/path/${SHOT}.spi1d``), or relative to any directory on the
+OCIO search path, which includes the resource path (e.g
+``${SHOT}.spi1d``)
+
+This is a simplified example, to demonstrate the context
+feature. Typically this "contextual LUT" would be used in conjuction
+with other LUT's (e.g before a scene-linear to log transform, followed
+by a 3D film emulation LUT), this will be covered in
+:ref:`context_per_shot_grade`
+
+So, we have our empty OCIO config in ``~/showcfg``, and our two LUTs
+in ``~/showcfg/luts`` which are named ``af-123.spi1d`` and
+``sf-432.spi1d``::
+
+    ~/showcfg/
+        config.ocio
+        luts/
+            af-123.spi1d
+            sf-432.spi1d
+
+In the config, we first specify the config version, and the resource
+path (usually this is relative to the directory containing
+``config.ocio``, although can be an absolute path)::
+
+    ocio_profile_version: 1
+    resource_path: luts
+
+Next, we define a colorspace that transforms from the show reference
+space to the display colorspace:
+
+.. code-block:: yaml
+
+    colorspaces:
+      - !<ColorSpace>
+        name: srgb8
+        family: srgb
+        bitdepth: 8ui
+        from_reference: !<FileTransform> {src: ${SHOT}.spi1d}
+
+Then add a display alias for this transform:
+
+.. code-block:: yaml
+
+    displays:
+      - !<Display> {device: sRGB, name: "Shot LUT", colorspace: srgb8}
+
+
+Finally, we point the OCIO env-variable to the config, set the SHOT
+env-variable to the shot being worked on, and launch Nuke (or any
+other OCIO-enabled application)::
+
+    export OCIO=~/showcfg/config.ocio
+    export SHOT=af-123
+    nuke
+
+In Nuke, we create an OCIODisplay node, select our "sRGB" device with
+the "Shot LUT" transform, and this will apply the ``af-123.spi1d``
+LUT.
+
+.. _context_per_shot_grade:
+
+Per-shot grades
+***************
+
+Similarly to LUTs, we use a ``.cc`` file (an XML file containing a
+single ASC CDL ``<ColorCorrection>``), or a ``.ccc`` file (an XML file
+containing multiple ASC CDL color corrections, each with a unique ID)
+
+The ``.cc`` file is applied identically to a regular LUT files, using
+a ``FileTransform``. For example, if we have ``af-123.cc`` in the
+``luts/`` directory:
+
+.. code-block:: xml
+
+    <ColorCorrection id="mygrade">
+            <SOPNode>
+                 <Slope>2 1 1</Slope>
+                 <Offset>0 0 0</Offset>
+                 <Power>1 1 1</Power>
+            </SOPNode>
+            <SATNode>
+                 <Saturation>1</Saturation>
+            </SATNode>
+      </ColorCorrection>
+
+
+We wish to apply this grade on the scene-linear image, then transform
+into log and apply a 3D print emulation LUT. Since this requires
+multiple transforms, instead of using a single ``FileTransform``, we
+use a ``GroupTransform`` (which is is just a collection of other
+transforms):
+
+.. code-block:: yaml
+
+    colorspaces:
+      - !<ColorSpace>
+        name: lnh
+        family: ln
+        bitdepth: 16f:
+        isdata: false
+
+      - !<ColorSpace>
+        name: lg10
+        family: lg
+        bitdepth: 10ui
+        isdata: false
+        to_reference: !<FileTransform> {src: lg10.spi1d, interpolation: nearest}
+
+      - !<ColorSpace>
+        name: srgb8
+        family: srgb
+        bitdepth: 8ui
+        isdata: false
+        from_reference: !<GroupTransform>
+          children:
+            - !<FileTransform> {src: ${SHOT}.cc}
+            - !<ColorSpaceTransform> {src: lnh, dst: lg10}
+            - !<FileTransform> {src: film_emulation.spi3d, interpolation: linear}
+
+A .ccc file is a collection of ``<ColorCorrection>``'s. The only
+difference is when defining the ``FileTransform``, you must specify
+the ``cccdid`` key, which you can also construct using the context's
+environment variables. This means we could create a ``grades.ccc``
+file containing the grade for all our shots:
+
+.. code-block:: xml
+
+    <ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2">
+          <ColorCorrection id="af-123">
+                  <SOPNode>
+                       <Slope>2 1 1</Slope>
+                       <Offset>0 0 0</Offset>
+                       <Power>1 1 1</Power>
+                  </SOPNode>
+                  <SATNode>
+                       <Saturation>1</Saturation>
+                  </SATNode>
+            </ColorCorrection>
+            <ColorCorrection id="mygrade">
+                    <SOPNode>
+                         <Slope>0.9 0.7 0.9</Slope>
+                         <Offset>0 0 0</Offset>
+                         <Power>1 1 1</Power>
+                    </SOPNode>
+                    <SATNode>
+                         <Saturation>1</Saturation>
+                    </SATNode>
+              </ColorCorrection>
+    </ColorCorrectionCollection>
+
+And the colorspace definition to utilise this:
+
+.. code-block:: yaml
+
+    - !<ColorSpace>
+      name: srgb8
+      family: srgb
+      bitdepth: 8ui
+      isdata: false
+      from_reference: !<GroupTransform>
+        children:
+          - !<FileTransform> {src: grades.ccc, cccid: ${SHOT}}
+          - !<ColorSpaceTransform> {src: lnh, dst: lg10}
+          - !<FileTransform> {src: film_emulation.spi3d, interpolation: linear}
+
+
+.. _context_complete_example:
+
+A complete example
+******************
+
+.. warning::
+    This is incomplete, the lnh_graded space is likely wrong
+
+The context feature can be used to accommodate complex grading
+pipelines. In this example, we have a "neutral grade" for each shot,
+to neutralise color casts and exposure variations, keeping plates
+consistent throughout a sequence.
+
+To view a shot, we reverse this neutral grade, apply a "beauty grade",
+then apply the display transform (the usual lin-to-log and a film
+emulation LUT)
+
+We will use the same two example shots from before, af-123 (which is
+in the af sequence) and sg-432 (in the sg sequence). Imagine we have
+many shots in each sequence, so we wish to put the grades for each
+sequence in a separate file.
+
+Using the same directory structure as above, in ``~/showcfg/luts`` we
+first create two grade files, ``grades_af.ccc``:
+
+.. code-block:: xml
+
+    <ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2">
+          <ColorCorrection id="af/af-123/neutral">
+                  <SOPNode>
+                       <Slope>2 1 1</Slope>
+                       <Offset>0 0 0</Offset>
+                       <Power>1 1 1</Power>
+                  </SOPNode>
+                  <SATNode>
+                       <Saturation>1</Saturation>
+                  </SATNode>
+            </ColorCorrection>
+            
+          <ColorCorrection id="af/af-123/beauty">
+                  <SOPNode>
+                       <Slope>1.5 1.2 0.9</Slope>
+                       <Offset>0 0 0</Offset>
+                       <Power>1 1 1</Power>
+                  </SOPNode>
+                  <SATNode>
+                       <Saturation>0.8</Saturation>
+                  </SATNode>
+            </ColorCorrection>
+
+            <!-- More ColorCorrection's... -->
+    </ColorCorrectionCollection>
+
+
+And ``grades_sg.ccc``:
+
+.. code-block:: xml
+
+    <ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2">
+            <ColorCorrection id="sg/sg-432/neutral">
+                    <SOPNode>
+                         <Slope>0.9 0.7 0.9</Slope>
+                         <Offset>0 0 0</Offset>
+                         <Power>1 1 1</Power>
+                    </SOPNode>
+                    <SATNode>
+                         <Saturation>1</Saturation>
+                    </SATNode>
+              </ColorCorrection>
+              
+            <ColorCorrection id="sg/sg-432/beauty">
+                    <SOPNode>
+                         <Slope>1.1 0.9 0.8</Slope>
+                         <Offset>0 0 0</Offset>
+                         <Power>1.2 0.9 1.5</Power>
+                    </SOPNode>
+                    <SATNode>
+                         <Saturation>1</Saturation>
+                    </SATNode>
+              </ColorCorrection>
+
+              <!-- More ColorCorrection's.. -->
+    </ColorCorrectionCollection>
+    
+
+Next, we create the ``config.ocio`` file, containing a colorspace to
+define several colorspaces:
+
+* ``lnh``, the scene-linear, 16-bit half-float space in which
+  compositing will happen
+
+* ``lg10``, the 10-bit log space in which material will be received
+  (e.g in .dpx format)
+
+* ``srgb8``, the display colorspace, for viewing the neutrally graded
+  footage on an sRGB display
+
+* ``srgb8graded``, another display colorspace, for viewing the final
+  "beauty grade"
+
+
+.. code-block:: yaml
+
+    ocio_profile_version: 1
+
+    # The directory relative to the location of this config
+    resource_path: "luts"
+
+    roles:
+      scene_linear: lnh
+      compositing_log: lgf
+
+    displays:
+      # Reference to display transform, without reversing the working grade
+      - !<Display> {device: sRGB, name: Film1D, colorspace: srgb8}
+
+      # Reference to display, reversing the working grade, and applying
+      # the beauty grade
+      - !<Display> {device: sRGB, name: Film1DGraded, colorspace: srgb8graded}
+
+    colorspaces:
+
+      # The source space, containing a log to scene-linear LUT
+      - !<ColorSpace>
+        name: lg10
+        family: lg
+        bitdepth: 10ui
+        isdata: false
+        to_reference: !<FileTransform> {src: lg10.spi1d, interpolation: nearest}
+
+      # Our scene-linear space (reference space)
+      - !<ColorSpace>
+        name: lnh
+        family: ln
+        bitdepth: 16f
+        isdata: false
+
+      # Neutrally graded scene-linear
+      - !<ColorSpace>
+        name: lnh_graded
+        family: ln
+        bitdepth: 16f
+        isdata: false
+        to_reference: !<FileTransform> {src: "grades_${SEQ}.ccc", cccid: "${SEQ}/${SHOT}/neutral"}
+          
+
+      # The display colorspace - how to get from scene-linear to sRGB
+      - !<ColorSpace>
+        name: srgb8
+        family: srgb
+        bitdepth: 8ui
+        isdata: false
+        from_reference: !<GroupTransform>
+          children:
+            - !<ColorSpaceTransform> {src: lnh, dst: lg10}
+            - !<FileTransform> {src: lg_to_srgb.spi3d, interpolation: linear}
+
+      # Display color, with neutral grade reversed, and beauty grade applied
+      - !<ColorSpace>
+        name: srgb8graded
+        family: srgb
+        bitdepth: 8ui
+        isdata: false
+        from_reference: !<GroupTransform>
+          children:
+            - !<FileTransform> {src: "grades_${SEQ}.ccc", cccid: "${SEQ}/${SHOT}/neutral", direction: inverse}
+            - !<FileTransform> {src: "grades_${SEQ}.ccc", cccid: "${SEQ}/${SHOT}/beauty", direction: forward}
+            - !<ColorSpaceTransform> {src: lnh, dst: srgb8}
diff --git a/docs/userguide/images/ps_icc/psicc_itworks.png b/docs/userguide/images/ps_icc/psicc_itworks.png
new file mode 100644
index 0000000..242db00
--- /dev/null
+++ b/docs/userguide/images/ps_icc/psicc_itworks.png
diff --git a/docs/userguide/images/ps_icc/psicc_open_current_profile.png b/docs/userguide/images/ps_icc/psicc_open_current_profile.png
new file mode 100644
index 0000000..1654ae6
--- /dev/null
+++ b/docs/userguide/images/ps_icc/psicc_open_current_profile.png
diff --git a/docs/userguide/images/ps_icc/psicc_proof_setup.png b/docs/userguide/images/ps_icc/psicc_proof_setup.png
new file mode 100644
index 0000000..179eb8e
--- /dev/null
+++ b/docs/userguide/images/ps_icc/psicc_proof_setup.png
diff --git a/docs/userguide/images/ps_icc/psicc_reveal_profile.png b/docs/userguide/images/ps_icc/psicc_reveal_profile.png
new file mode 100644
index 0000000..07ad56c
--- /dev/null
+++ b/docs/userguide/images/ps_icc/psicc_reveal_profile.png
diff --git a/docs/userguide/images/ps_icc/psicc_select_profile.png b/docs/userguide/images/ps_icc/psicc_select_profile.png
new file mode 100644
index 0000000..06fecef
--- /dev/null
+++ b/docs/userguide/images/ps_icc/psicc_select_profile.png
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
new file mode 100644
index 0000000..256d89d
--- /dev/null
+++ b/docs/userguide/index.rst
@@ -0,0 +1,15 @@
+.. _user-guide:
+
+User Guide
+==========
+
+These guides will focus on a specific task (for example, writing a basic config, or setting up per-shot LUT's).
+For a "broader picture" expiation of how to use OCIO, see the :ref:`configurations` section
+
+.. toctree::
+    :maxdepth: 2
+
+    tool_overview
+    baking_luts
+    contexts
+    looks
diff --git a/docs/userguide/looks.rst b/docs/userguide/looks.rst
new file mode 100644
index 0000000..591d835
--- /dev/null
+++ b/docs/userguide/looks.rst
@@ -0,0 +1,139 @@
+Looks
+=====
+
+A "look" is a named color transform, intended to modify the look of an
+image in a "creative" manner (as opposed to a colorspace definion
+which tends to be technically/mathematically defined)
+
+Examples of looks may be a neutral grade, to be applied to film scans
+prior to VFX work, or a per-shot DI grade decided on by the director,
+to be applied just before the viewing transform
+
+Looks are defined similarly to colorspaces, you specify a name and a
+transform (possibly a GroupTransform containing several other
+transforms), and optionally an inverse transform.
+
+Where looks differ from colorspace definions are in how they are
+applied. With a look, you also specify the "process space" - the
+colorspace in which the transform is applied.
+
+Example configuration
+*********************
+
+Step 1: Setup a Look
+
+A look is a top-level OCIO configuration object. Conceptually, it's a
+named transform which gets applied in a specific color space. All of the
+changes below to the .ocio configs can be done manually by editing the
+text, or using the Python API.
+
+Example look definition in a OCIO config:
+
+.. code-block:: yaml
+
+    looks:
+    - !<Look>
+      name: di
+      process_space: rclg16
+      transform: !<FileTransform> {src: look_di.cc, interpolation: linear}
+
+
+The src file can be any LUT type that OCIO supports (in this case, it's a
+file that contains the ``<ColorCorrection>`` element from a CDL file.) You
+could also specify a .3dl, etc.
+
+Once you define a look in your configuration, you'll see that the
+``OCIOLookTransform`` node in Nuke will provide the named option. In
+this example, the 'DI' look conceptually represents a look that will
+be applied in DI. Other look names we often used are 'onset',
+'editorial', etc.  The ``process_space`` specifies that the transform
+should be applied in that space. In this example, if you provide
+linear input to the ``OCIOLookTransform`` node, the pixels will be
+converted to ``rclg16`` before applying the ``look_di.cc``
+file-transform.
+
+Step 2: Update the Display to use a look.
+
+You can specify an optional 'looks' tag in the View tag, which will
+apply the specified look(s). This lets application in the viewer
+provide options which use the looks.
+
+Example:
+
+.. code-block:: yaml
+
+    displays:
+      DLP:
+        - !<View> {name: Raw, colorspace: nc10}
+        - !<View> {name: Log, colorspace: rclg10}
+        - !<View> {name: Film, colorspace: p3dci16}
+        - !<View> {name: Film DI, colorspace: p3dci16, looks: di}
+      sRGB:
+        - !<View> {name: Raw, colorspace: nc10}
+        - !<View> {name: Log, colorspace: rclg10}
+        - !<View> {name: Film, colorspace: srgb10}
+        - !<View> {name: Film DI, colorspace: srgb10, looks: di}
+
+
+Option for advanced users: The looks tag is actually a comma-delimited
+list supporting +/- modifiers. So if you you wanted to specify a View
+that undoes DI, and then adds Onset, you could do "-di,+onset".
+
+Step 3: Get per-shot looks supported.
+
+In the top example, look_di.cc, being a relative path location, will check
+each location in the config's search_path. The first file that's found
+will be used.
+
+So if your config contains::
+
+    search_path: luts
+
+... then only the 'luts' subdir relative to the OCIO config will be
+checked.
+
+However if you specify::
+
+    search_path: /shots/show/$SHOT/cc/data:luts
+
+...the directory '/shots/show/$SHOT/cc/data/' will be evaluated first,
+and only if not found will the 'luts' directory be checked.
+
+env-vars, absolute, and relative paths can be used both in the config's
+``search_path``, as well as the View's src specification.
+
+Example:
+
+.. code-block:: yaml
+
+    - !<Look>
+      name: di
+      process_space: rclg16
+      transform: !<FileTransform> {src: looks/$SHOT_di/current/look_$SHOT_di.cc, interpolation: linear}
+
+
+Note that if the per-shot lut is not found, you can control whether a
+fallback LUT succeeds based on if it's in the master location. You can
+also use this for multiple levels (show, shot, etc).
+
+Advanced option: If some shots use .cc files, and some use 3d-luts
+currently there's no simple way to handle this. What we'd recommend as a
+work around is to label all of your files with the same extension (such as
+.cc), and then rely on OCIO's resiliance to misnamed lut files to just load
+them anyways. Caveat: this only works in 1.0.1+ (commit sha-1: 6da3411ced)
+
+Advanced option: In the Nuke OCIO nodes, you often want to preview
+looks 'across shots' (often for reference, same-as, etc). You can
+override the env-vars in each node, using the 'Context' menu. For
+example, if you know that $SHOT is being used, in the context key1 you
+should specify 'SHOT', and the in value1 specify the shot to use (such
+as dev.lookdev). You can also use expressions, to say parse a shot
+name out of ``[metadata "input/filename"]``
+
+Advanced option: If you are writing your own OCIO integration code,
+``getProcessor`` will fail if the per-shot lut is not found, and you
+may want to distinguish this error from other OCIO errors. For this
+reason, we provide OCIO::ExceptionMissingFile, which can be explicitly
+caught (this can then handled using
+``OCIO::DisplayTransform::setLooksOverride()``). I'd expect image
+flipbook applications to use this approach.
diff --git a/docs/userguide/tool_overview.rst b/docs/userguide/tool_overview.rst
new file mode 100644
index 0000000..f9ac0e4
--- /dev/null
+++ b/docs/userguide/tool_overview.rst
@@ -0,0 +1,168 @@
+.. _userguide-tooloverview:
+
+Tool overview
+=============
+
+OCIO is comprised of many parts. At the lowest level there is the C++ API.
+This API can be used in applications and plugins
+
+Note that all these plugins use the same config file to define color spaces,
+roles and so on. For information on setting up configurations, see 
+:ref:`configurations`
+
+The API
+*******
+
+Most users will never directly interact with the C++ API. However the API is used by all the supplied applications (e.g :ref:`overview-ocio2icc`) and plugins (e.g 
+the :ref:`overview-nukeplugins`)
+
+To get started with the API, see the :ref:`developer-guide`
+
+.. _overview-ociocheck:
+
+ociocheck
+*********
+
+This is a command line tool which shows an overview of an OCIO config
+file, and check for obvious errors
+
+For example, the following shows the output of a config with a typo -
+the colorspace used for ``compositing_log`` is not incorrect::
+
+    $ ociocheck --iconfig example.ocio
+
+    OpenColorIO Library Version: 0.8.3
+    OpenColorIO Library VersionHex: 525056
+    Loading example.ocio
+
+    ** General **
+    Search Path: luts
+    Working Dir: /tmp
+
+    Default Display: sRGB
+    Default View: Film
+
+    ** Roles **
+    ncf (default)
+    lnf (scene_linear)
+    NOT DEFINED (compositing_log)
+
+    ** ColorSpaces **
+    lnf
+    lgf
+    ncf
+    srgb8 -- output only
+
+    ERROR: Config failed sanitycheck. The role 'compositing_log' refers to a colorspace, 'lgff', which is not defined.
+
+    Tests complete.
+
+It cannot verify the defined color transforms are "correct", only that the
+config file can be loaded by OCIO without error.
+
+As with all the OCIO command line tools, you can use the `--help` argument to
+read a description and see the other arguments accepted::
+
+    $ ociocheck --help
+    ociocheck -- validate an OpenColorIO configuration
+
+    usage:  ociocheck [options]
+
+        --help        Print help message
+        --iconfig %s  Input .ocio configuration file (default: $OCIO)
+        --oconfig %s  Output .ocio file
+
+
+.. _overview-ociobakelut:
+
+ociobakelut
+************
+
+A command line tool which bakes a color transform into various color
+lookup file formats ("a LUT")
+
+This is intended for applications that have not directly integrated
+OCIO, but can load LUT files
+
+If we want to create a ``lnf`` to ``srgb8`` viewer LUT for Houdini's
+MPlay::
+
+    $ ociobakelut --inputspace scene_linear --shaperspace lg10 --outputspace srgb8 --format houdini houdini__lnf_to_lg10_to_srgb8.lut
+
+The ``--inputspace`` and ``-outputspace`` options specify the
+colorspace of the input image, and the displayed image.
+
+Since a 3D LUT can only practically operate on 0-1 (e.g a Log image),
+the ``--shaperspace`` option is specified. This uses the Houdini LUT's
+1D "pretransform" LUT to do "lnf" to "lg10", then the 3D LUT part to
+go from "lg10" to "srgb8" (basically creating a single file containing
+a 1D linear-to-log LUT, and a 3D log-to-sRGB LUT)
+
+To make a log to sRGB LUT for Flame, the usage is similar, except the
+shaperspace option is omitted, as the input colorspace does not have
+values outside 0.0-1.0 (being a Log space)::
+
+    $ ociobakelut --inputspace lg10 --outputspace srgb8 --format flame flame__lg10_to_srgb.3dl
+
+See the :ref:`faq-supportedlut` section for a list of formats that
+support baking
+
+.. TODO: For more information on baking LUT's, see :ref:`userguide-bakelut`
+
+
+.. _overview-ocio2icc:
+
+ocio2icc
+********
+
+A command line tool to generate an ICC "proofing" profile from a color space
+transform, which can be used in applications such as Photoshop.
+
+A common workflow is for matte-painters to work on sRGB files in Photoshop. An
+ICC profile is used to view the work with the same film emulation transform as
+used in other departments.
+
+.. TODO: Link to more elaborate description
+
+
+.. _overview-ocioconvert:
+
+ocioconvert
+***********
+
+Loads an image, applies a color transform, and saves it to a new file.
+
+OpenImageIO is used to open and save the file, so a wide range of formats are supported.
+
+.. TODO: Link to more elaborate description
+
+
+.. _overview-ociodisplay:
+
+ociodisplay
+***********
+
+A basic image viewer. Uses OpenImageIO to load images, and displays them using OCIO and typical viewer controls (scene-linear exposure control and a post-display gamma control)
+
+May be useful to users to quickly check colorspace configuration, but
+primarily a demonstration of the OCIO API
+
+.. TODO: Link to more elaborate description
+
+
+.. _overview-nukeplugins:
+
+Nuke plugins
+************
+
+A set of OCIO nodes for The Foundry's Nuke, including:
+
+* OCIOColorSpace, transforms between two color spaces (similar to the built-in "ColorSpace" node, but the colorspaces are described in the OCIO config file)
+
+* OCIODisplay to be used as viewer processes
+
+* OCIOFileTransform loads a transform from a file (e.g a 1D or 3D LUT), and applies it
+
+* OCIOCDLTransform applies CDL-compliant grades, and includes utilities to create/load ASC CDL files
+
+.. TODO - Link to more elaborate description