/docs/userguide/tool_overview.rst

  1..
  2  SPDX-License-Identifier: CC-BY-4.0
  3  Copyright Contributors to the OpenColorIO Project.
  4
  5.. _userguide-tooloverview:
  6
  7Tool overview
  8=============
  9
 10OCIO is comprised of many parts. At the lowest level there is the C++ API.
 11This API can be used in applications and plugins
 12
 13Note that all these plugins use the same config file to define color spaces,
 14roles and so on. For information on setting up configurations, see 
 15:ref:`configurations`
 16
 17The API
 18*******
 19
 20Most users will never directly interact with the C++ API. However the API is
 21used by all the supplied applications (e.g :ref:`overview-ocio2icc`) and plugins
 22(e.g the :ref:`overview-nukeplugins`)
 23
 24To get started with the API, see the :ref:`developer-guide`
 25
 26.. _overview-ociocheck:
 27
 28ociocheck
 29*********
 30
 31This is a command line tool which shows an overview of an OCIO config
 32file, and check for obvious errors
 33
 34For example, the following shows the output of a config with a typo -
 35the colorspace used for ``compositing_log`` is not incorrect::
 36
 37    $ ociocheck --iconfig example.ocio
 38
 39    OpenColorIO Library Version: 0.8.3
 40    OpenColorIO Library VersionHex: 525056
 41    Loading example.ocio
 42
 43    ** General **
 44    Search Path: luts
 45    Working Dir: /tmp
 46
 47    Default Display: sRGB
 48    Default View: Film
 49
 50    ** Roles **
 51    ncf (default)
 52    lnf (scene_linear)
 53    NOT DEFINED (compositing_log)
 54
 55    ** ColorSpaces **
 56    lnf
 57    lgf
 58    ncf
 59    srgb8 -- output only
 60
 61    ERROR: Config failed sanitycheck. The role 'compositing_log' refers to a colorspace, 'lgff', which is not defined.
 62
 63    Tests complete.
 64
 65It cannot verify the defined color transforms are "correct", only that
 66the config file can be loaded by OCIO without error. Some of the
 67problems it will detect are:
 68
 69* Duplicate colorspace names
 70* References to undefined colorspaces
 71* Required roles being undefined
 72* At least one display device is defined
 73
 74
 75As with all the OCIO command line tools, you can use the `--help` argument to
 76read a description and see the other arguments accepted::
 77
 78    $ ociocheck --help
 79    ociocheck -- validate an OpenColorIO configuration
 80
 81    usage:  ociocheck [options]
 82
 83        --help        Print help message
 84        --iconfig %s  Input .ocio configuration file (default: $OCIO)
 85        --oconfig %s  Output .ocio file
 86
 87
 88.. _overview-ociobakelut:
 89
 90ociobakelut
 91***********
 92
 93A command line tool which bakes a color transform into various color
 94lookup file formats ("a LUT")
 95
 96This is intended for applications that have not directly integrated
 97OCIO, but can load LUT files
 98
 99If we want to create a ``lnf`` to ``srgb8`` viewer LUT for Houdini's
100MPlay::
101
102    $ ociobakelut --inputspace scene_linear --shaperspace lg10 --outputspace srgb8 --format houdini houdini__lnf_to_lg10_to_srgb8.lut
103
104The ``--inputspace`` and ``-outputspace`` options specify the
105colorspace of the input image, and the displayed image.
106
107Since a 3D LUT can only practically operate on 0-1 (e.g a Log image),
108the ``--shaperspace`` option is specified. This uses the Houdini LUT's
1091D "pretransform" LUT to do "lnf" to "lg10", then the 3D LUT part to
110go from "lg10" to "srgb8" (basically creating a single file containing
111a 1D linear-to-log LUT, and a 3D log-to-sRGB LUT)
112
113To make a log to sRGB LUT for Flame, the usage is similar, except the
114shaperspace option is omitted, as the input colorspace does not have
115values outside 0.0-1.0 (being a Log space)::
116
117    $ ociobakelut --inputspace lg10 --outputspace srgb8 --format flame flame__lg10_to_srgb.3dl
118
119See the :ref:`faq-supportedlut` section for a list of formats that
120support baking
121
122.. TODO: For more information on baking LUT's, see :ref:`userguide-bakelut`
123
124
125.. _overview-ocio2icc:
126
127ocio2icc
128********
129
130A command line tool to generate an ICC "proofing" profile from a color space
131transform, which can be used in applications such as Photoshop.
132
133A common workflow is for matte-painters to work on sRGB files in Photoshop. An
134ICC profile is used to view the work with the same film emulation transform as
135used in other departments.
136
137.. TODO: Link to more elaborate description
138
139
140.. _overview-ocioconvert:
141
142ocioconvert
143***********
144
145Loads an image, applies a color transform, and saves it to a new file.
146
147OpenImageIO is used to open and save the file, so a wide range of formats are
148supported.
149
150.. TODO: Link to more elaborate description
151
152
153.. _overview-ociodisplay:
154
155ociodisplay
156***********
157
158A basic image viewer. Uses OpenImageIO to load images, and displays them using
159OCIO and typical viewer controls (scene-linear exposure control and a
160post-display gamma control)
161
162May be useful to users to quickly check colorspace configuration, but
163primarily a demonstration of the OCIO API
164
165.. TODO: Link to more elaborate description
166
167
168.. _overview-nukeplugins:
169
170Nuke plugins
171************
172
173A set of OCIO nodes for The Foundry's Nuke, including:
174
175* OCIOColorSpace, transforms between two color spaces (similar to the built-in
176  "ColorSpace" node, but the colorspaces are described in the OCIO config file)
177
178* OCIODisplay to be used as viewer processes
179
180* OCIOFileTransform loads a transform from a file (e.g a 1D or 3D LUT), and
181  applies it
182
183* OCIOCDLTransform applies CDL-compliant grades, and includes utilities to
184  create/load ASC CDL files
185
186.. TODO - Link to more elaborate description