Installation¶
The easy way¶
While prebuilt binaries are not yet available for all platforms, OCIO is available via several platform’s package managers.
Fedora and RHEL¶
In Fedora Core 15 and above, the following command will install OpenColorIO:
yum install OpenColorIO
Providing you are using the Fedora EPEL repository (see the FAQ for instructions), this same command will work for RedHat Enterprise Linux 6 and higher (including RHEL derivatives such as CentOS 6 and Scientific Linux 6)
OS X using Homebrew¶
You can use the Homebrew package manager to install OpenColorIO on OS X.
First install Homebrew as per the instructions on the Homebrew homepage (or see the Homebrew wiki for more detailed instructions)
Then simply run the following command to install:
brew install opencolorio
To build with the Python library use this command:
brew install opencolorio --with-python
Building from source¶
OS X and Linux¶
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 or newer (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
Windows Build¶
While build environments may vary between user, here is an example batch file for compiling on Windows as provided by @hodoulp:
@echo off
REM Grab the repo name, default is ocio_rw
set repo_name=ocio_rw
if not %1.==. set repo_name=%1
set CYGWIN=nodosfilewarning
set CMAKE_PATH=D:\OpenSource\cmake-3.9.3
set PYTHON_PATH=C:\Python27
set BOOST_ROOT=D:\SolidAngle\boost_1_55_0
set PATH=D:\Tools\cygwin64\bin;%CMAKE_PATH%\bin;%PYTHON_PATH%;%PATH%
call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
set OCIO_PATH=D:\OpenSource\%repo_name%
@doskey ne="D:\Tools\Notepad++\notepad++.exe" -nosession -multiInst $*
@doskey sub="D:\Tools\Sublime Text 3\subl.exe" --project %OCIO_PATH%_project.sublime-project
REM Decompose the directory change to avoid problems...
D:
IF NOT EXIST %OCIO_PATH% (
echo %OCIO_PATH% does not exist
exit /b
)
cd %OCIO_PATH%
set CMAKE_BUILD_TYPE=Release
echo *******
echo *********************************************
echo ******* Building %OCIO_PATH%
echo **
echo **
set are_you_sure = Y
set /P are_you_sure=Build in %CMAKE_BUILD_TYPE% ([Y]/N)?
if not %are_you_sure%==Y set CMAKE_BUILD_TYPE=Debug
set BUILD_PATH=_build_rls
if not %CMAKE_BUILD_TYPE%==Release set BUILD_PATH=_build_dbg
IF NOT EXIST %BUILD_PATH% ( mkdir %BUILD_PATH% )
cd %BUILD_PATH%
echo **
echo **
cmake -G "NMake Makefiles" ^
-DCMAKE_BUILD_TYPE=%CMAKE_BUILD_TYPE% ^
-DCMAKE_INSTALL_PREFIX=%OCIO_PATH%\_install ^
-DOCIO_BUILD_TESTS=ON ^
%OCIO_PATH%
set PATH=%OCIO_PATH%\%BUILD_PATH%\src\core;%PATH%
REM Find the current branch
set GITBRANCH=
for /f %%I in ('git.exe rev-parse --abbrev-ref HEAD 2^> NUL') do set GITBRANCH=%%I
if not "%GITBRANCH%" == "" prompt $C%GITBRANCH%$F $P$G
echo *******
echo *********************************************
echo boost = %BOOST_ROOT%
echo cmake = %CMAKE_PATH%
echo *******
if not "%GITBRANCH%" == "" echo branch = %GITBRANCH%
echo *******
echo Mode = %CMAKE_BUILD_TYPE%
echo path = %OCIO_PATH%\%BUILD_PATH%
echo compile = nmake all
echo test = nmake test
echo *********************************************
echo *******
Also look to the Appveyor config script at the root of repository for an example build sequence.
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 environment configuration¶
The quickest way to set the required Environment variables 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
OCIO
, which points to the configuration file you wish to
use. For prebuilt config files, see the
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¶
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 Quick environment configuration, 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 NUKE_PATH
(e.g
~/.nuke/menu.py
for a single user setup), add the following:
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!
Environment variables¶
-
OCIO
¶ This variable needs to point to the global OCIO config file, e.g
config.ocio
-
OCIO_LOGGING_LEVEL
¶ Configures OCIO’s internal logging level. Valid values are
none
,warning
,info
, ordebug
(or their respective numeric values0
,1
,2
, or3
can be used)Logging output is sent to STDERR output.
-
OCIO_ACTIVE_DISPLAYS
¶ Overrides the active_displays configuration value. Colon-separated list of displays, e.g
sRGB:P3
-
OCIO_ACTIVE_VIEWS
¶ Overrides the active_views configuration item. Colon-separated list of view names, e.g
internal:client:DI
-
DYLD_LIBRARY_PATH
¶ The
lib/
folder (containinglibOpenColorIO.dylib
) must be on theDYLD_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.
-
LD_LIBRARY_PATH
¶ Equivalent to the
DYLD_LIBRARY_PATH
on Linux
-
PYTHONPATH
¶ Python’s module search path. If you are using the PyOpenColorIO module, you must add
lib/python2.x
to this search path (e.gpython/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
DYLD_LIBRARY_PATH
orLD_LIBRARY_PATH
must be set correctly for the module to work.
-
NUKE_PATH
¶ Nuke’s customization search path, where it will look for plugins, gizmos, init.py and menu.py scripts and other customizations.
This should point to both
lib/nuke6.2/
(or whatever version the plugins are built against), andshare/nuke/