diff options
Diffstat (limited to 'docs')
53 files changed, 4175 insertions, 0 deletions
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 0000000..e15db13 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,73 @@ + +############################################################################### +### Create Doc Targets ### + +message(STATUS "Create sphinx conf.py from conf.py.in") +configure_file(${CMAKE_SOURCE_DIR}/docs/conf.py.in + ${CMAKE_BINARY_DIR}/docs/conf.py @ONLY) + +message(STATUS "Copying doc to staging area") +file(COPY ${CMAKE_SOURCE_DIR}/docs/ DESTINATION ${CMAKE_BINARY_DIR}/docs) + +message(STATUS "Copy extra doc files to staging area") +list(APPEND DOCFILES ${CMAKE_SOURCE_DIR}/README) +list(APPEND DOCFILES ${CMAKE_SOURCE_DIR}/INSTALL) +list(APPEND DOCFILES ${CMAKE_SOURCE_DIR}/ChangeLog) +list(APPEND DOCFILES ${CMAKE_SOURCE_DIR}/LICENSE) +list(APPEND DOCFILES ${CMAKE_SOURCE_DIR}/share/nuke/ocionuke/viewer.py) +CopyFiles(RSTDOC ${DOCFILES}) + +message(STATUS "Extracting .rst files from C++ headers") +ExtractRstCPP(${CMAKE_SOURCE_DIR}/export/OpenColorIO/OpenColorIO.h developers/api/OpenColorIO.rst) +ExtractRstCPP(${CMAKE_SOURCE_DIR}/export/OpenColorIO/OpenColorTransforms.h developers/api/OpenColorTransforms.rst) +ExtractRstCPP(${CMAKE_SOURCE_DIR}/export/OpenColorIO/OpenColorTypes.h developers/api/OpenColorTypes.rst) + +add_custom_target(doc ALL + COMMAND PYTHONPATH=${PYTHONPATH} sphinx-build -b html . ${CMAKE_CURRENT_BINARY_DIR}/build-html + DEPENDS + OpenColorIO + PyOpenColorIO + ${CMAKE_BINARY_DIR}/docs/conf.py + developers/api/OpenColorIO.rst + developers/api/OpenColorTransforms.rst + developers/api/OpenColorTypes.rst + ${RSTDOC_OUTPUT} + COMMENT "Building html docs" + SOURCES ${DOCFILES}) + +# note: ExternalProject will not build when added to a add_custom_target this +# works around this problem. This seems to be fixed in the cmake ^HEAD +add_dependencies(doc Sphinx) + +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/build-html/ + DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/OpenColorIO/html + PATTERN .* EXCLUDE +) + +find_package(LATEX) +if(PDFLATEX_COMPILER) + + add_custom_target(latex + COMMAND PYTHONPATH=${PYTHONPATH} sphinx-build -b latex . ${CMAKE_CURRENT_BINARY_DIR}/build-latex + DEPENDS + OpenColorIO + ${CMAKE_BINARY_DIR}/docs/conf.py + developers/api/OpenColorIO.rst + developers/api/OpenColorTransforms.rst + developers/api/OpenColorTypes.rst + ${RSTDOC_OUTPUT} + COMMENT "Building latex doc" + SOURCES ${DOCFILES}) + add_dependencies(latex Sphinx) + + add_custom_target(pdf ALL + COMMAND ${PDFLATEX_COMPILER} OpenColorIO.tex + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/build-latex + COMMENT "Building pdf doc" + SOURCES ${DOCFILES}) + add_dependencies(pdf latex) + + install(FILES ${CMAKE_CURRENT_BINARY_DIR}/build-latex/OpenColorIO.pdf + DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/OpenColorIO/) + +endif() diff --git a/docs/ChangeLog.rst b/docs/ChangeLog.rst new file mode 100755 index 0000000..3ebc244 --- /dev/null +++ b/docs/ChangeLog.rst @@ -0,0 +1,6 @@ +.. _changelog-main: + +ChangeLog +========= + +.. include:: ChangeLog diff --git a/docs/CompatibleSoftware.rst b/docs/CompatibleSoftware.rst new file mode 100644 index 0000000..05845e6 --- /dev/null +++ b/docs/CompatibleSoftware.rst @@ -0,0 +1,268 @@ +.. _compatiblesoftware: + +Compatible Software +=================== + +The following sofware all supports OpenColorIO (to varying degrees). + +If you are interested in getting OCIO support for an application not listed +here, please contact the ocio-dev mailing list. + +If you are a developer and would like assistance integration OCIO into your +application, please contant ocio-dev as well. + + +After Effects +************* + +`Compositor - Adobe <http://www.adobe.com/products/aftereffects.html>`__ + +OpenColorIO nodes are available for use in After Effects. + +See `src/aftereffects +<http://github.com/imageworks/OpenColorIO/tree/master/src/aftereffects>`__ +if you are interested in building your own OCIO plugins. + +Pre-built binaries are also available for `download +<http://www.fnordware.com/OpenColorIO>`__, courtesy of +`fnordware <http://www.fnordware.com>`__. + + +Krita +***** + +`2D Paint - Open Source <http://www.krita.org/>`__ + +Krita now support OpenColorIO for image viewing, allowing for the accurate +painting of float32/OpenEXR imagery. + +See `krita.org +<http://www.krita.org/item/113-krita-starts-supporting-opencolorio>`__ +for details. + + +Silhouette +********** + +`Roto, Paint, Keying - SilhouetteFX <http://www.silhouettefx.com/silhouette>`__ + +OCIO is natively integrated in +`4.5+ <http://www.silhouettefx.com/silhouette/silhouette-4.5-WhatsNew.pdf>`__ +Full support is provide for both image import/export, as well as image display. + + + +Nuke +**** + +`Compositor - The Foundry <http://www.thefoundry.co.uk/products/nuke>`__ + +Nuke 6.3v7+ ships with native support for OpenColorIO. The OCIO configuration +is selectable in the user preferences. + +OCIO Nodes: OCIOCDLTransform, OCIOColorSpace, OCIODisplay, OCIOFileTransform, +OCIOLookConvert, OCIOLogConvert + +The OCIODisplay node is suitable for use in the Viewer as an input process (IP), +and a register function is provides to add viewer options for each display upon +launch. + +The OCIO config "nuke-default" is provided, which matches the built-in Nuke +color processing. This profile is useful for those who want to mirror the native +nuke color processing in other applications. (The underlying equations are +also provided as python code in the config as well). + +A `video demonstration <http://vimeo.com/38773736>`__ of the Nuke OCIO workflow. + +Mari +**** + +`3D Paint - The Foundry <http://www.thefoundry.co.uk/products/mari>`__ + +Mari 1.4v1+ ships with native support for OpenColorIO in their display toolbar. + +A `video demonstration <http://vimeo.com/32909648>`__ of the Mari OCIO workflow. + +Katana +****** + +`CG Pipeline / Lighting Tool - The Foundry <http://www.thefoundry.co.uk/products/katana>`__ + +Color management in Katana (all versions) natively relies on OCIO. + +2D Nodes: OCIODisplay, OCIOColorSpace, OCIOCDLTransform +Monitor Panel: Full OCIO Support + +Hiero +***** + +`Conform & Review - The Foundry <http://www.thefoundry.co.uk/products/hiero>`__ + +Hiero 1.0 will ship with native support for OCIO in the display and the +equivalent of Nuke's OCIOColorSpace in the Read nodes. + +It comes with “nuke-default” OCIO config by default, so the Hiero viewer +matches when sending files to Nuke for rendering. + + +Photoshop +********* +OpenColorIO display luts can be exported as ICC profiles for use in photoshop. +See the ociobakelut details below for additional info. The core idea is to +create an .icc profile, with a valid description, and then to save it to the +proper OS icc directory. (On OSX, ~/Library/ColorSync/Profiles/) Upon a +Photoshop relaunch, Edit->Assign Profile, and then select your new OCIO lut. + + +OpenImageIO +*********** + +`Open Source Image Library / Renderer Texture Engine <http://openimageio.org>`__ + +Available in the current code trunk. Integration is with makecolortx (allowing +for color space conversion during mipmap generation), and also through the +public header `src/include/color.h <http://github.com/OpenImageIO/oiio/blob/master/src/include/color.h>`__ . + +Remaining integration tasks include +`color conversion at runtime <http://github.com/OpenImageIO/oiio/issues/193>`__ . + +C++ +*** +The core OpenColorIO API is avaiable for use in C++. See the `export directory +<http://github.com/imageworks/OpenColorIO/tree/master/export/OpenColorIO>`__ +for the C++ API headers. Minimal code examples are also available in the source +code distribution. Of particular note are apps/ocioconvert and apps/ociodisplay. + +Python +****** +The OpenColorIO API is available for use in python. See the "pyglue" directory +in the codebase. + + +Apps w/icc or luts +****************** +flame (.3dl), lustre (.3dl), cinespace (.csp), houdini (.lut), iridas_itx (.itx) +photoshop (.icc) + +Export capabilities through ociobakelut:: + + $ ociobakelut -- create a new LUT or icc profile from an OCIO config or lut file(s) + $ + $ usage: ociobakelut [options] <OUTPUTFILE.LUT> + $ + $ example: ociobakelut --inputspace lg10 --outputspace srgb8 --format flame lg_to_srgb.3dl + $ example: ociobakelut --lut filmlut.3dl --lut calibration.3dl --format flame display.3dl + $ example: ociobakelut --lut look.3dl --offset 0.01 -0.02 0.03 --lut display.3dl --format flame display_with_look.3dl + $ example: ociobakelut --inputspace lg10 --outputspace srgb8 --format icc ~/Library/ColorSync/Profiles/test.icc + $ example: ociobakelut --lut filmlut.3dl --lut calibration.3dl --format icc ~/Library/ColorSync/Profiles/test.icc + $ + $ + $ Using Existing OCIO Configurations + $ --inputspace %s Input OCIO ColorSpace (or Role) + $ --outputspace %s Output OCIO ColorSpace (or Role) + $ --shaperspace %s the OCIO ColorSpace or Role, for the shaper + $ --iconfig %s Input .ocio configuration file (default: $OCIO) + $ + $ Config-Free LUT Baking + $ (all options can be specified multiple times, each is applied in order) + $ --lut %s Specify a LUT (forward direction) + $ --invlut %s Specify a LUT (inverse direction) + $ --slope %f %f %f slope + $ --offset %f %f %f offset (float) + $ --offset10 %f %f %f offset (10-bit) + $ --power %f %f %f power + $ --sat %f saturation (ASC-CDL luma coefficients) + $ + $ Baking Options + $ --format %s the lut format to bake: flame (.3dl), lustre (.3dl), + $ cinespace (.csp), houdini (.lut), iridas_itx (.itx), icc (.icc) + $ --shapersize %d size of the shaper (default: format specific) + $ --cubesize %d size of the cube (default: format specific) + $ --stdout Write to stdout (rather than file) + $ --v Verbose + $ --help Print help message + $ + $ ICC Options + $ --whitepoint %d whitepoint for the profile (default: 6505) + $ --displayicc %s an icc profile which matches the OCIO profiles target display + $ --description %s a meaningful description, this will show up in UI like photoshop + $ --copyright %s a copyright field + + + +See this `ocio-dev thread +<http://groups.google.com/group/ocio-dev/browse_thread/thread/56fd58e60d98e0f6#>`__ +for additional usage discussions. + +When exporting an ICC Profile, you will be asked to specify your monitor’s +profile (it will be selected for you by default). This is because ICC Profile +are not LUTs per se. An ICC Profile describes a color space and then needs a +destination profile to calculate the transformation. So if you have an operation +working and looking good on the monitor you’re using (and maybe its +profile has been properly measured using a spectrophotometer), then choose your +display. If the transform was approved on a different monitor, then maybe you +should choose its profile instead. + + +RV (Beta) +********* + +`Playback Tool - Tweak Software <http://www.tweaksoftware.com>`__ + +`OCIO support in RV <https://github.com/imageworks/OpenColorIO/tree/master/src/rv>`__ +is currently being developed by Ben Dickson (dbr). + +See this `email thread <http://groups.google.com/group/ocio-dev/browse_thread/thread/955fc6271f89a28e>`__ +for additional details. + +This integration is currently considered a work in progress, and should not be +relied upon for critical production work. + + +Java (Beta) +*********** +The OpenColorIO API is available for use in Java. See the `jniglue directory +<http://github.com/imageworks/OpenColorIO/tree/master/src/jniglue>`__ +in the codebase. + +This integration is currently considered a work in progress, and should not be +relied upon for critical production work. + +java.com + + +Blender (Beta) +************** +`Open Source 3D Application <http://www.blender.org/>`__ + +Blender currently has `limited support +<http://wiki.blender.org/index.php/Dev:Source/Image/OpenColorIO#OpenColorIO_Integration>`__ +for OCIO. + +Xaview Thomas has begun the `Blender OCIO integration <http://github.com/thmxv/blender-ocio>`__ . +Currently undergoing development. + +`Blender Developers Meeting Notes July 31, 2011 +<http://www.blendernation.com/2011/08/01/blender-developers-meeting-notes-july-31-2011>`__ + +`YouTube Blender Example +<http://www.youtube.com/watch?v=O43ItUVvcks>`__ + + +Ramen (Beta) +************ +`Open Source Compositor <http://ramencomp.blogspot.com>`__ + +Under development, with native OCIO color managment. + + +CryEngine3 (Beta) +***************** + +`Game Engine - Crytek (Cinema Sandbox) <http://mycryengine.com/index.php?conid=59>`__ + +CryENGINE is a real-time game engine, targeting applications in the +motion-picture market. While we don't know many details about the CryEngine +OpenColorIO integration, we're looking forward to learning more as information +becomes available. + diff --git a/docs/FAQ.rst b/docs/FAQ.rst new file mode 100644 index 0000000..9530cec --- /dev/null +++ b/docs/FAQ.rst @@ -0,0 +1,141 @@ +.. _faq: + +FAQ +=== + +License? +******** + +New BSD. + +You are welcome to include the OpenColorIO in commercial, or open source +applications. See the :ref:`license` for further details. + + +Terminology +*********** + +- Transform - a function that alters RGB(A) data (e.g transform an image from scene linear to sRGB) +- Reference space - a space that connects colorspaces +- Colorspace - a meaningful space that can be transferred to and from the reference space +- Display - a virtual or physical display device (e.g an sRGB display device) +- View - a meaningful view of the reference space on a Display (e.g a film emulation view on an sRGB display device) +- Role - abstract colorspace naming (e.g specify the "lnh" colorspace as the scene_linear role) + + +.. _faq-supportedlut: + +What LUT Formats are supported? +******************************* + +========= =================================== =============================== +Ext Details Notes +========= =================================== =============================== +3dl Autodesk Apps: Lustre, Flame, etc. Read + Write Support. + Supports shaper LUT + 3D +ccc ASC CDL ColorCorrectionCollection Full read support. +cc ASC CDL ColorCorrection Full read support. +csp Cinespace (Rising Sun Research) Read + Write Support. Shaper is + LUT. Spline-based shaper LUT, with resampled into simple 1D LUT + either 1D or 3D LUT. with 2^16 samples. +cub Truelight format. Shaper Lut + 3D Full read support. +cube Iridas format. Either 1D or 3D Lut. Full read support +hdl Houdini. 1D Lut, 3D lut, 1D shaper Only 'C' type is supported. + Lut Need to add R G B A RGB RGBA ALL. + No support for Sampling tag. + Header fields must be in strict order. +look IRIDAS .look Read baked 3D LUT embedded in file. + No mask support. +mga/m3d Pandora 3D lut Full read support. +spi1d 1D format. Imageworks native 1D Full read support. + lut format. HDR friendly, supports + arbitrary input and output domains +spi3d 3D format. Imageworks native 3D Full read support. + lut format. +spimtx 3x3 matrix + color offset. Full read support. + Imageworks native color matrix + format +vf Inventor 3d lut. Read support for 3d lut data + and global_transform element +========= =================================== =============================== + +.. note:: + Shaper LUT application in OCIO currently only supports linear interpolation. + For very small shaper LUT sizes this may not be sufficient. (CSP shaper luts + excluded; they do use spline interpolation at load-time). + + +Can you query a color space by name (like "Rec709") and get back XYZ coordinates of its primaries and whitepoint? +***************************************************************************************************************** + +Not currently. + +OCIO is a color configuration 'playback' tool that tries to be as flexible as possible; +color information such as this is often only needed / relevant at configuration authoring time. +Making primaries / whitepoint required would limit the pipeline OCIO could service. In the +strictest sense, we would consider OCIO to be a 'baked' representation of color processes, +similar to how Alembic files do not store animation rig data, but rather only the baked geometry. + +Also, remember that not all colorspaces using in visual effects even have strongly +defined color space definitions. For example, scanned film negatives, when linearized with +1d transfer curves (the historical norm in vfx), do not have defined primaries/white point. +Each rgb value could of course individually be tied to a specific color, but if you were to +do a sweep of the pure 'red channel', for example, you'd find that it creates a curves in +chromaticity space, not a single point. (This is due to the 1d linearization not attempting +to undo the subtractive processes that created the pixels in the first place. + +But many color spaces in OCIO *do* have very strongly defined white points/chromaticities. +On the display side, for example, we have very precise information on this. + +Perhaps OCIO should include optional metadata to tag outputs? We are looking at this as +as a OCIO 1.2 feature. + +Can you convert XYZ <-> named color space RGB values? +***************************************************** + +OCIO includes a MatrixTransform, so the processing capability is there. But there is no convenience +function to compute this matrix for you. (We do include other Matrix convenience functions though, +so it already has a place to be added. See MatrixTransform in export/OpenColorTransforms.h) + +There's talk of extended OCIO 1.2 to have a plugin api where colorspaces could be dynamically +added at runtime (such as after reading exr chromaticity header metadata). This would +necessitate adding such a feature. + + +What are the differences between Nuke's Vectorfield and OCIOFileTransform? +************************************************************************** + +(All tests done with Nuke 6.3) + +========= ============================================= =============================== +Ext Details Notes +========= ============================================= =============================== +3dl Matched Results +ccc n/a +cc n/a +csp *Difference* Gain error. Believe OCIO is correct, but need to verify. +cub Matched Results Note: Nuke's .cub exporter is broken (gain error) +cube Matched Results +hdl n/a +mga/m3d n/a +spi1d n/a +spi3d n/a +spimtx n/a +vf *Difference* Gain error. Believe OCIO is correct, but need to verify. +========= ============================================= =============================== + +All gain differences are due to a common 'gotcha' when interpolating 3d luts, related to +internal index computation. If you have a 32x32x32 3dlut, when sampling values from (0,1) +do you internally scale by 31.0 or 32.0? This is typically well-defined for each format, +(in this case the answer is usually 31.0) but when incorrectly handled in an application, +you occationally see gain errors that differ by this amount. (In the case of a 32-sized +3dlut, 32/31 = ~3% error) + + +What do ColorSpace::setAllocation() and ColorSpace::setAllocationVars() do? +*************************************************************************** + +These hints only come into play during GPU processing, and are used to determine proper +colorspace allocation handling for 3D LUTs. See this page :ref:`allocationvars` for +further information. + diff --git a/docs/License.rst b/docs/License.rst new file mode 100755 index 0000000..9d35840 --- /dev/null +++ b/docs/License.rst @@ -0,0 +1,5 @@ +.. _license: + +License +======= +.. include:: LICENSE diff --git a/docs/conf.py.in b/docs/conf.py.in new file mode 100644 index 0000000..b08493b --- /dev/null +++ b/docs/conf.py.in @@ -0,0 +1,110 @@ +# -*- coding: utf-8 -*- + +# See: +# http://sphinx.pocoo.org/config.html + +import sys, os + +# -- Add PyOpenColorIO to sys.path +sys.path.insert(0, "@CMAKE_BINARY_DIR@/src/pyglue") + +# -- General configuration ----------------------------------------------------- +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.ifconfig'] +templates_path = ['templates'] +source_suffix = '.rst' +master_doc = 'index' +project = u'OpenColorIO' +copyright = u'2010, Sony Pictures Imageworks' +# The short X.Y version. +version = '@OCIO_VERSION_MAJOR@.@OCIO_VERSION_MINOR@' +# The full version, including alpha/beta/rc tags. +release = '@OCIO_VERSION@' +exclude_patterns = ['build', '*-prefix'] +#add_function_parentheses = True +#add_module_names = True +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' +#modindex_common_prefix = [] + +rst_prolog = """ +.. |OCIO| replace:: *OCIO* +.. |OpenColorIO| replace:: **OpenColorIO** +.. _Sony Imageworks: http://www.imageworks.com/ +.. |Sony Imageworks| replace:: `Sony Imageworks`_ +.. _Jeremy Selan: mailto:jeremy.selan@gmail.com +.. |Jeremy Selan| replace:: `Jeremy Selan`_ +.. _ocio-users: http://groups.google.com/group/ocio-users +.. _ocio-dev: http://groups.google.com/group/ocio-dev +""" + +# -- Options for HTML output --------------------------------------------------- +html_theme_path = ['.'] +html_theme = 'ociotheme' +#html_theme_options = {} +#html_title = None +#html_short_title = None +#html_logo = None +#html_favicon = None +html_static_path = [] +#html_last_updated_fmt = '%b %d, %Y' +#html_use_smartypants = True +#html_sidebars = {} +#html_additional_pages = {} +html_domain_indices = ['cpp-modindex', 'py-modindex'] +#html_use_index = True +#html_split_index = False +#html_show_sourcelink = True +#html_show_sphinx = True +#html_show_copyright = True +#html_use_opensearch = '' +#html_file_suffix = None +htmlhelp_basename = 'OpenColorIOdoc' + +# -- Options for LaTeX output -------------------------------------------------- +#latex_paper_size = 'letter' +#latex_font_size = '10pt' +latex_documents = [ + ('index', 'OpenColorIO.tex', u'OpenColorIO Documentation', + u'Sony Pictures Imageworks', 'manual', False), +] +latex_elements = { + 'preamble': '\setcounter{tocdepth}{2}', + 'footer': 'test...123' +} + +#latex_logo = None +#latex_use_parts = False +#latex_show_pagerefs = False +#latex_show_urls = False +#latex_preamble = '\setcounter{tocdepth}{2}' +#latex_appendices = [] +latex_domain_indices = ['cpp-modindex', 'py-modindex'] + +# -- Options for manual page output -------------------------------------------- +man_pages = [ + ('index', 'opencolorio', u'OpenColorIO Documentation', + [u'Sony Pictures Imageworks'], 1) +] + +# -- Options for Texinfo output ------------------------------------------------ +texinfo_documents = [ + ('index', 'OpenColorIO', u'OpenColorIO Documentation', u'Sony Pictures Imageworks', + 'OpenColorIO', 'One line description of project.', 'Miscellaneous'), +] +texinfo_appendices = [] + +# -- Options for Epub output --------------------------------------------------- +epub_title = u'OpenColorIO' +epub_author = u'Sony Pictures Imageworks' +epub_publisher = u'Sony Pictures Imageworks' +epub_copyright = u'2010, Sony Pictures Imageworks' +#epub_language = '' +#epub_scheme = '' +#epub_identifier = '' +#epub_uid = '' +#epub_cover = () +#epub_pre_files = [] +#epub_post_files = [] +#epub_exclude_files = [] +#epub_tocdepth = 3 +#epub_tocdup = True diff --git a/docs/configurations/allocation_vars.rst b/docs/configurations/allocation_vars.rst new file mode 100644 index 0000000..9cb2a05 --- /dev/null +++ b/docs/configurations/allocation_vars.rst @@ -0,0 +1,119 @@ +.. _allocationvars: + +How to Configure ColorSpace Allocation +====================================== + +The allocation / allocation vars are utilized using during GPU 3dlut / shader +text generation. (Processor::getGpuShaderText, Processor::getGpuLut3D). + +If, in the course of GPU processing, a 3D lut is required, the "allocation / +allocation vars" direct how OCIO should sample the colorspace, with the intent +being to maintain maximum fidelity and minimize clamping. + +Currently support allocations / variables: + +ALLOCATION_UNIFORM:: + 2 vars: [min, max] + +ALLOCATION_LG2:: + 2 vars: [lg2min, lg2max] + 3 vars: [lg2min, lg2max, linear_offset] + +So say you have an srgb image (such as an 8-bit tif), where you know the data +ranges between 0.0 - 1.0 (after converting to float). If you wanted to apply +a 3d lut to this data, there is no danger in samplingthat space uniformly and +clamping data outside (0,1). So for this colorspace we would tag it: + +.. code-block:: yaml + + allocation: uniform + allocationvars: [0.0, 1.0] + +These are the defaults, so the tagging could also be skipped. + +But what if you were actually first processing the data, where occasionally +small undershoot and overshoot values were encountered? If you wanted OCIO to +preserve this overshoot / undershoot pixel information, you would do so by +modifying the allocation vars. + +.. code-block:: yaml + + allocation: uniform + allocationvars: [-0.125, 1.125] + +This would mean that any image data originally within [-0.125, 1.125] will be +preserved during GPU processing. (Protip: Data outside this range *may* +actually be preserved in some circumstances - such as if a 3d lut is not needed +- but it's not required to be preserved). + +So why not leave this at huge values (such as [-1000.0, 1000.0]) all the time? +Well, there's a cost to supporting this larger dynamic range, and that cost is +reduced precision within the 3D luts sample space. So in general you're best +served by using sensible allocations (the smallest you can get away with, but +no smaller). + +Now in the case of high-dynamic range color spaces (such as float linear), a +uniform sampling is not sufficient because the max value we need to preserve is +so high. + +Say you were using a 32x32x32 3d lookup table (a common size). Middle gray is +at 0.18, and specular values are very much above that. Say the max value we +wanted to preserve in our coding space is 256.0, each 3d lut lattice coordinates +would represent 8.0 units of linear light! That means the vast majority of the +perceptually significant portions of the space wouldnt be sampled at all! + +unform allocation from 0-256\: +0 +8.0 +16.0 +... +240.0 +256.0 + +So another allocation is defined, lg2 + +.. code-block:: yaml + + - !<ColorSpace> + name: linear + description: | + Scene-linear, high dynamic range. Used for rendering and compositing. + allocation: lg2 + allocationvars: [-8, 8] + +In this case, we're saying that the appropriate ways to sample the 3d lut are +logarithmically, from 2^-8 stops to 2^8 stops. + +Sample locations: +2^-8\: 0.0039 +2^-7\: 0.0078 +2^-6\: 0.0156 +... +2^0\: 1.0 +... +2^6\: 64.0 +2^7\: 128.0 +2^8\: 256.0 + +Which gives us a much better perceptual sampling of the space. + +The one downside of this approach is that it can't represent 0.0, +which is why we optionally allow a 3d allocation var, a black point +offset. If you need to preserve 0.0 values, and you have a high +dynamic range space, you can specify a small offset. + +Example: + +.. code-block:: yaml + + allocation: lg2 + allocationvars: [-8, 8, 0.00390625] + +The [-15.0, 6.0] values in spi-vfx come from the fact that all of the +linearizations provided in that profile span the region from 2^-15 +stops, to 2^6 stops. One could probably change that black point to a +higher number (such as -8), but if you raised it too much you would +start seeing black values be clipped. Conversely, on the high end +one could raise it a bit but if you raised it too far the precision +would suffer around gray, and if you lowered it further you'd start to +see highlight clipping. diff --git a/docs/configurations/images/spi-vfx/gn10_to_linear_light.jpeg b/docs/configurations/images/spi-vfx/gn10_to_linear_light.jpeg Binary files differnew file mode 100644 index 0000000..ffc228e --- /dev/null +++ b/docs/configurations/images/spi-vfx/gn10_to_linear_light.jpeg diff --git a/docs/configurations/images/spi-vfx/gnf_to_linear_light.jpeg b/docs/configurations/images/spi-vfx/gnf_to_linear_light.jpeg Binary files differnew file mode 100644 index 0000000..25deaf4 --- /dev/null +++ b/docs/configurations/images/spi-vfx/gnf_to_linear_light.jpeg diff --git a/docs/configurations/images/spi-vfx/lg10_to_linear_light.jpeg b/docs/configurations/images/spi-vfx/lg10_to_linear_light.jpeg Binary files differnew file mode 100644 index 0000000..cbef9b4 --- /dev/null +++ b/docs/configurations/images/spi-vfx/lg10_to_linear_light.jpeg diff --git a/docs/configurations/images/spi-vfx/lg8_to_vd8.jpeg b/docs/configurations/images/spi-vfx/lg8_to_vd8.jpeg Binary files differnew file mode 100644 index 0000000..ba49ad4 --- /dev/null +++ b/docs/configurations/images/spi-vfx/lg8_to_vd8.jpeg diff --git a/docs/configurations/images/spi-vfx/lgf_to_linear_light.jpeg b/docs/configurations/images/spi-vfx/lgf_to_linear_light.jpeg Binary files differnew file mode 100644 index 0000000..8b897ed --- /dev/null +++ b/docs/configurations/images/spi-vfx/lgf_to_linear_light.jpeg diff --git a/docs/configurations/index.rst b/docs/configurations/index.rst new file mode 100644 index 0000000..0284d34 --- /dev/null +++ b/docs/configurations/index.rst @@ -0,0 +1,22 @@ +.. _configurations: + +Configurations +============== + +This section gives an overview of what existing (public) OCIO configuration exist, +and how to create new ones. + +OCIO Configurations can be downloaded here: `.zip <http://github.com/imageworks/OpenColorIO-Configs/zipball/master>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO-Configs/tarball/master>`__ (OCIO v1.0+) + +If you are interested in crafting custom color configurations, and need assistance, please contact: ocio-dev_\ ``@googlegroups.com`` + +.. toctree:: + :maxdepth: 1 + + spi_pipeline + + spi_vfx + spi_anim + nuke_default + + allocation_vars diff --git a/docs/configurations/nuke_default.rst b/docs/configurations/nuke_default.rst new file mode 100644 index 0000000..7e3a7ee --- /dev/null +++ b/docs/configurations/nuke_default.rst @@ -0,0 +1,19 @@ +Nuke default +============ + +This profile corresponds to the default Nuke color configuration (currently generated from Nuke 6.1). + +If you have made modifications to a nuke color configuration, and wish to re-export your own custom OCIO profile, please refer to the nuke_to_ocio utility script distributed with OpenColorIO. + +The following color transforms are defined: + +- linear +- sRGB +- rec709 +- Cineon +- Gamma 1.8 +- Gamma 2.2 +- Panalog +- REDLog +- ViperLog +- REDSpace diff --git a/docs/configurations/spi_anim.rst b/docs/configurations/spi_anim.rst new file mode 100644 index 0000000..49a7779 --- /dev/null +++ b/docs/configurations/spi_anim.rst @@ -0,0 +1,4 @@ +spi-anim +======== + +This is a real OCIO color profile in use at Sony Pictures Imageworks, and is suitable for use on animated features. The concepts utilized in this profile have been successfully validated on a variety of Sony Pictures Animation features including Cloudy With A Chance Of Meatballs, Surf's Up, and Arthur Christmas. diff --git a/docs/configurations/spi_pipeline.rst b/docs/configurations/spi_pipeline.rst new file mode 100644 index 0000000..c508899 --- /dev/null +++ b/docs/configurations/spi_pipeline.rst @@ -0,0 +1,74 @@ +Sony Pictures Imageworks Color Pipeline +======================================= + +This document describes a high-level overview on how to emulate the current color management practice at Sony Imageworks. It applies equally to all profiles used at Imageworks, including both the VFX and Animation profiles. It's by no means a requirement to follow this workflow at your own facility, this is merely a guideline on how we choose to work. + +General Pipeline Observations +***************************** + +* All images, on disk, contain colorspace information as a substring withing the filename. This is obeyed by all applications that load image, write images, or view images. File extensions and metadata are ignored with regards to color processing. + + Example:: + + colorimage_lnf.exr : lnf + dataimage_ncf.exr : ncf + plate_lg10.dpx : lg10 + texture_dt8.tif: dt8 + + Note: fileformat extension does NOT imply a color space. Not all dpx files are lg10. Note all tif images are dt8. + +* The common file formats we use are exr, tif, dpx. + + * render outputs: exr + * render inputs (mipmapped-textures): exr, tif (txtif) + * photographic plates (scans): dpx + * composite outputs: dpx, exr + * on-set reference: (camera raw) NEF, CR2, etc. + * painted textures: psd, tif + * output proxies: jpg + +* All pipelines that need to be colorspace aware rely on ``Config.parseColorSpaceFromString``. + +* Color configurations are show specific. The $OCIO environment variable is set as part of a 'setshot' process, before other applications are launched. Artists are not allowed to work across different shows without using a fresh shell + setshot. + +* While the list of colorspaces can be show specific, care is taken to maintain similar naming to the greatest extent feasible. This reduces artist confusion. Even if two color spaces are not identical across shows, if they serve a similar purpose they are named the same. Example: We label 10-bit scanned film negatives as lg10. Even if two different shows use different acquisition film stocks, and rely on different linearization curves, they are both labelled lg10. + +* There is no explicit guarantee that image assets copied across shows will be transferable in a color-correct manner. For example, in the above film scan example, one would not expect that the linearized versions of scans processed on different shows to match. In practice, this is not a problematic issue as the colorspaces which are convenient to copy (such as texture assets) happen to be similarly defined across show profiles. + + +Rendering +********* + +* Rendering and shading occurs in a scene-linear floating point space, typically named "ln". Half-float (16-bit) images are labelled lnh, full float images (32-bit) are labelled lnf. + + +* All image inputs should be converted to ln prior to render-time. Typically, this is done when textures are published. (See below) + +* Renderer outputs are always floating-point. Color outputs are typically stored as lnh (16-bit half float). Data outputs (normals, depth data, etc) are stored as ncf ("not color" data, 32-bit full float). Lossy compression is never utilized. + +* Render outputs are always viewed with an OCIO compatible image viewer. Thus, for typical color imagery the lnf display transform will be applied. In Nuke, this can be emulated using the OCIODisplay node. A standalone image viewer, ociodisplay, is also included with OpenColorIO src/example. + + +Texture Painting / Matte Painting +********************************* + +* Textures are painted in non-OCIO color-managed environment. (Photoshop, etc). + +* At texture publish time, before mipmaps are generated, all color processing is applied. Internally at SPI we use a modified version of OpenImageIO's maketx that also links to OpenColorIO. We intend to make this code available as soon as possible. In the meantime, the OpenColorIO 'ocioconvert' script included in examples can be relied upon. Color processing (linearization) is applied before mipmap generation in order to assure energy preservation in the render. If the opposite processing order were used, (mipmap in the original space, color convert in the shader), the apparent intensity of texture values would change as the object approached to receeded to the camera. + +* The original texture filenames contain the colorspace information as a substring, to signify processing intent. + + * Textures that contain data (bump maps, opacity maps, blend maps, etc) are labelled with the nc colorspaces according to their bitdepth. Ex: an 8-bit opacity map -> skin_opacity_nc8.tif + + * Painted textures that are intended to modulate diffuse color components are labelled dt (standing for "diffuse texture"). The dt8 colorspace is designed such that, when linearized, values will not extend above 1.0. At texture publishing time these are converted to lnh mipmapped tiffs/exr. Note that as linear textures have greater allocation requirements, a bit depth promotion is required in this case. I.e., even if the original texture as painted was only 8-bits, the mipmapped texture will be stored as a 16-bit float image. + + * Painted environment maps, which may be emissive as labelled vd (standing for 'video'). These values, when linearized, have the potential to generate specular information well above 1.0. Note that in the current vd linearization curves, the top code values may be very "sensitive". I.e., very small changes in the initial code value (such as 254->255) may actually result in very large differences in the estimated scene-linear intensity. All environment maps are store as lnh mipmapped tiffs/exr. The same bit-depth promotion as in the dt8 case is required here. + + +Compositing +*********** + +* The majority of compositing operations happen in scene-linear, lnf, colorspace. +* All image inputs are linearized to lnf as they are loaded. Customized input nodes make this processing convenient. Rendered elements, which are stored in linear already, do not require processing. Photographic plates will typically be linearized according to their source type, (lg10 for film scans, gn10 for genesis sources, etc). +* All output images are de-linearized from lnf when they are written. A customized output node makes this convenient. +* On occasion log data is required for certain processing operations. (Plate resizing, pulling keys, degrain, etc). For each show, a colorspace is specified as appropriate for this operation. The artist does not have to keep track of which colorspace is appropriate to use; the OCIOLogConvert node is always intended for this purpose. (Within the OCIO profile, this is specified using the 'compositing_log' role). diff --git a/docs/configurations/spi_vfx.rst b/docs/configurations/spi_vfx.rst new file mode 100644 index 0000000..9e6cc96 --- /dev/null +++ b/docs/configurations/spi_vfx.rst @@ -0,0 +1,186 @@ +.. _config-spivfx: + +spi-vfx +======= + +This is a real OCIO color profile in use at Sony Pictures Imageworks, and is suitable for use on visual effects (VFX) work. The concepts utilized in this profile have been successfully validated on a variety of Imageworks visual effects films, including Spider-Man, Alice In Wonderland, G-Force, and Green Lantern. + +**Conversion from film to/from scene-linear is a simple, trivially invertible 1D transform. The display transforms are complex, 3D film-print emulations.** + +In production, this profile is typically used before final color details are worked out. Although it sounds temporary, most of a film can be made off this configuration. Final color decisions for a film are often made long after significant work has been done. In some cases shots from a film can be finaled before the color details, such as which Digital Intermediate (DI) house will be used, are decided. Entire projects have been completed using this profile without modification. + +This profile embodies two philosophies of color management familiar to those in production: *"Keep It Simple"*, and, *"Don't Be Evil"*. + +The following steps outline a simplified visual effects color workflow: + +* Load a plate (log film scan, digital motion picture camera, etc) +* Convert device color space to scene-linear +* Render and composite in scene-linear +* Convert from scene-linear to device color space +* Output final plate + +It is absolutely critical to guarantee that process - end to end - is colorimetrically a no-op. Under no circumstances are any unintended modifications to the original image allowed. + +Thus, this profile uses very simple (1D) conversions for all input and output color space conversions. All of the complexity (the 3D LUT film emulation lifting) is handled at display time, and is never baked (or unbaked) into the imagery. For visualization, this profile includes a generic Kodak Vision print emulation suitable for display on a reference sRGB monitor or a P3 Digital Cinema projector. + +Caveot 1: Of course, we realize that there are many other color workflows that may be equally good (or better) than the one presented here. Please, if you have a successful alternative workflows share the details! + +Caveot 2: We are not distributing the code that generates the luts from their underlying curve representations. While we hope to publish this eventually, at the current time this process relies on internal tools and we don't have the spare development cycles to port this code to something suitable for distribution. + + +Invertibility ++++++++++++++ + +Elements often need to be transferred back and forth many times between different colorspaces. Since it’s impossible to know in advance how many times an image may be transferred between colorspaces it is essential for the majority of transformations to be lossless invertible transformations. By the end of the color pipeline even a 1 value difference in a 10bit transformation can become a significant issue. Invertible transformations can be taken from the source space, to linear and back with no change to the data. A higher value is placed on transformations being predictable and invertible than absolutely correct. All 1-d luts allow for forward and inverse transformations with no loss. Unless specified all channels are equally affected. The luts are 1 bit wider than stated, so lg8 actually defines 9 bits worth of entries. This allows the rounding in the inverse direction to be applied unambiguously (lossless). + +Non-invertible transforms contain 3d lookups. 3D transformations can not be inverted due to gamut mapping issues. Non-invertible transformations are only used for final output media (such as QuickTimes) and for display purposes. + +Film Emulation Inversion +++++++++++++++++++++++++ + +Inverse film emulation luts aren’t supported in a default configuration. Imageworks does not use a film emulation inversion lut for texture or matte paintings. In its place a film emulation preview lut, commonly as an ICC profile, is used. Although most film emulation luts are similar they do differ significantly. The DI facility creating final color is often chosen long after significant vfx work has been begun. The film luts the film will be finished on are not made until weeks, or days, before DI begins. So the ‘true’ lut that will be used for the finishing is not available until very late in the production, from a VFX perspective. There are many color gamut mapping issues that arise when inverting film to video lut. Using a film inversion lut at this stage would bake in a look that isn't quite right and is very difficult to fully un-bake. It is safer to work with images in a non-constrained way and apply a visualization that can be toggled on and off. + +Scene Linear +************ + +**lnf, lnh, ln16** + +**Middle Gray: 0.18** + +The linear space is a photometrically linear space, representing high-dynamic range (HDR) pixel values in our virtual world. Middle gray is defined to be at 0.18. While the dynamic range of lnf is technically unbounded, pixel values for natural, well exposed imagery will often fall between +/- 8 stops from gray. + +The scene linear colorspace is used for compositing, rendering, and is also the profile connection space. All colorspace conversions are made in relation how they transform into or out of scene linear. + +The colors defined in linear are implicitly bounded by film negative sensitivities. The space is based off an OCN film scan where values refer to linear light at the focal plane. 0.18 in linear will correspond to a %18 percent grey card captured on filmplane under the same lighting conditions where diffuse white is 1.0. Values above 1.0 in any channel would indicate a 'specular', or light emitting objects. + +lnf is a full precision (32-bit) floating point colorspace. It is used for rendering and compositing. + +lnh is a half precision (16-bit) floating point colorspace. It is used for rendering and compositing. + +ln16 is a 16 bit integer representation of the [0,1] range of lnf. This is no longer used but is kept if a legacy image needs to be loaded, or if linear images need to be loaded into an application that does not support float. Note that storing a float lnf image using an integer ln16 representation is destructive, and throws away data. + + +Film Log +******** + +**lg8, lg10, lg16, lgf** + +**Middle Gray: 445 (of 1023)** + +The log to linear curve is based on an analysis of several commonly used Kodak acquisition stocks. It was found that Kodak 5218 is right about in the middle in terms of tone response given the input imagery we receive. The curve incorporates some toe compensation. The curve gamma closely matches 5218. The transformation does not represent any single stock. The Imageworks log conversions are not channel specific, all color channels are transformed uniformly. Compositing productivity gains have been found using the toe compensations when compared to using a straight line log to linear curve. Shoulder compensation - while technically correct - detracted from compositing quality, often creating situations where grain film noise would result in larger than desired changes in linear light. + +lg8, lg10, and lg16 are similar. They are all the same log to linear transformation but are explicitly defined to be lossless at the specified bit depths. The luts use nearest neighbor interpolation to search for an exact match. Significant performance gains were found when using the proper bitdepth lut. While using the lg16 conversion on an 8 bit image will yield the same result, it is measurably slower than using the 8-bit conversion (assuming 8-bits is all that is needed). This performance gap remains even on current graphics hardware. + +.. figure:: images/spi-vfx/lg10_to_linear_light.jpeg + :align: center + + lg10 to linear light. The green curve represents the lg to ln conversion. The red curve show the green channel of a Kodak 5218 exposure test. The x-axis is in 10bit input lg the output is in lg base2 linear light units. 0.0 Represents diffuse white. + +lg spaces specify 21 of stops of dynamic range. 0 in lg10 space is 15 stops below diffuse white. 445 correspond to 18% grey and is ~2.47 below diffuse white. 1023 in lg10 space is 6 stops above diffuse white. + +lgf is identical on the range from 0-1 to the standard lg luts. It specifies an additional range below 0.0 and above 1.0. In 10 bit the spaces is defined from -512 to 2048. Lg color timing number from either on set color correction devices or from a DI house to be applied in a way that can be fully inverted out without loss. Lgf specifies 18 stops above the lg10 max and 36 stops below the log10 min with a total dynamic range of 85 stops. The space is designed to be bigger than needed. + + +.. figure:: images/spi-vfx/lgf_to_linear_light.jpeg + :align: center + + lgf to linear light. The green curve represents the lg to ln conversion. The red curve show the green channel of a Kodak 5218 exposure test. The x axis is in 10bit input lg the output is in log(base2) linear light units. 0 Represents diffuse white + + +Panalog (Genesis) +***************** + +**gn8, gn10, gn16, gnf** + +GN is the Imageworks Panalog space. It follows the Panalog specification and additionally extrapolates so all of the values from 0 to 1023 are defined. This was necessary due to compression artifacts that could create values below the Panalog specifications. gn8,10,16 are defined with diffuse white at 681, Max white is approximately 2.6 stops above diffuse white and black is approximately 12.6 stops below diffuse white. The dynamic range is less than that of lg. + +.. figure:: images/spi-vfx/gn10_to_linear_light.jpeg + :align: center + + gn10 to linear light. the x axis is in 10bit Panalog values. The Y axis is in linear light. The green curve is the gn curve. the red curve is the Panalog data. + +gnf is similar in purpose and function to lgf. It is identical on the range from 0-1 to the regular gn and specifies an additional range below 0.0 and above 1.0. In 10 bit numbers gnf is defined from -255 to 3125. This allows for color timing number from either on set color correction devices or from a DI house to be applied in a way that can be fully inverted. Additionally it allows for lg10 based image data to be fully represented without clipping. + +gnf specifies 14.5 stops above the gn10 max and 18 of stops below the gn10 min. The entire range of gnf is 47 stops. + +.. figure:: images/spi-vfx/gnf_to_linear_light.jpeg + :align: center + + gnf to linear light. the x axis is in 10bit Panalog values. The Y axis is in linear light. The green curve is the gn curve. the red curve is the Panalog data. Only a subset of the function is used to define the gnf solorspace + + +Reference Art +************* + +**vd8, vd16, vdf, hd10** + +The vd spaces are mappings of linear image data into display space. The main part of the transformation is defined as a single curve that is conceptually two parts. The first is a ln to lg conversion. The second is lg to sRGB conversion. This is based off the neutral channel response of the sRGB film emulation lut used in the profile. The dynamic range of the vd colorspace is limited. It is undesirable to map the vd max to the linear max. Such a conversion results in linear values are almost never what an artist intended. The rule of thumb is that, at the high end, single value deltas in an 8 bit image should never create over a half stop of additional linear light. The vd conversion curve is limited to prevent this case. + +.. figure :: images/spi-vfx/lg8_to_vd8.jpeg + :align: center + + The curve used to map from Lg8 to vd 8. The x-axis is in lg8 units, the y-axis is in vd8 units. + +The dynamic range of the vd is limited to around 2.5 stops above diffuse white. This has two positive attributes. It allows vd to be used to directly on matte paintings. It also allows all of vd to be represented in a gn10 image. The last part of the transformation is a matrix transformation that moves the whitepoint of film to look correct when displayed with a d65 whitepoint. + +The main use of this colorspace is to import RGB images with an unknown colorspace. This colorspace no longer gets much use alone; However it is an integral part of many conversions. It is also part of the matte painting and diffuse texture pipelines. + +vdf works differently than the other floating spaces. It still only defines the color transformation from 0-1. This colorspace is used when we receive video space encoded exr's. + +HD10 is a vd based space that is used for importing and exporting REC709 range broadcast material. This works very well for broadcast camera native material and poorly for material with a film emulation lut baked in. This transformation works well exporting film based material to tape, even though it lacks a film emulation lut. It does not give an accurate color rendering but created a pleasing image that makes clients happy. + +Structurally the conversion is a matrix operation that scales the data then adds an offset to limit the range from 64-940. From there the standard vd transformation is applied. + +Texture Painting +**************** + +**dt8, dt16** + +DT 8,16 - Diffuse texture colorspaces. These colorspaces are used for the conversion of textures painted in video space into a range limited linear space for use in rendering. The Color space is based on the vd transformation but limits the conversion into linear space so that no values above diffuse white can be created. This ensures that textures do not add light to a render. This is achieved by using a matrix transformation to limit the mapping of vd to the linear value of diffuse white. + +Data +**** + +**nc8, nc10, nc16, ncf** + +Non-Color (NC) spaces are used to hold any data that needs to be processed though the color pipeline unaltered. These are data spaces and can hold anything such as point clouds, normals, untagged reference art, etc. These data spaces do not get transformations applied at any point. + + +Display Transforms +****************** + +**srgb8, p3dci8, xyz16** + +**srgb8** bakes in the film3d emulation lut. This table can be used for either QuickTime generation or output to the sRGB display. The transformation is a 3d film emulation table with gray balance compensation, so a value of 445,445,445 in lg10 space os modified to become equal RGB values in sRGB. Additionally the lut is scaled so that at least one of the color channels on maximum white uses the display max. + +The transformation takes place in three parts. First the linear data is converted to the show log space. Then a film emulation table is applied. Then the grey balance and white scaling compensation are applied. This table is designed to be evaluated in a dimly lit office environment on a sRGB display. + +**p3dci8** is an implementation of film emulation table that has an output of DCI P3. This is only ever used for driving DLPs for display. The transformation has two parts. First the linear image data is converted to lg10 based image data then the DCI P3 film emulation lut is applied. No additional compensations are made. + +**xyz16** is designed for the creation of a Digital Cinema Distribution Master (DCDM). The color matches that of the P3 output (dlpqt8), but has an additional output transformation to convert to X'Y'Z'. The transformation takes the linear image data and converts it to lg, then applies the filmlook. The data is then in DCI P3 colorspace. That data is converted to display linear P3, using an inverse gamma curve. A matrix conversion is then used to transform from DCI P3’ into XYZ’. The final step is to reapply the gamma 2.6 to result in XYZ16 values. + +In this profile each display has three identical looks defined. The names are kept consistent between devices to minimize confusion. OCIO uses a specific tag to associate colorspaces with displays. The tags are nothing more than links to already defined colorspaces. + +**Film** is the image displayed though a film emulation lut. This visualization is display compensated and should visually match between a sRGB display and a P3 projector. The goal is to match how the film will look in a DI. The luts in use for this profile roughly match the Sony ColorWorks environment. + +**Raw** visualization shows the image data on the screen with no display compensation. This is used for image debugging purposes, for instance to see if potential image discontinuities are in the source data or the visualization. + +**Log** visualization displays the image as if it were converted to the show specific log. This is transformation also has no display compensation. The common use for this us to see how well elements fit into the comp without the film emulation lut disguising any flaws. Old school compositors love it for grain matching. + +sRGB Film : srgb8 +sRGB Raw : nc10 +sRGB Log : lg10 + +DCIP3 Raw : nc10 +DCIP3 Log : lg10 +DCIP3 Film : dlpqt8 + + +Display Calibration +******************* + +**sRGB** is the supported desktop display specification, calibrated to the sRGB standard and viewed in a dim office environment. As Imageworks switched from crt based display devices to LCD based devices a number of possible colorspaces were explored. It was a long decision but sRGB was chosen for a few reasons. An important one was that almost every display manufacturer can implement sRGB, reasonable well. This becomes a boon when we work needs to be done outside of our main facilities. Even a consumer display with calibration can come close to matching the sRGB standard. Since so many monitor manufacturers can hit sRGB calibration we are not tied to purchasing from a specific vendor. It becomes unnecessary to specify a specific display to with productions or external vendors. It also reduces the amount of studio specific color requirements that need to be communicated when working with other facilities. 80 cd/m^2, D65 white point, srgb gamma function (approx 2.4) + +**P3** was deemed especially unusable on the desktop. The full specification requires a white point of 48 cd/m^2. To adapt P3 for desktop use (in dim ambient environments), the whitepoint luminance needed to be raised. The specified 2.6 gamma is very challenging to the current display technology on very dark colors. This meant that we would have a special Imageworks video P3. A custom colorspace wouldn't make compositing better and would require a conversation, or conversion, every time video was sent out of house. + +**DCIP3** is a projector calibrated to DCI P3 mastering specification in a theatrical mastering environment. We use a mix of display technologies, SXRD and DLP, depending on application. Gamma 2.6. Traditional DCI calibration. diff --git a/docs/developers/api/index.rst b/docs/developers/api/index.rst new file mode 100644 index 0000000..eccef5c --- /dev/null +++ b/docs/developers/api/index.rst @@ -0,0 +1,6 @@ +.. toctree:: + :maxdepth: 1 + + OpenColorIO + OpenColorTransforms + OpenColorTypes diff --git a/docs/developers/bindings/PythonAPI.rst b/docs/developers/bindings/PythonAPI.rst new file mode 100644 index 0000000..839e9d2 --- /dev/null +++ b/docs/developers/bindings/PythonAPI.rst @@ -0,0 +1,147 @@ +########## +Python API +########## + +Description +=========== + +A color configuration (:py:class:`Config`) defines all the color spaces to be +available at runtime. + +(:py:class:`Config`) is the main object for interacting with this library. +It encapsulates all the information necessary to use customized +:py:class:`PyOpenColorIO.ColorSpaceTransform` and +:py:class:`PyOpenColorIO.DisplayTransform` operations. + +See the :ref:`user-guide` for more information on selecting, creating, +and working with custom color configurations. + +For applications interested in using only one color configuration at +a time (this is the vast majority of apps), their API would +traditionally get the global configuration and use that, as +opposed to creating a new one. This simplifies the use case +for plugins and bindings, as it alleviates the need to pass +around configuration handles. + +An example of an application where this would not be +sufficient would be a multi-threaded image proxy server +(daemon) that wants to handle multiple show configurations +concurrently in a single process. This app would need to keep +multiple configurations alive, and manage them appropriately. + +Roughly speaking, a novice user should select a default +configuration that most closely approximates the use case +(animation, visual effects, etc.), and set the :envvar:`OCIO` +environment variable to point at the root of that configuration. + +.. note:: + Initialization using environment variables is typically preferable + in a multi-app ecosystem, as it allows all applications to be consistently configured. + +.. note:: + Paths to LUTs can be relative. The search paths are defined in :py:class:`Config`. + +See :ref:`developers-usageexamples` + +Examples of Use +--------------- + +.. code-block:: python + + import PyOpenColorIO as OCIO + + # Load an existing configuration from the environment. + # The resulting configuration is read-only. If $OCIO is set, it will use that. + # Otherwise it will use an internal default. + config = OCIO.GetCurrentConfig() + + # What color spaces exist? + colorSpaceNames = [ cs.getName() for cs in config.getColorSpaces() ] + + # Given a string, can we parse a color space name from it? + inputString = 'myname_linear.exr' + colorSpaceName = config.parseColorSpaceFromString(inputString) + if colorSpaceName: + print 'Found color space', colorSpaceName + else: + print 'Could not get color space from string', inputString + + # What is the name of scene-linear in the configuration? + colorSpace = config.getColorSpace(OCIO.Constants.ROLE_SCENE_LINEAR) + if colorSpace: + print colorSpace.getName() + else: + print 'The role of scene-linear is not defined in the configuration' + + # For examples of how to actually perform the color transform math, + # see 'Python: Processor' docs. + + # Create a new, empty, editable configuration + config = OCIO.Config() + + # Create a new color space, and add it + cs = OCIO.ColorSpace(...) + # (See ColorSpace for details) + config.addColorSpace(cs) + + # For additional examples of config manipulation, see + # https://github.com/imageworks/OpenColorIO-Configs/blob/master/nuke-default/make.py + +Exceptions +========== + +.. autoclass:: PyOpenColorIO.Exception + :members: + :undoc-members: + +.. autoclass:: PyOpenColorIO.ExceptionMissingFile + :members: + :undoc-members: + +Global +====== + +.. autofunction:: PyOpenColorIO.ClearAllCaches + +.. autofunction:: PyOpenColorIO.GetCurrentConfig + +.. autofunction:: PyOpenColorIO.GetLoggingLevel + +.. autofunction:: PyOpenColorIO.SetCurrentConfig + +.. autofunction:: PyOpenColorIO.SetLoggingLevel + +Config +====== + +.. autoclass:: PyOpenColorIO.Config + :members: + :undoc-members: + +ColorSpace +========== + +.. autoclass:: PyOpenColorIO.ColorSpace + :members: + :undoc-members: + +Look +==== + +.. autoclass:: PyOpenColorIO.Look + :members: + :undoc-members: + +Processor +========= + +.. autoclass:: PyOpenColorIO.Processor + :members: + :undoc-members: + +Context +======= + +.. autoclass:: PyOpenColorIO.Context + :members: + :undoc-members: diff --git a/docs/developers/bindings/PythonTransforms.rst b/docs/developers/bindings/PythonTransforms.rst new file mode 100644 index 0000000..d59a877 --- /dev/null +++ b/docs/developers/bindings/PythonTransforms.rst @@ -0,0 +1,132 @@ +Python Transforms +================= + +Transform +--------- + +.. autoclass:: PyOpenColorIO.Transform + :members: + :undoc-members: + +AllocationTransform +------------------- + +.. code-block:: python + + import PyOpenColorIO as OCIO + transform = OCIO.AllocationTransform() + transform.setAllocation(OCIO.Constants.ALLOCATION) + +.. autoclass:: PyOpenColorIO.AllocationTransform + :members: + :undoc-members: + :inherited-members: + +CDLTransform +------------ + +.. code-block:: python + + import PyOpenColorIO as OCIO + + cdl = OCIO.CDLTransform() + # Set the slope, offset, power, and saturation for each channel. + cdl.setSOP([, , , , , , , , ]) + cdl.setSat([, , ]) + cdl.getSatLumaCoefs() + +.. autoclass:: PyOpenColorIO.CDLTransform + :members: + :undoc-members: + :inherited-members: + +ColorSpaceTransform +------------------- + +This class is meant so that ColorSpace conversions can be reused, referencing ColorSpaces that already exist. + +.. note:: + Careless use of this may create infinite loops, so avoid referencing the colorspace you're in. + +.. code-block:: python + + import PyOpenColorIO as OCIO + transform = OCIO.ColorSpaceTransform() + +.. autoclass:: PyOpenColorIO.ColorSpaceTransform + :members: + :undoc-members: + :inherited-members: + +DisplayTransform +---------------- + +.. code-block:: python + + import PyOpenColorIO as OCIO + transform = OCIO.DisplayTransform() + +.. autoclass:: PyOpenColorIO.DisplayTransform + :members: + :undoc-members: + :inherited-members: + +ExponentTransform +----------------- + +.. code-block:: python + + import PyOpenColorIO as OCIO + transform = OCIO.ExponentTransform() + +.. autoclass:: PyOpenColorIO.ExponentTransform + :members: + :undoc-members: + :inherited-members: + +FileTransform +------------- + +.. autoclass:: PyOpenColorIO.FileTransform + :members: + :undoc-members: + :inherited-members: + +GroupTransform +-------------- + +.. autoclass:: PyOpenColorIO.GroupTransform + :members: + :undoc-members: + :inherited-members: + +LogTransform +------------ + +.. code-block:: python + + import PyOpenColorIO as OCIO + +:py:class:`LogTransform` is used to define a log transform. The direction of +the transform and its numerical base can be specified. + +.. autoclass:: PyOpenColorIO.LogTransform + :members: + :undoc-members: + :inherited-members: + +LookTransform +------------- + +.. autoclass:: PyOpenColorIO.LookTransform + :members: + :undoc-members: + :inherited-members: + +MatrixTransform +--------------- + +.. autoclass:: PyOpenColorIO.MatrixTransform + :members: + :undoc-members: + :inherited-members: diff --git a/docs/developers/bindings/PythonTypes.rst b/docs/developers/bindings/PythonTypes.rst new file mode 100644 index 0000000..074e65e --- /dev/null +++ b/docs/developers/bindings/PythonTypes.rst @@ -0,0 +1,9 @@ +Python Types +============ + +Constants +--------- + +.. automodule:: PyOpenColorIO.Constants + :members: + :undoc-members: diff --git a/docs/developers/coding_guidelines.rst b/docs/developers/coding_guidelines.rst new file mode 100644 index 0000000..742b0f8 --- /dev/null +++ b/docs/developers/coding_guidelines.rst @@ -0,0 +1,109 @@ +Coding guidelines +================= + +There are only two important rules: + +1. When making changes, conform to the style and conventions of the surrounding code. + +2. Strive for clarity, even if that means occasionally breaking the guidelines. Use your head and ask for advice if your common sense seems to disagree with the conventions. + +File Conventions +**************** + +C++ implementation should be named ``*.cpp``. Headers should be named ``*.h``. +All source files should begin with the copyright and license, which can be cut and pasted from other source files). For NEW source files, please do change the copyright year to the present. However DO NOT edit existing files just to update the copyright year, it just creates pointless deltas and offers no increased protection + +Line Length +*********** + +Each line of text in your code should be at most 80 characters long. + +Generally the only exceptions are for comments with example commands or URLs - to make cut and paste easier. + +The other exception is for those rare cases where letting a line be longer (and wrapping on an 80-character window) is actually a better and clearer alternative than trying to split it into two lines. Sometimes this happens, but it's rare. + +DO NOT alter somebody else's code to re-wrap lines (or change whitespace) just because you found something that violates the rules. Let the group/author/leader know, and resist the temptation to change it yourself. + +Formatting +********** + +* Indent 4 spaces at a time, and use actual spaces, not tabs. This is particularly critical on python code. The only exception currently allowed in within Makefiles, where tab characters are sometimes required. + +* Opening brace on the line following the condition or loop. + +* The contents of namespaces are not indented. + +* Function names should be on the same line as their return values. + +* Function calls should NOT have a space between the function name and the opening parenthesis. A single space should be added after each required comma. + +Here is a short code fragement that shows these concepts in action: + +.. code-block:: c++ + + namespace + { + + + int MungeMyNumbers(int a, int b) + { + int x = a + b; + + if (a == 0 || b==0) + { + x += 1; + x += 2; + } + else + { + for (int i=0; i<16; ++i) + { + x += a * i; + } + } + + return x; + } + + + } // namespace + +Misc. Rules +*********** + +* Avoid macros when possible. + +* Anonymous namespaces are preferred when sensible. + +* Variable names should be camelCase, as well as longAndExplicit. + +* Avoid long function implementations. Break up work into small, manageable chunks. + +* Use "TODO:" comments for code that is temporary, a short-term solution, or good-enough but not perfect. This is vastly preferred to leaving subtle corner cases undocumented. + +* Always initialize variables on construction. + +* Do not leave dead code paths around. (This is what revision history is for) + +* Includes should always be ordered as follows: C library, C++ library, other libraries' .h, OCIO public headers, OCIO private headers. Includes within a category should be alphabetized. + +* The C++ "using" directive is not allowed. + +* Static / global variables should be avoided at all costs. + +* Use const whenever it makes sense to do so. + +* The use of Boost is not allowed, except for unit_test_framework and shared_ptr. + +* Default function arguments are not allowed. + +Bottom Line +*********** + +When in doubt, look elsewhere in the code base for examples of similar structures and try to format your code in the same manner. + + +Portions of this document have been blatantly lifted from OpenImageIO, and Google. + +http://openimageio.org/wiki/index.php?title=Coding_Style_Guide +http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
\ No newline at end of file diff --git a/docs/developers/getting_started.rst b/docs/developers/getting_started.rst new file mode 100644 index 0000000..88f61ae --- /dev/null +++ b/docs/developers/getting_started.rst @@ -0,0 +1,47 @@ +Getting started +=============== + +Checking Out The Codebase +************************* + +The master code repository is available on Github: http://github.com/imageworks/OpenColorIO + +For those unfamiliar with git, the wonderful part about it is that even though only a limited number people have write access to the master repository, anyone is free to create, and even check in, changes to their own local git repository. Your local changes will not automatically be pushed back to the master repository, so everyone feel free to informally play around with the codebase. Also - unlike svn - when you download the git repository you have a full copy of the project's history (including revision history, logs, etc), so the majority of code changes you will make, including commits, do not require network server access. + +The first step is to install git on your system. For those new to the world of git, github has an excellent tutorial stepping you through the process, available at: http://help.github.com/ + +To check out a read-only version of the repository (no github signup required):: + + git clone git://github.com/imageworks/OpenColorIO.git ocio + +For write-access, you must first register for a Github account (free). Then, you must create a local fork of the OpenColorIO repository by visiting http://github.com/imageworks/OpenColorIO and clicking the "Fork" icon. If you get hung up on this, further instructions on this process are available at http://help.github.com/forking/ + +To check out a read-write version of the repository (github acct required):: + + git clone git@github.com:yourgitusername/OpenColorIO.git ocio + + Initialized empty Git repository in /mcp/ocio/.git/ + remote: Counting objects: 2220, done. + remote: Compressing objects: 100% (952/952), done. + remote: Total 2220 (delta 1434), reused 1851 (delta 1168) + Receiving objects: 100% (2220/2220), 2.89 MiB | 2.29 MiB/s, done. + Resolving deltas: 100% (1434/1434), done. + +Both read + read/write users should then add the Imageworks (SPI) master branch as a remote. This will allow you to more easily fetch updates as they become available:: + + cd ocio + git remote add spi git://github.com/imageworks/OpenColorIO.git + +Optionally, you may then add any additional users who have individual working forks (just as you've done). This will allow you to track, view, and potentially merge intermediate changes before they're been pushed into the main trunk. (For really bleeding edge folks). For example, to add Jeremy Selan's working fork:: + + git remote add js git://github.com/jeremyselan/OpenColorIO.git + +You should then do a git fetch, and git merge (detailed below) to download the remote branches you've just added. + + +Merging changes +*************** + +More detailed guide coming soon, for now, see http://help.github.com/remotes/ + +.. TODO: Write this
\ No newline at end of file diff --git a/docs/developers/index.rst b/docs/developers/index.rst new file mode 100644 index 0000000..67a2da2 --- /dev/null +++ b/docs/developers/index.rst @@ -0,0 +1,45 @@ +.. _developer-guide: + +Developer guide +=============== + +Some information on contributing to OCIO: + +.. toctree:: + :maxdepth: 1 + + getting_started + coding_guidelines + submitting_changes + issues + +Instructions on using OCIO: + +.. toctree:: + :maxdepth: 1 + + usage_examples + +C++ API documentation: + +.. toctree:: + :maxdepth: 1 + + api/index + +Python API documentation: + +.. toctree:: + :maxdepth: 1 + + bindings/PythonAPI + bindings/PythonTransforms + bindings/PythonTypes + +Internal Architecture: + +.. toctree:: + :maxdepth: 1 + + internal_architecture + diff --git a/docs/developers/internal_architecture.rst b/docs/developers/internal_architecture.rst new file mode 100644 index 0000000..d74bd0d --- /dev/null +++ b/docs/developers/internal_architecture.rst @@ -0,0 +1,287 @@ +Internal Architecture Overview +============================== + +External API +************ + + +Configs +~~~~~~~ + +At the highest level, we have OCIO::Configs. This represents the entirety of the +current color "universe". Configs are serialized as .ocio files, read at runtime, +and are often used in a 'read-only' context. + +Config are loaded at runtime to allow for customized color handling in a show- +dependent manner. + +Example Configs: + +* ACES (Acacdemy's standard color workflow) +* spi-vfx (Used on some Imageworks VFX shows such as spiderman, etc). +* and others + + +ColorSpaces +~~~~~~~~~~~ + +The meat of an OCIO::Config is a list of named ColorSpaces. ColorSpace often +correspond to input image states, output image states, or image states used for +internal processing. + +Example ColorSpaces (from ACES configuration): + +* aces (HDR, scene-linear) +* adx10 (log-like density encoding space) +* slogf35 (sony F35 slog camera encoding) +* rrt_srgb (baked in display transform, suitable for srgb display) +* rrt_p3dci (baked in display transform, suitable for dcip3 display) + + + +Transforms +~~~~~~~~~~ + +ColorSpaces contain an ordered list of transforms, which define the conversion +to and from the Config's "reference" space. + +Transforms are the atomic units available to the designer in order to specify a +color conversion. + +Examples of OCIO::Transforms are: + +* File-based transforms (1d lut, 3d lut, mtx... anything, really.) +* Math functions (gamma, log, mtx) +* The 'meta' GroupTransform, which contains itself an ordered lists of transforms +* The 'meta' LookTransform, which contains an ordered lists of transforms + +For example, the adx10 ColorSpace (in one particular ACES configuration) +-Transform FROM adx, to our reference ColorSpace: + +#. Apply FileTransform adx_adx10_to_cdd.spimtx +#. Apply FileTransform adx_cdd_to_cid.spimtx +#. Apply FileTransform adx_cid_to_rle.spi1d +#. Apply LogTransform base 10 (inverse) +#. Apply FileTransform adx_exp_to_aces.spimtx + +If we have an image in the reference ColorSpace (unnamed), we can convert TO +adx by applying each in the inverse direction: + +#. Apply FileTransform adx_exp_to_aces.spimtx (inverse) +#. Apply LogTransform base 10 (forward) +#. Apply FileTransform adx_cid_to_rle.spi1d (inverse) +#. Apply FileTransform adx_cdd_to_cid.spimtx (inverse) +#. Apply FileTransform adx_adx10_to_cdd.spimtx (inverse) + +Note that this isn't possible in all cases (what if a lut or matrix is not +invertible?), but conceptually it's a simple way to think about the design. + + + +Summary +~~~~~~~ + +Configs and ColorSpaces are just a bookkeeping device used to get and ordered +lists of Transforms corresponding to image color transformation. + +Transforms are visible to the person AUTHORING the OCIO config, but are +NOT visible to the client applications. Client apps need only concern themselves +with Configs and Processors. + + + + +OCIO::Processors +~~~~~~~~~~~~~~~~ + +A processor corresponds to a 'baked' color transformation. You specify two arguments +when querying a processor: the :ref:`colorspace_section` you are coming from, +and the :ref:`colorspace_section` you are going to. + +Once you have the processor, you can apply the color transformation using the +"apply" function. For the CPU veseion, first wrap your image in an +ImageDesc class, and then call apply to process in place. + +Example: + +.. code-block:: cpp + + #include <OpenColorIO/OpenColorIO.h> + namespace OCIO = OCIO_NAMESPACE; + + try + { + // Get the global OpenColorIO config + // This will auto-initialize (using $OCIO) on first use + OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig(); + + // Get the processor corresponding to this transform. + // These strings, in this example, are specific to the above + // example. ColorSpace names should NEVER be hard-coded into client + // software, but should be dynamically queried at runtime from the library + OCIO::ConstProcessorRcPtr processor = config->getProcessor("adx10", "aces"); + + // Wrap the image in a light-weight ImageDescription + OCIO::PackedImageDesc img(imageData, w, h, 4); + + // Apply the color transformation (in place) + processor->apply(img); + } + catch(OCIO::Exception & exception) + { + std::cerr << "OpenColorIO Error: " << exception.what() << std::endl; + } + + +The GPU code path is similar. You get the processor from the config, and then +query the shaderText and the lut3d. The client loads these to the GPU themselves, +and then makes the appropriate calls to the newly defined function. + +See `src/apps/ociodisplay` for an example. + + + +Internal API +************ + + +The Op Abstraction +~~~~~~~~~~~~~~~~~~ + +It is a useful abstraction, both for code-reuse and optimization, to not relying +on the transforms to do pixel processing themselves. + +Consider that the FileTransform represents a wide-range of image processing +operations (basically all of em), many of which are really complex. For example, +the houdini lut format in a single file may contain a log convert, a 1d lut, and +then a 3d lut; all of which need to be applied in a row! If we dont want the +FileTransform to know how to process all possible pixel operations, it's much +simpler to make light-weight processing operations, which the transforms can +create to do the dirty work as needed. + +All image processing operations (ops) are a class that present the same +interface, and it's rather simple: +(src/core/Op.h) + +.. code-block:: cpp + + virtual void apply(float* rgbaBuffer, long numPixels) + +Basically, given a packed float array with the specified number of pixels, process em. + +Examples of ops include Lut1DOp, Lut3DOp, MtxOffsetOp, LogOp, etc. + +Thus, the job of a transform becomes much simpler and they're only responsible +for converting themselves to a list of ops. A simple FileTransform that only has +a single 1D lut internally may just generate a single Lut1DOp, but a +FileTransform that references a more complex format (such as the houdini lut case +referenced above) may generate a few ops: + +.. code-block:: cpp + + void FileFormatHDL::BuildFileOps(OpRcPtrVec & ops, + const Config& /*config*/, + const ConstContextRcPtr & /*context*/, + CachedFileRcPtr untypedCachedFile, + const FileTransform& fileTransform, + TransformDirection dir) const { + + // Code omitted which loads the lut file into the file cache... + + CreateLut1DOp(ops, cachedFile->lut1D, + fileTransform.getInterpolation(), dir); + CreateLut3DOp(ops, cachedFile->lut3D, + fileTransform.getInterpolation(), dir); + +See (src/core/*Ops.h) for the available ops. + +Note that while compositors often have complex, branching trees of image processing +operations, we just have a linear list of ops, lending itself very well to +optimization. + +Before the ops are run, they are optimized. (Collapsed with appropriate neighbors, etc). + + +An Example +~~~~~~~~~~ + +Let us consider the internal steps when getProcessor() is called to convert +from ColorSpace 'adx10' to ColorSpace 'aces'. + +* The first step is to turn this ColorSpace conversion into an ordered list of +transforms. We do this by creating a single of the conversions from 'adx10' +to reference, and then adding the transforms required to go from reference to +'aces'. + +* The Transform list is then converted into a list of ops. It is during this +stage luts, are loaded, etc. + + + +CPU CODE PATH +~~~~~~~~~~~~~ + +The master list of ops is then optimized, and stored internally in the processor. + +.. code-block:: cpp + + FinalizeOpVec(m_cpuOps); + +During Processor::apply(...), a subunit of pixels in the image are formatted into a sequential rgba block. (Block size is optimized for computational (SSE) simplicity and performance, and is typically similar in size to an image scanline) + +.. code-block:: cpp + + float * rgbaBuffer = 0; + long numPixels = 0; + while(true) { + scanlineHelper.prepRGBAScanline(&rgbaBuffer, &numPixels); + ... + +Then for each op, op->apply is called in-place. + +.. code-block:: cpp + + for(OpRcPtrVec::size_type i=0, size = m_cpuOps.size(); i<size; ++i) + { + m_cpuOps[i]->apply(rgbaBuffer, numPixels); + } + +After all ops have been applied, the results are copied back to the source + +.. code-block:: cpp + + scanlineHelper.finishRGBAScanline(); + + + +GPU CODE PATH +~~~~~~~~~~~~~ + +#. The master list of ops is partitioned into 3 ordered lists: + +- As many ops as possible from the BEGINNING of the op-list that can be done + analytically in shader text. (called gpu-preops) +- As many ops as possible from the END of the op-list that can be done + analytically in shader text. (called gpu-postops) +- The left-over ops in the middle that cannot support shader text, and thus + will be baked into a 3dlut. (called gpu-lattice) + +#. Between the first an the second lists (gpu-preops, and gpu-latticeops), we +anaylze the op-stream metadata and determine the appropriate allocation to use. +(to minimize clamping, quantization, etc). This is accounted for here by +interserting a forward allocation to the end of the pre-ops, and the inverse +allocation to the start of the lattice ops. + +See https://github.com/imageworks/OpenColorIO/blob/master/src/core/NoOps.cpp#L183 + +#. The 3 lists of ops are then optimized individually, and stored on the processor. +The Lut3d is computed by applying the gpu-lattice ops, on the CPU, to a lut3d +image. + +The shader text is computed by calculating the shader for the gpu-preops, adding +a sampling function of the 3d lut, and then calculating the shader for the gpu +post ops. + + + + diff --git a/docs/developers/issues.rst b/docs/developers/issues.rst new file mode 100644 index 0000000..e26bd3b --- /dev/null +++ b/docs/developers/issues.rst @@ -0,0 +1,4 @@ +Issues +====== + +Please visit http://github.com/imageworks/OpenColorIO/issues for an up to date listing of bugs, feature requests etc
\ No newline at end of file diff --git a/docs/developers/submitting_changes.rst b/docs/developers/submitting_changes.rst new file mode 100644 index 0000000..ca1169d --- /dev/null +++ b/docs/developers/submitting_changes.rst @@ -0,0 +1,14 @@ +Submitting Changes +================== + +Code Review +*********** + +Ask early, and ask often! + +All new contributors are highly encouraged to post development ideas, questions, +or any other thoughts to the :ref:`mailing_lists` before starting to code. This +greatly improves the process and quality of the resulting library. Code +reviews (particularly for non-trivial changes) are typically far simpler if the +reviewers are aware of a development task beforehand. (And, who knows? Maybe they +will have implementation suggestions as well!) diff --git a/docs/developers/usage_examples.rst b/docs/developers/usage_examples.rst new file mode 100644 index 0000000..8dace70 --- /dev/null +++ b/docs/developers/usage_examples.rst @@ -0,0 +1,357 @@ +.. _developers-usageexamples: + +Usage Examples +============== + +Some examples of using the OCIO API, via both C++ and the Python bindings. + +For further examples, see the ``src/apps/`` directory in the git repository + +.. _usage_applybasic: + +Applying a basic ColorSpace transform, using the CPU +**************************************************** +This describes what code is used to convert from a specified source +:cpp:class:`ColorSpace` to a specified destination :cpp:class:`ColorSpace`. +If you are using the OCIO Nuke plugins, the OCIOColorSpace node performs these +steps internally. + +#. **Get the Config.** + This represents the entirety of the current color "universe". It can either + be initialized by your app at startup or created explicitly. In common + usage, you can just query :cpp:func:`GetCurrentConfig`, which will auto + initialize on first use using the :envvar:`OCIO` environment variable. + +#. **Get Processor from the Config.** + A processor corresponds to a 'baked' color transformation. You specify two + arguments when querying a processor: the :ref:`colorspace_section` you are + coming from, and the :ref:`colorspace_section` you are going to. + :ref:`cfgcolorspaces_section` ColorSpaces can be either explicitly named + strings (defined by the current configuration) or can be + :ref:`cfgroles_section` (essentially :ref:`colorspace_section` aliases) + which are consistent across configurations. Constructing a + :cpp:class:`Processor` object is likely a blocking operation (thread-wise) + so care should be taken to do this as infrequently as is sensible. Once per + render 'setup' would be appropriate, once per scanline would be + inappropriate. + +#. **Convert your image, using the Processor.** + Once you have the processor, you can apply the color transformation using + the "apply" function. In :ref:`usage_applybasic_cpp`, you apply the + processing in-place, by first wrapping your image in an + :cpp:class:`ImageDesc` class. This approach is intended to be used in high + performance applications, and can be used on multiple threads (per scanline, + per tile, etc). In :ref:`usage_applybasic_python` you call + "applyRGB" / "applyRGBA" on your sequence of pixels. Note that in both + languages, it is far more efficient to call "apply" on batches of pixels at + a time. + +.. _usage_applybasic_cpp: + +C++ +--- + +.. code-block:: cpp + + #include <OpenColorIO/OpenColorIO.h> + namespace OCIO = OCIO_NAMESPACE; + + try + { + OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig(); + ConstProcessorRcPtr processor = config->getProcessor(OCIO::ROLE_COMPOSITING_LOG, + OCIO::ROLE_SCENE_LINEAR); + + OCIO::PackedImageDesc img(imageData, w, h, 4); + processor->apply(img); + } + catch(OCIO::Exception & exception) + { + std::cerr << "OpenColorIO Error: " << exception.what() << std::endl; + } + +.. _usage_applybasic_python: + +Python +------ + +.. code-block:: py + + import PyOpenColorIO as OCIO + + try: + config = OCIO.GetCurrentConfig() + processor = config.getProcessor(OCIO.Constants.ROLE_COMPOSITING_LOG, + OCIO.Constants.ROLE_SCENE_LINEAR) + + # Apply the color transform to the existing RGBA pixel data + img = processor.applyRGBA(img) + except Exception, e: + print "OpenColorIO Error",e + +.. _usage_displayimage: + +Displaying an image, using the CPU (simple ColorSpace conversion) +***************************************************************** +Converting an image for display is similar to a normal color space conversion. +The only difference is that one has to first determine the name of the display +(destination) ColorSpace by querying the config with the device name and +transform name. + +#. **Get the Config.** + See :ref:`usage_applybasic` for details. + +#. **Lookup the display ColorSpace.** + The display :cpp:class:`ColorSpace` is queried from the configuration using + :cpp:func:`Config::getDisplayColorSpaceName`. If the user has specified + value for the ``device`` or the ``displayTransformName``, use them. If these + values are unknown default values can be queried (as shown below). + +#. **Get the processor from the Config.** + See :ref:`usage_applybasic` for details. + +#. **Convert your image, using the processor.** + See :ref:`usage_applybasic` for details. + +C++ +--- + +.. code-block:: cpp + + #include <OpenColorIO/OpenColorIO.h> + namespace OCIO = OCIO_NAMESPACE; + + OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig(); + + // If the user hasn't picked a display, use the defaults... + const char * device = config->getDefaultDisplayDeviceName(); + const char * transformName = config->getDefaultDisplayTransformName(device); + const char * displayColorSpace = config->getDisplayColorSpaceName(device, transformName); + + ConstProcessorRcPtr processor = config->getProcessor(OCIO::ROLE_SCENE_LINEAR, + displayColorSpace); + + OCIO::PackedImageDesc img(imageData, w, h, 4); + processor->apply(img); + +Python +------ + +.. code-block:: python + + import PyOpenColorIO as OCIO + + config = OCIO.GetCurrentConfig() + + device = config.getDefaultDisplayDeviceName() + transformName = config.getDefaultDisplayTransformName(device) + displayColorSpace = config.getDisplayColorSpaceName(device, transformName) + + processor = config.getProcessor(OCIO.Constants.ROLE_SCENE_LINEAR, displayColorSpace) + + processor.applyRGB(imageData) + + +Displaying an image, using the CPU (Full Display Pipeline) +********************************************************** + +This alternative version allows for a more complex displayTransform, allowing +for all of the controls typically added to real-world viewer interfaces. For +example, options are allowed to control which channels (red, green, blue, +alpha, luma) are visible, as well as allowing for optional color corrections +(such as an exposure offset in scene linear). If you are using the OCIO Nuke +plugins, the OCIODisplay node performs these steps internally. + +#. **Get the Config.** + See :ref:`usage_applybasic` for details. +#. **Lookup the display ColorSpace.** + See :ref:`usage_displayimage` for details +#. **Create a new DisplayTransform.** + This transform will embody the full 'display' pipeline you wish to control. + The user is required to call + :cpp:func:`DisplayTransform::setInputColorSpaceName` to set the input + ColorSpace, as well as + :cpp:func:`DisplayTransform::setDisplayColorSpaceName` (with the results of + :cpp:func:`Config::getDisplayColorSpaceName`). +#. **Set any additional DisplayTransform options.** + If the user wants to specify a channel swizzle, a scene-linear exposure + offset, an artistic look, this is the place to add it. See below for an + example. Note that although we provide recommendations for display, any + transforms are allowed to be added into any of the slots. So if for your app + you want to add 3 transforms into a particular slot (chained together), you + are free to wrap them in a :cpp:class:`GroupTransform` and set it + accordingly! +#. **Get the processor from the Config.** + The processor is then queried from the config passing the new + :cpp:class:`DisplayTransform` as the argument. Once the processor has been + returned, the original :cpp:class:`DisplayTransform` is no longer necessary + to hold onto. (Though if you'd like to for re-use, there is no problem doing + so). +#. **Convert your image, using the processor.** + See :ref:`usage_applybasic` for details. + +C++ +--- + +.. code-block:: cpp + + // Step 1: Get the config + OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig(); + + // Step 2: Lookup the display ColorSpace + const char * device = config->getDefaultDisplayDeviceName(); + const char * transformName = config->getDefaultDisplayTransformName(device); + const char * displayColorSpace = config->getDisplayColorSpaceName(device, transformName); + + // Step 3: Create a DisplayTransform, and set the input and display ColorSpaces + // (This example assumes the input is scene linear. Adapt as needed.) + + OCIO::DisplayTransformRcPtr transform = OCIO::DisplayTransform::Create(); + transform->setInputColorSpaceName( OCIO::ROLE_SCENE_LINEAR ); + transform->setDisplayColorSpaceName( displayColorSpace ); + + // Step 4: Add custom transforms for a 'canonical' Display Pipeline + + // Add an fstop exposure control (in SCENE_LINEAR) + float gain = powf(2.0f, exposure_in_stops); + const float slope3f[] = { gain, gain, gain }; + OCIO::CDLTransformRcPtr cc = OCIO::CDLTransform::Create(); + cc->setSlope(slope3f); + transform->setLinearCC(cc); + + // Add a Channel view 'swizzle' + + // 'channelHot' controls which channels are viewed. + int channelHot[4] = { 1, 1, 1, 1 }; // show rgb + //int channelHot[4] = { 1, 0, 0, 0 }; // show red + //int channelHot[4] = { 0, 0, 0, 1 }; // show alpha + //int channelHot[4] = { 1, 1, 1, 0 }; // show luma + + float lumacoef[3]; + config.getDefaultLumaCoefs(lumacoef); + + float m44[16]; + float offset[4]; + OCIO::MatrixTransform::View(m44, offset, channelHot, lumacoef); + OCIO::MatrixTransformRcPtr swizzle = OCIO::MatrixTransform::Create(); + swizzle->setValue(m44, offset); + transform->setChannelView(swizzle); + + // And then process the image normally. + OCIO::ConstProcessorRcPtr processor = config->getProcessor(transform); + + OCIO::PackedImageDesc img(imageData, w, h, 4); + processor->apply(img); + +Python +------ + +.. code-block:: python + + import PyOpenColorIO as OCIO + + # Step 1: Get the config + config = OCIO.GetCurrentConfig() + + # Step 2: Lookup the display ColorSpace + device = config.getDefaultDisplayDeviceName() + transformName = config.getDefaultDisplayTransformName(device) + displayColorSpace = config.getDisplayColorSpaceName(device, transformName) + + # Step 3: Create a DisplayTransform, and set the input and display ColorSpaces + # (This example assumes the input is scene linear. Adapt as needed.) + + transform = OCIO.DisplayTransform() + transform.setInputColorSpaceName(OCIO.Constants.ROLE_SCENE_LINEAR) + transform.setDisplayColorSpaceName(displayColorSpace) + + # Step 4: Add custom transforms for a 'canonical' Display Pipeline + + # Add an fstop exposure control (in SCENE_LINEAR) + gain = 2**exposure + slope3f = (gain, gain, gain) + + cc = OCIO.CDLTransform() + cc.setSlope(slope3f) + + transform.setLinearCC(cc) + + # Add a Channel view 'swizzle' + + channelHot = (1, 1, 1, 1) # show rgb + # channelHot = (1, 0, 0, 0) # show red + # channelHot = (0, 0, 0, 1) # show alpha + # channelHot = (1, 1, 1, 0) # show luma + + lumacoef = config.getDefaultLumaCoefs() + + m44, offset = OCIO.MatrixTransform.View(channelHot, lumacoef) + + swizzle = OCIO.MatrixTransform() + swizzle.setValue(m44, offset) + transform.setChannelView(swizzle) + + # And then process the image normally. + processor = config.getProcessor(transform) + + print processor.applyRGB(imageData) + + +Displaying an image, using the GPU +********************************** + +Applying OpenColorIO's color processing using GPU processing is +straightforward, provided you have the capability to upload custom shader code +and a custom 3D Lookup Table (3DLUT). + +#. **Get the Processor.** + This portion of the pipeline is identical to the CPU approach. Just get the + processor as you normally would have, see above for details. +#. **Create a GpuShaderDesc.** +#. **Query the GPU Shader Text + 3D LUT.** +#. **Configure the GPU State.** +#. **Draw your image.** + +C++ +--- + +This example is available as a working app in the OCIO source: src/apps/ociodisplay. + +.. code-block:: cpp + + // Step 0: Get the processor using any of the pipelines mentioned above. + OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig(); + const char * device = config->getDefaultDisplayDeviceName(); + const char * transformName = config->getDefaultDisplayTransformName(device); + const char * displayColorSpace = config->getDisplayColorSpaceName(device, transformName); + ConstProcessorRcPtr processor = config->getProcessor(OCIO::ROLE_SCENE_LINEAR, + displayColorSpace); + + // Step 1: Create a GPU Shader Description + GpuShaderDesc shaderDesc; + shaderDesc.setLanguage(OCIO::GPU_LANGUAGE_GLSL_1_0); + shaderDesc.setFunctionName("OCIODisplay"); + const int LUT3D_EDGE_SIZE = 32; + shaderDesc.setLut3DEdgeLen(LUT3D_EDGE_SIZE); + + // Step 2: Compute and the 3D LUT + // Optional Optimization: + // Only do this the 3D LUT's contents + // are different from the last drawn frame. + // Use getGpuLut3DCacheID to compute the cacheID. + // cheaply. + // + // std::string lut3dCacheID = processor->getGpuLut3DCacheID(shaderDesc); + int num3Dentries = 3*LUT3D_EDGE_SIZE*LUT3D_EDGE_SIZE*LUT3D_EDGE_SIZE; + std::vector<float> g_lut3d; + g_lut3d.resize(num3Dentries); + processor->getGpuLut3D(&g_lut3d[0], shaderDesc); + + // Load the data into an OpenGL 3D Texture + glGenTextures(1, &g_lut3d_textureID); + glBindTexture(GL_TEXTURE_3D, g_lut3d_textureID); + glTexImage3D(GL_TEXTURE_3D, 0, GL_RGB, + LUT3D_EDGE_SIZE, LUT3D_EDGE_SIZE, LUT3D_EDGE_SIZE, + 0, GL_RGB,GL_FLOAT, &g_lut3d[0]); + + // Step 3: Query diff --git a/docs/downloads.rst b/docs/downloads.rst new file mode 100644 index 0000000..d5e6615 --- /dev/null +++ b/docs/downloads.rst @@ -0,0 +1,41 @@ +.. _downloads: + +Downloads +========= + +* Sample OCIO Configurations -- `.zip <http://github.com/imageworks/OpenColorIO-Configs/zipball/master>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO-Configs/tarball/master>`__ +* Reference Images v1.0v4 -- `.tgz <http://code.google.com/p/opencolorio/downloads/detail?name=ocio-images.1.0v4.tgz>`__ +* Core Library v1.0.8 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.8>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.8>`__ +* Core Library latest -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/master>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/master>`__ + +Per-version updates: :ref:`changelog-main`. + +Build instructions: :ref:`building-from-source`. + +.. _contributor-license-agreements: + +Contributor License Agreements +****************************** +Please see the `Imageworks Open Source website <http://opensource.imageworks.com/cla/>`__ + +Deprecated Downloads +******************** +* Reference Images v1.0v2 `tgz <http://code.google.com/p/opencolorio/downloads/detail?name=ocio-images.1.0v2.tgz>`__ +* Reference Images v1.0v1 `tgz <http://code.google.com/p/opencolorio/downloads/detail?name=ocio-images.1.0v1.tgz>`__ + +* Core Library v1.0.7 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.7>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.7>`__ +* Core Library v1.0.6 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.6>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.6>`__ +* Core Library v1.0.5 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.5>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.5>`__ +* Core Library v1.0.4 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.4>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.4>`__ +* Core Library v1.0.3 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.3>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.3>`__ +* Core Library v1.0.2 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.2>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.2>`__ +* Core Library v1.0.1 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.1>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.1>`__ +* Core Library v1.0.0 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v1.0.0>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v1.0.0>`__ + +* Color Config v0.7v4 `tgz <http://code.google.com/p/opencolorio/downloads/detail?name=ocio-configs.0.7v4.tgz>`__ (OCIO v0.7.6+) +* Core Library v0.8.7 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v0.8.7>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v0.8.7>`__ +* Core Library v0.7.9 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v0.7.9>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v0.7.9>`__ +* Core Library v0.6.1 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v0.6.1>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v0.6.1>`__ +* Core Library v0.5.16 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v0.5.16>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v0.5.16>`__ +* Core Library v0.5.8 -- `.zip <http://github.com/imageworks/OpenColorIO/zipball/v0.5.8>`__ `.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/v0.5.8>`__ + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..3757b66 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,77 @@ +Home +==== + +.. include:: README + +.. _mailing_lists: + +Mailing lists +""""""""""""" + +There are two mailing lists associated with OpenColorIO: + +`ocio-users <http://groups.google.com/group/ocio-users>`__\ ``@googlegroups.com`` + For end users (artists, often) interested in OCIO profile design, + facility color management, and workflow. + +`ocio-dev <http://groups.google.com/group/ocio-dev>`__\ ``@googlegroups.com`` + For developers interested OCIO APIs, code integration, compilation, etc. + +Using OpenColorIO +""""""""""""""""" + +Most users will likely want to use the OpenColorIO that comes precompiled with +their applications. See the :ref:`compatiblesoftware` for further details on +each application. + +Note that OCIO configurations aren't required to do any 'real' work, and are +available separately on the :ref:`downloads` section of this site. Example +images are also available. For assistance customizing .ocio configurations, +contact the ocio-users email alias. + +- Step 1: set the OCIO environment-variable to /path/to/your/profile.ocio +- Step 2: Launch supported application. + +If you are on a platform that is not envvar friendly, most applications also +provide a menu option to select a different OCIO configuration after launch. + +Please be sure to select a profile that matches your color workflow (VFX work +typically requires a different profile than animated features). If you need +assistance picking a profile, email ocio-users. + +Downloading and building the code +""""""""""""""""""""""""""""""""" + +Source code is available on Github at +http://github.com/imageworks/OpenColorIO + +Download a `.zip <http://github.com/imageworks/OpenColorIO/zipball/master>`_ or +`.tar.gz <http://github.com/imageworks/OpenColorIO/tarball/master>`_ of the +current state of the repository. + +Please see the :ref:`developer-guide` for more info, and contact ocio-dev with any +questions. + +.. toctree:: + :hidden: + :maxdepth: 2 + + self + CompatibleSoftware + + configurations/index + installation + + userguide/index + + developers/index + + FAQ + downloads + + ChangeLog + License + +:ref:`search` + +:ref:`genindex` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..e6e26e2 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,234 @@ +Installation +============ + +.. _building-from-source: + +Building from source +******************** + +While there is a huge range of possible setups, the following steps +should work on OS X and most Linux distros. + +The basic requirements are: + +- cmake >= 2.8 +- (optional) Python 2.x (for the Python bindings) +- (optional) Nuke 6.x (for the Nuke nodes) +- (optional) OpenImageIO (for apps including ocioconvert) +- (optional) Truelight SDK (for TruelightTransform) + +To keep things simple, this guide will use the following example +paths - these will almost definitely be different for you: + +- source code: ``/source/ocio`` +- the temporary build location: ``/tmp/ociobuild`` +- the final install directory: ``/software/ocio`` + +First make the build directory and cd to it:: + + $ mkdir /tmp/ociobuild + $ cd /tmp/ociobuild + +Next step is to run cmake, which looks for things such as the +compiler's required arguments, optional requirements like Python, +Nuke, OpenImageIO etc + +As we want to install OCIO to a custom location (instead of the +default ``/usr/local``), we will run cmake with +``CMAKE_INSTALL_PREFIX`` + +Still in ``/tmp/ociobuild``, run:: + + $ cmake -D CMAKE_INSTALL_PREFIX=/software/ocio /source/ocio + +The last argument is the location of the OCIO source code (containing +the main CMakeLists.txt file). You should see something along the +lines of:: + + -- Configuring done + -- Generating done + -- Build files have been written to: /tmp/ociobuild + +Next, build everything (with the ``-j`` flag to build using 8 +threads):: + + $ make -j8 + +This should complete in a few minutes. Finally, install the files into +the specified location:: + + $ make install + +If nothing went wrong, ``/software/ocio`` should look something like +this:: + + $ cd /software/ocio + $ ls + bin/ include/ lib/ + $ ls bin/ + ocio2icc ociobakelut ociocheck + $ ls include/ + OpenColorIO/ PyOpenColorIO/ pkgconfig/ + $ ls lib/ + libOpenColorIO.a libOpenColorIO.dylib + + +.. _enabling-optional-components: + +Enabling optional components +---------------------------- + +The OpenColorIO library is probably not all you want - the Python +libraries bindings, the Nuke nodes and several applications are only +built if their dependencies are found. + +In the case of the Python bindings, the dependencies are the Python +headers for the version you wish to use. These may be picked up by +default - if so, when you run cmake you would see:: + + -- Python 2.6 okay, will build the Python bindings against .../include/python2.6 + +If not, you can point cmake to correct Python executable using the +``-D PYTHON=...`` cmake flag:: + + $ cmake -D PYTHON=/my/custom/python2.6 /source/ocio + +Same process with Nuke (although it less likely to be picked up +automatically). Point cmake to your Nuke install directory by adding +``-D NUKE_INSTALL_PATH``:: + + $ cmake -D PYTHON=/my/custom/python2.6 -D NUKE_INSTALL_PATH=/Applications/Nuke6.2v1/Nuke6.2v1.app/Contents/MacOS/ /source/ocio + +The ``NUKE_INSTALL_PATH`` directory should contain the Nuke executable +(e.g Nuke6.2v1), and a ``include/`` directory containing ``DDImage/`` +and others. + +If set correctly, you will see something similar to:: + + -- Found Nuke: /Applications/Nuke6.2v1/Nuke6.2v1.app/Contents/MacOS/include + -- Nuke_API_VERSION: --6.2-- + +The Nuke plugins are installed into ``lib/nuke$MAJOR.$MINOR/``, e.g +``lib/nuke6.2/OCIODisdplay.so`` + + +.. note:: + + If you are using the Nuke plugins, you should compile the Python + bindings for the same version of Python that Nuke uses + internally. For Nuke 6.0 and 6.1 this is Python 2.5, and for 6.2 + it is Python 2.6 + +The applications included with OCIO have various dependencies - to +determine these, look at the CMake output when first run:: + + -- Not building ocioconvert. Requirement(s) found: OIIO:FALSE + + +.. _quick-env-config: + +Quick environment configuration +******************************* + +The quickest way to set the required :ref:`environment-setup` is to +source the ``share/ocio/setup_ocio.sh`` script installed with OCIO. + +For a simple single-user setup, add the following to ``~/.bashrc`` +(assuming you are using bash, and the example install directory of +``/software/ocio``):: + + source /software/ocio/share/ocio/setup_ocio.sh + +The only environment variable you must configure manually is +:envvar:`OCIO`, which points to the configuration file you wish to +use. For prebuilt config files, see the +:ref:`downloads` section + +To do this, you would add a line to ``~/.bashrc`` (or a per-project +configuration script etc), for example:: + + export OCIO="/path/to/my/config.ocio" + + +.. _nuke-configuration: + +Nuke Configuration +****************** + +If you specified the ``NUKE_INSTALL_PATH`` option when running cmake, +you should have a ``/software/ocio/lib/nuke6.2`` directory containing +various files. + +If you have followed :ref:`quick-env-config`, the plugins should be +functional. However, one common additional configuration step is to +register an OCIODisplay node for each display device/view specified in +the config. + +To do this, in a menu.py on :envvar:`NUKE_PATH` (e.g +``~/.nuke/menu.py`` for a single user setup), add the following: + +.. code-block:: python + + import ocionuke.viewer + ocionuke.viewer.populate_viewer(also_remove = "default") + +The ``also_remove`` argument can be set to either "default" to remove +the default sRGB/rec709 options, "all" to remove everything, or "none" +to leave existing viewer processes untouched. + +Alternatively, if your workflow has different requirements, you can +copy the function and modify it as required, or use it as reference to +write your own, better viewer setup function! + +.. literalinclude:: viewer.py + :language: python + + +.. _environment-setup: + +Environment variables +********************* + +.. envvar:: OCIO + + This variable needs to point to the global OCIO config file, e.g + ``config.ocio`` + +.. envvar:: DYLD_LIBRARY_PATH + + The ``lib/`` folder (containing ``libOpenColorIO.dylib``) must be + on the ``DYLD_LIBRARY_PATH`` search path, or you will get an error + similar to:: + + dlopen(.../OCIOColorSpace.so, 2): Library not loaded: libOpenColorIO.dylib + Referenced from: .../OCIOColorSpace.so + Reason: image not found + + This applies to anything that links against OCIO, including the + Nuke nodes, and the ``PyOpenColorIO`` Python bindings. + +.. envvar:: LD_LIBRARY_PATH + + Equivalent to the ``DYLD_LIBRARY_PATH`` on Linux + +.. envvar:: PYTHONPATH + + Python's module search path. If you are using the PyOpenColorIO + module, you must add ``lib/python2.x`` to this search path (e.g + ``python/2.5``), or importing the module will fail:: + + >>> import PyOpenColorIO + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + ImportError: No module named PyOpenColorIO + + Note that :envvar:`DYLD_LIBRARY_PATH` or :envvar:`LD_LIBRARY_PATH` + must be set correctly for the module to work. + +.. envvar:: NUKE_PATH + + Nuke's customisation search path, where it will look for plugins, + gizmos, init.py and menu.py scripts and other customisations. + + This should point to both ``lib/nuke6.2/`` (or whatever version + the plugins are built against), and ``share/nuke/`` diff --git a/docs/ociotheme/layout.html b/docs/ociotheme/layout.html new file mode 100644 index 0000000..43a5858 --- /dev/null +++ b/docs/ociotheme/layout.html @@ -0,0 +1,74 @@ +{# + haiku/layout.html + ~~~~~~~~~~~~~~~~~ + + Sphinx layout template for the haiku theme. + + :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{% extends "basic/layout.html" %} +{% set script_files = script_files + ['_static/theme_extras.js'] %} +{% set css_files = css_files + ['_static/print.css'] %} + +{% block relbar1 %}{% endblock %} +{% block relbar2 %}{% endblock %} + +{% block htmltitle %} + <title>OpenColorIO</title> +{% endblock %} + +{% macro nav() %} + <p> + {%- block haikurel1 %} + {%- endblock %} + {%- block haikurel2 %} + {%- endblock %} + </p> +{% endmacro %} + +{% block content %} + <div class="header"> + {%- block haikuheader %} + {%- if theme_full_logo != "false" %} + <a href="{{ pathto('index') }}"> + <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/> + </a> + {%- else %} + {%- if logo -%} + <img class="rightlogo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/> + {%- endif -%} + <h1 class="heading"><a href="{{ pathto('index') }}"> + <span>OpenColorIO</span></a></h1> + <h2 class="heading"><span>Open Source Color Management</span></h2> + {%- endif %} + {%- endblock %} + </div> + <div class="topnav"> + {{ shorttitle|e }} + </div> + <div class="content"> + {#{%- if display_toc %} + <div id="toc"> + <h3>Table Of Contents</h3> + {{ toc }} + </div> + {%- endif %}#} + <table width="100%" cellspacing="0" cellpadding="0"> + <tr> + <td width="200"> + <div class="sidebar2"> + {{toctree()}} + {%- include "searchbox.html" %} + </div> + </td> + <td width="100%" id="bodycontent"> + {% block body %}{% endblock %} + </td> + </tr></table> + <br> + </div> + <div class="bottomnav"> + {{ nav() }} + </div> +{% endblock %} diff --git a/docs/ociotheme/page.html b/docs/ociotheme/page.html new file mode 100644 index 0000000..6442a17 --- /dev/null +++ b/docs/ociotheme/page.html @@ -0,0 +1,29 @@ +{# + basic/page.html + ~~~~~~~~~~~~~~~ + + Master template for simple pages. + + :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{% extends "layout.html" %} +{% block body %} +{{ body }} + {% if pagename == "index" %} + <td width="275"> + <div class="imageBar"> + <p style="text-align: center; font-size: small;"><b>Color Transform Example</b></p> + <img src="{{ pathto('_static/clo_res19_vd16.0101.jpg', 1) }}"> + <div class="caption">Final Image: sRGB</div> + <img src="{{ pathto('_static/clo_res19_lm10.0101.jpg', 1) }}"> + <div class="caption">Digital Intermediate (DI): log dpx</div> + <img src="{{ pathto('_static/clo_res19_lnf.0101.jpg', 1) }}"> + <div class="caption">Render: scene-linear exr</div> + <p style="text-align: right">Images from "Cloudy With A Chance of Meatballs"</p> + <p style="text-align: right">Copyright 2011 Sony Pictures Inc. All Rights Reserved.</p> + <p style="text-align: right">spi-animation profile, available here.</p> + </div> + </td> + {% endif %} +{% endblock %} diff --git a/docs/ociotheme/searchbox.html b/docs/ociotheme/searchbox.html new file mode 100644 index 0000000..e631a35 --- /dev/null +++ b/docs/ociotheme/searchbox.html @@ -0,0 +1,12 @@ + +<div id="searchbox" style="display: none"> + <h3>{{ _('Quick search') }}</h3> + <form class="search" action="{{ pathto('search') }}" method="get"> + <input type="text" name="q" /> + <input type="submit" value="{{ _('Go') }}" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> +<script type="text/javascript">$('#searchbox').show(0);</script> + diff --git a/docs/ociotheme/static/alert_info_32.png b/docs/ociotheme/static/alert_info_32.png Binary files differnew file mode 100644 index 0000000..05b4fe8 --- /dev/null +++ b/docs/ociotheme/static/alert_info_32.png diff --git a/docs/ociotheme/static/alert_warning_32.png b/docs/ociotheme/static/alert_warning_32.png Binary files differnew file mode 100644 index 0000000..f13611c --- /dev/null +++ b/docs/ociotheme/static/alert_warning_32.png diff --git a/docs/ociotheme/static/bg-page.png b/docs/ociotheme/static/bg-page.png Binary files differnew file mode 100644 index 0000000..c6f3bc4 --- /dev/null +++ b/docs/ociotheme/static/bg-page.png diff --git a/docs/ociotheme/static/bullet_orange.png b/docs/ociotheme/static/bullet_orange.png Binary files differnew file mode 100644 index 0000000..7171fd5 --- /dev/null +++ b/docs/ociotheme/static/bullet_orange.png diff --git a/docs/ociotheme/static/clo_res19_lm10.0101.jpg b/docs/ociotheme/static/clo_res19_lm10.0101.jpg Binary files differnew file mode 100644 index 0000000..121f814 --- /dev/null +++ b/docs/ociotheme/static/clo_res19_lm10.0101.jpg diff --git a/docs/ociotheme/static/clo_res19_lnf.0101.jpg b/docs/ociotheme/static/clo_res19_lnf.0101.jpg Binary files differnew file mode 100644 index 0000000..0d5f4c5 --- /dev/null +++ b/docs/ociotheme/static/clo_res19_lnf.0101.jpg diff --git a/docs/ociotheme/static/clo_res19_vd16.0101.jpg b/docs/ociotheme/static/clo_res19_vd16.0101.jpg Binary files differnew file mode 100644 index 0000000..1e8ec02 --- /dev/null +++ b/docs/ociotheme/static/clo_res19_vd16.0101.jpg diff --git a/docs/ociotheme/static/ocio.css_t b/docs/ociotheme/static/ocio.css_t new file mode 100644 index 0000000..f991bba --- /dev/null +++ b/docs/ociotheme/static/ocio.css_t @@ -0,0 +1,469 @@ +/* + * haiku.css_t + * ~~~~~~~~~~~ + * + * Sphinx stylesheet -- haiku theme. + * + * Adapted from http://haiku-os.org/docs/Haiku-doc.css. + * Original copyright message: + * + * Copyright 2008-2009, Haiku. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Francois Revol <revol@free.fr> + * Stephan Assmus <superstippi@gmx.de> + * Braden Ewing <brewin@gmail.com> + * Humdinger <humdingerb@gmail.com> + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +html { + margin: 0px; + padding: 0px; + background: #FFF url(bg-page.png) top left repeat-x; +} + +body { + line-height: 1.5; + margin: auto; + padding: 0px; + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; + min-width: 59em; + color: {{ theme_textcolor }}; +} + +div.footer { + /* padding: 8px; */ + font-size: 11px; + text-align: center; + letter-spacing: 0.5px; +} + +/* Sidebar */ + +/* link colors and text decoration */ + +a:link { + font-weight: bold; + text-decoration: none; + color: {{ theme_linkcolor }}; +} + +a:visited { + font-weight: bold; + text-decoration: none; + color: {{ theme_visitedlinkcolor }}; +} + +a:hover, a:active { + text-decoration: underline; + color: {{ theme_hoverlinkcolor }}; +} + +/* Some headers act as anchors, don't give them a hover effect */ + +h1 a:hover, a:active { + text-decoration: none; + color: {{ theme_headingcolor }}; +} + +h2 a:hover, a:active { + text-decoration: none; + color: {{ theme_headingcolor }}; +} + +h3 a:hover, a:active { + text-decoration: none; + color: {{ theme_headingcolor }}; +} + +h4 a:hover, a:active { + text-decoration: none; + color: {{ theme_headingcolor }}; +} + +a.headerlink { + color: #a7ce38; + padding-left: 5px; +} + +a.headerlink:hover { + color: #a7ce38; +} + +/* basic text elements */ + +div.content { + margin-top: 20px; + margin-left: 0px; + margin-right: 0px; + margin-bottom: 50px; + font-size: 0.9em; +} + +/* heading and navigation */ + +div.header { + position: relative; + left: 0px; + top: 0px; + height: 85px; + /* background: #eeeeee; */ + padding: 0 40px; +} +div.header h1 { + font-size: 1.6em; + font-weight: normal; + letter-spacing: 1px; + color: {{ theme_headingcolor }}; + border: 0; + margin: 0; + padding-top: 15px; +} +div.header h1 a { + font-weight: normal; + color: {{ theme_headingcolor }}; +} +div.header h2 { + font-size: 1.3em; + font-weight: normal; + letter-spacing: 1px; + text-transform: uppercase; + color: #aaa; + border: 0; + margin-top: -3px; + padding: 0; +} + +div.header img.rightlogo { + float: right; +} + + +div.title { + font-size: 1.3em; + font-weight: bold; + color: {{ theme_headingcolor }}; + border-bottom: dotted thin #e0e0e0; + margin-bottom: 25px; +} +div.topnav { + background: #e0e0e0; + font-size: 0.8em; + text-align: right; +} +div.topnav p { + margin-top: 0; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 0px; + text-align: right; + font-size: 0.8em; +} +div.bottomnav { + background: #eeeeee; +} +div.bottomnav p { + margin-right: 40px; + text-align: right; + font-size: 0.8em; +} + +a.uplink { + font-weight: normal; +} + + +/* contents box */ + +table.index { + /*margin: 0px 0px 30px 30px;*/ + padding: 1px; + border-width: 1px; + border-style: dotted; + border-color: #e0e0e0; +} +table.index tr.heading { + background-color: #e0e0e0; + text-align: center; + font-weight: bold; + font-size: 1.1em; +} +table.index tr.index { + background-color: #eeeeee; +} +table.index td { + padding: 5px 20px; +} + +table.index a:link, table.index a:visited { + font-weight: normal; + text-decoration: none; + color: {{ theme_linkcolor }}; +} +table.index a:hover, table.index a:active { + text-decoration: underline; + color: {{ theme_hoverlinkcolor }}; +} + + +/* Haiku User Guide styles and layout */ + +/* Rounded corner boxes */ +/* Common declarations */ +div.admonition { + -webkit-border-radius: 10px; + -khtml-border-radius: 10px; + -moz-border-radius: 10px; + border-radius: 10px; + border-style: dotted; + border-width: thin; + border-color: #dcdcdc; + padding: 10px 15px 10px 15px; + margin-bottom: 15px; + margin-top: 15px; +} +div.note { + padding: 10px 15px 10px 80px; + background: #e4ffde url(alert_info_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.warning { + padding: 10px 15px 10px 80px; + background: #fffbc6 url(alert_warning_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.seealso { + background: #e4ffde; +} + +/* More layout and styles */ +h1 { + font-size: 1.3em; + font-weight: bold; + color: {{ theme_headingcolor }}; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h2 { + font-size: 1.2em; + font-weight: normal; + color: {{ theme_headingcolor }}; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h3 { + font-size: 1.1em; + font-weight: normal; + color: {{ theme_headingcolor }}; + margin-top: 30px; +} + +h4 { + font-size: 1.0em; + font-weight: normal; + color: {{ theme_headingcolor }}; + margin-top: 30px; +} + +p { + text-align: justify; +} + +p.last { + margin-bottom: 0; +} + +ol { + padding-left: 20px; +} + +ul { + padding-left: 5px; + margin-top: 3px; +} + +li { + line-height: 1.3; +} + +div.content ul > li { + -moz-background-clip:border; + -moz-background-inline-policy:continuous; + -moz-background-origin:padding; + background: transparent url(bullet_orange.png) no-repeat scroll left 0.45em; + list-style-image: none; + list-style-type: none; + padding: 0 0 0 1.666em; + margin-bottom: 3px; + font-weight: normal; +} + +td { + vertical-align: top; +} + +tt { + background-color: #e2e2e2; + font-size: 1.0em; + font-family: monospace; +} + +pre { + border-color: #0c3762; + border-style: dotted; + border-width: thin; + margin: 0 0 12px 0; + padding: 0.8em; + background-color: #f0f0f0; +} + +hr { + border-top: 1px solid #ccc; + border-bottom: 0; + border-right: 0; + border-left: 0; + margin-bottom: 10px; + margin-top: 20px; +} + +/* printer only pretty stuff */ +@media print { + .noprint { + display: none; + } + /* for acronyms we want their definitions inlined at print time */ + acronym[title]:after { + font-size: small; + content: " (" attr(title) ")"; + font-style: italic; + } + /* and not have mozilla dotted underline */ + acronym { + border: none; + } + div.topnav, div.bottomnav, div.header, table.index { + display: none; + } + div.content { + margin: 0px; + padding: 0px; + } + html { + background: #FFF; + } +} + +.viewcode-back { + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; + margin: -1px -12px; + padding: 0 12px; +} + +div.imageBar { + font-size:x-small; + text-align: right; + padding: 10px; + margin-left: 15px; + margin-right: 10px; + margin-top: 10px; + border: 1px solid #000000; + background-color: #DDDDDD; +} + +div.tocBar { + + text-align: left; + padding: 10px; + margin-left: 15px; + margin-right: 10px; + margin-top: 10px; + border: 1px solid #000000; + background-color: #DDDDDD; +} + +div.content div.tocBar ul > li.toctree-l1 { + width: 400; + font-family: Arial, sans-serif; + color: #0C3762; + font-size: 1.2em; + font-weight: normal; + margin: 0; /** reset the margins back to 0**/ + padding: 2px 5px; + /**text-shadow: 1px 1px 0 white;**/ + background: #ddd; + font-size: 1.1em; +} + +p.caption { + font-size:x-small; + text-align: right; + background-color: #cdcdcd; +} + +div.sidebar2 { + width: 200px; + font-size: 0.75em; + line-height: 1.5em; + margin: 10px; + /* + padding-left: 10px; + padding-right: 10px; + */ +} + +div.content div.sidebar2 ul > li.toctree-l1 { + font-family: Arial, sans-serif; + color: #0C3762; + font-size: 1.2em; + font-weight: normal; + margin: 0; /** reset the margins back to 0**/ + padding: 2px 5px; + /**text-shadow: 1px 1px 0 white;**/ + background: #ddd; + font-size: 1.1em; +} + +div.content ul > li.toctree-l1 > ul { + margin: 0; +} + +div.sidebar2 h3 a { + color: #444; +} + +div.sidebar2 ul { + /** This is the selected sidebar text **/ + margin: 5px 10px; + /** + padding: 5px; + **/ + padding-left: 0px; + /**background-color: #cdcdcd;**/ +} + +div.sidebar2 li { + padding:3px; +} + +div.sidebar2 a { + color: #444; +} + +#bodycontent { + padding: 4px; +} diff --git a/docs/ociotheme/theme.conf b/docs/ociotheme/theme.conf new file mode 100644 index 0000000..d8118b4 --- /dev/null +++ b/docs/ociotheme/theme.conf @@ -0,0 +1,13 @@ +[theme] +inherit = basic +stylesheet = ocio.css +pygments_style = autumn + +[options] +full_logo = false +textcolor = #333333 +headingcolor = #0c3762 +linkcolor = #dc3c01 +visitedlinkcolor = #892601 +hoverlinkcolor = #ff4500 +rightsidebar = true 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 |
