User Manual

ZEISS eXtended Data OFX plug-in for Blackmagic Design DaVinci Resolve

OFX plug-in Version Beta 0.6c (171011)

This manual describes how to use the ZEISS eXtended Data OFX plug-in in BlackgmagicDesign’s DaVinci Resolve. If you want to

learn how to use DaVinci Resolve in general visit the official homepage.

Table of contents Introduction ................................................................................................................................................................2

System Requirements ..................................................................................................................................................2

Installation ..................................................................................................................................................................2

Required Input Data ....................................................................................................................................................2

Important Settings ......................................................................................................................................................3

Using the Plug-in .........................................................................................................................................................5

The GUI of the Plug-in ...............................................................................................................................................10

The Correction Radius ...............................................................................................................................................12

The Output of the Plug-in .........................................................................................................................................13

Trouble Shooting ......................................................................................................................................................14

Introduction The ZEISS eXtended Data OpenFX (OFX) plug-in is an OFX plug-in for BlackmagicDesign’s DaVinci Resolve. The plug-

in provides the potential to remove shading (often termed vignetting elsewhere) and distortion digitally from videos

made with ZEISS’ CP.3 lenses supporting ZEISS eXtended Data.

It is important to note that the degree of shading and distortion introduced by these lenses is very small because all

CP.3 lenses are optically well corrected. In particular, there is no optical difference between the CP.3 lenses with and

without Zeiss eXtended Data support. Thus, it is not meaningful to apply the plug-in by default or indiscriminately.

However, for certain scenes and, especially, when combining footage with visual effects it can be desired to remove

optical aberrations beyond the level provided by the lenses themselves.

There are other effects and plug-ins, respectively, which allow to modify shading and distortion digitally.

Theoretically, you can remove shading and distortion with them for every frame if you put enough time and work

into it. However, the ZEISS plug-in provides a much more convenient way.

System Requirements 1) System with (a) graphic card(s) that support(s) OpenCL

2) Operating Systems: Windows, Mac

3) BlackmagicDesign DaVinci Resolve 12.5 (64 bit) or later installed

Installation Run the installer and follow the instructions. The installer can be requested here.

Verification of the Installation To verify whether the plug-in has been installed successfully

open DaVinci Resolve, go to the “Color” sheet, click on the

“OpenFX” button to open the effects library, and scroll down

to the very end. If the “ZEISS Lens Correction” effect is

available the installation has been successful. If the effect does

not show up check the section Trouble Shooting.

Required Input Data To make full use of the plug-in, the user must provide the following input data

1) Video files recorded with lenses supporting ZEISS eXtended Data (e.g. ZEISS CP.3 XD)

o Information about the required setup to record ZEISS eXtended Data can be found in the corresponding guide

which is available here.

2) The corresponding ZEISS Lens Correction files (*.zlcf, Version 2 or later)

o ZEISS Lens Correction files can be obtained using the latest version of Silverstack by Pomfort. Please see the

guide (here) for more information.

3) A FinalCut Pro XML file (*.fcpxml) which represents the current timeline on the “Edit” sheet in DaVinci Resolve

o You find more information on how to obtain these files below.

Important Settings The current version of the plug-in requires certain project settings to calculate and apply the corrections correctly.

Thus, it is recommended to employ these settings right at the beginning if you start a new project. Existing projects

should be changed before you apply the plug-in to a clip.

Color Space and Color Depth The plug-in expects input whose color information is given in the color space “Rec.709 Gamma 2.4”. If the color

information of your input is defined in another color space and you want to apply the shading correction it is

important that you transform the color information into the expected color space before you apply the correction.

DaVinci Resolve offers several possibilities to work on the color space of footage; see its reference manual for more

information.

The plug-in supports input with components RGBA and a color depth of 32bit (float).

Input Scaling At the moment the plug-in does not support the automatic correction of scaled input. Thus, the input scaling should be turned off in the project settings. To this end

Go to “File” “Project Settings” ”Image Scaling” and choose “Center crop with no resizing” in the drop down menu “Mismatch resolution files”. Save the changes.

The plug-in can be applied to scaled input, however, the user has to choose the “Manual Input” mode of the plug-in and provide the correction radius manually. Details on the correction radius can be found in the section The Correction Radius. Furthermore, note that the current version of the plug-in does not take translation of the crop window into account. I.e., if you decenter the crop the correction will not be applied correctly.

Timeline Resolution The resolution of the timeline must be smaller than or equal to the resolution of the included video files and the pixel

aspect ratio should be square. In order to set the resolution manually

o Go to “File” “Project Settings” “Master Settings” and choose the desired resolution using the “Timeline resolution” drop down menu. Save the changes.

Using the Plug-in When you have sufficient input data at your disposal, you can employ the plug-in to correct a clip.

Exemplarily, it is shown how to use the plug-in in order to apply corrections to a trimmed clip of a timeline. Before

you go on check whether the project settings are appropriate. See the section Important Settings for more

information.

It is assumed that the editing of the timeline is temporarily done. Thereby, it does not matter whether the editing has

been done in DaVinci Resolve or whether the timeline has been imported from another editing software.

Exporting the FinalCut Pro XML file (fcpxml) The first step towards applying the plug-in successfully is to export the fcpxml representing the timeline. This is

required at this point because here we apply the plug-in to a clip trimmed at the front and cannot fall back to the

“Manual Input” mode.

The plug-in needs an fcpxml file (Version 1.5) which represents the current timeline in order to match and check

metadata from the ZEISS Lens Correction files (zlcf). To export an fcpxml representing the current timeline

Go to the “Edit” sheet

Choose “File” “Export AAF, XML” and choose save it as type “FCPXML 1.5 Files (*.fcpxml)”.

It is important that the fcpxml file is up-to-date because the plug-in will not apply corrections if it detects differences

between the metadata it receives from the fcpxml file and the OFX interface.

The OFX interface does not convey information about the editing which has been applied to a clip in the timeline.

However, the plug-in needs to know whether and how a clip has been cut or trimmed, respectively, in order to apply

the corrections correctly because these corrections vary per frame. And this is the point where fcpxml files enter the

scene. fcpxml files contain most of the editing information which constitute the timeline. With this data the plug-in

can apply the corrections automatically correctly to all frames.

At the moment there are two ways to link exported fcpxml files to the plug-in

1. The first way requires that all ZEISS Lens Correction Files (.zlcf) are stored in one directory. In this case, you

can simply export the fcpxml file to that directory; the plug-in searches there by default. It is important that

there is exactly one fcpxml file in that directory because the plug-in cannot know which file is the right one if

there are more than one.

2. The second way is appropriate if you store the ZEISS Lens Correction Files (.zlcf) in several directories (e.g.,

together with the corresponding video file). In this case you have to link the exported fcpxml file explicitly

using the “Choose fcpxml path…” button. Two things are important to note

a. The chosen fcpxml file will be used for ALL clips in that project! You only have to link it once on one

clip!

b. The path to the fcpxml is only valid for the current session! I.e., if you close DaVinci or destroy the

plug-in instance in another way, the fcpxml file must be re-linked! However, you have to re-link it

only once on one clip – it will be used for all clips!

You can get the default behavior again if you cancel the file dialog. Thus, the plug-in will look in the directory where

the zlcf file of the currently highlighted clip is stored.

Since DaVinci resolve does not allow to update the parameter sets assigned to clips without an explicit user

interaction it might be necessary to update the GUI manually after an fcpxml file has been chosen using the “Choose

fcpxml Path…” button or after the fcpxml file has been re-exported after a change in the timeline.

If there is only one clip in the timeline this can be done by clicking the “Manual Input” switch two times (on and off

again). If there are several clips in the timeline you can either use the method described before or you can simply

click on another clip which is using the plug-in.

Applying the Plug-in When the fcpxml file has been exported switch to the “Color” sheet. The first step here is to add the plug-in to a

node of the node structure of the clip by drag and drop. It is important to keep in mind that other effects might

affect the data of clips such that it is not meaningful to apply lens corrections afterwards. Thus, it is recommended to

apply the plug-in to the first node (the leftmost) unless you have to employ a color space transformation in order to

match the input requirements of the plug-in. Other effects can be applied to nodes that follow.

Furthermore, the plug-in expects one input and one output stream. Consequently, do not use the plug-in with more

input or output streams, respectively, in the node editor.

Next, you activate the plug-in using the “ACTIVATE” button. This is required to generate a unique identifier for the

plug-in instance.

Now, the metadata needed for the corrections must be provided which is why the next step is to load the zlcf file. In

order to do that you need to know the filename of the video file. If you are not sure which file you are working on

right now right click the clip in the thumbnail timeline and choose “View Clip Details”.

If all zlcf files required in the project are stored in one directory you can directly choose the zlcf file using the

“Choose zlcf File” button. If, on the other hand, the zlcf files are not stored in a single directory the fcpxml file has to

be linked explicitly using the “Choose fcpxml file…” button. It is good practice to choose the fcpxml file before you

choose the zlcf file belonging to the clip. Important: see the section Exporting the FinalCut Pro XML file (fcpxml)

before you link an fcpxml file to your project.

Either way, assumed that the plug-in has access to an appropriate fcpxml file and that the chosen zlcf file is parsed

successfully the plug-in should render with corrections. In order to check if it is rendering you can simply switch the

shading correction on and off using the “Shading Correction” switch and look at the “Scopes” (the “Parade” mode is

good to this end) simultaneously. When the plug-in renders you observe a deformation of the structures on switch.

If you cannot oberserve deformations visit the log file; see the section The Output of the Plug-in for more

information. In particular, check whether the render algorithm complaints about missing zlcf data which means that

the file has not been parsed successfully.

If the plug-in does render you should, in any case, check the “Sensor Width / Height”, the “Correction Radius”, and

the “Correction Startframe” now. Since we applied the plug-in to a clip trimmed at the beginning the value in the

“Correction Startframe” field should be > 0.

The values of the “Correction Radius” and the “Sensor Width / Height” should be as expected.

If the “Correction Startframe” and the “Correction Radius” are ok you are done.

If “Sensor Width / Height” are ok but the radius is wrong check the

values of the fields “Sensor Pixel W / H” and “Timeline Pixel W / H”.

If the values are not as expected you can use the drop down menus

to set “Sensor Width / Height” and “Sensor Pixel W / H”. See the

section Camera Properties for more information.

If you cannot find the camera or recording format, respectively, you

used (not all cameras are available in the datbase at the moment) you

can fall back to the “Manual Input” mode which allows to set the

“Correction Radius” manually. See the sections File I/O and The

Correction Radius for more information.

The “Correction Startframe” calculated before is employed in the

“Manual Input” mode, too. Thus, you are done as soon as you have

entered the “Correction Radius”.

It is, furthermore, nice to know that you can make the plug-in render correctly with corrections without an fcpxml

file if the clip has not been trimmed at the front. To do this, activate the “Manual Input” mode after you have loaded

the zlcf file and type in an appropriate correction radius into the input field “Correction Radius” and that is it.

Note, however, that this procedure does ONLY work correctly for clips that have not been trimmed at the front!

The GUI of the Plug-in This section gives a short overview of the GUI elements of the plug-in.

File I/O The “File I/O” menu bundles all GUI elements which

are related to files and their usage. The “Choose zlcf

File…” button is used to link the zlcf file which belongs

to the video file which is represented by the current

clip. Likewise, the “Choose fcpxml Path…” can be

used to link the fcpxml file which represents the

current timeline if the fcpxml file is not stored at the

default location.

The “Manual Input” switch determines whether the

data from the fcpxml file should be used to calculate

the “Correction Startframe” and whether the

“Correction Radius” should be calculated automatically.

Plug-in Settings By clicking on the “Shading Correction” or “Distortion Correction”

switch, respectively, you can activate or deactivate, respectively, the

shading and distortion correction for the current clip.

If the “Auto Zoom” is turned on the plug-in determines the optimal

zoom factor needed to compensate for the change of the frame size

due to the distortion correction. By deactivating the “Auto Zoom”

switch you can set the zoom factor manually using the slider “Zoom

(Distortion)”.

Clip & Timeline Properties When the “Manual Input” mode is turned off this menu

displays two parameters. First, the resolution of the render

window in terms of the number of pixels along the width and

the height of that window. Since the resolution of the render

window is determined by timeline settings the parameter is

called “Timeline Pixel W / H”. Second, the “Correction

Startframe” which determines the offset (in number of frames) between the frames in the zlcf file and the frames of

the clip in the timeline. The plug-in needs to know the offset because the frames from the OFX interface always start

at zero – no matter whether the clip has been trimmed or not. In order to calculate the offset the plug-in uses the

data from the fcpxml file. If the clip has not been trimmed at the front the value in the field should be zero.

If the “Manual Input” mode is switched on the “Correction Startframe” input field turns active and you can type in

the offset manually.

Camera Properties All parameters related the sub-area of the sensor covered by the recording format are bundled under this menu.

The fields “Sensor Width” and “Sensor Height”,

respectively, show the (full) width and (full) height,

respectively, of the sub-area of the sensor covered by

the chosen recording format in mm. Note that the

plug-in tries to get the numbers from the header of

the zlcf file. If the data is not available the default

values are used (full frame). The values can also be set

using the drop down menus; see below for more

information.

It is important to note that the two fields affect the

“Correction Radius” only if an fcpxml file has been

parsed successfully. The “Correction Radius” must be

provided manually if no fcpxml file has been parsed

successfully! Consequently, the input field “Correction Radius” turns active when the “Manual Input” is switched on.

The fields “Sensor Pixel W / H” show the number of pixels along the width and the height, respectively, of the sub-

area of the sensor covered by the recording format. The plug-in tries to read these values from the header of the zlcf

file, too. If they are not available from there the plug-in tries to get them from the fcpxml file which, of course, is

only possible if an fcpxml file has been parsed successfully. Again, the values can be set through the drop down

menus; see below for more information.

The field “Correction Radius” contains the radius (in mm) which is used to normalize the corrections appropriately. If

an fcpxml file has been parsed successfully the radius is calculated from the values of the fields “Clip & Timeline

Properties”→“Timeline Pixel”, “Sensor Width / Height”, and “Sensor Pixel W / H”. Under such circumstances every

change to any of these values affects the value of the radius!

If the “Manual Input” mode is turned on the radius must be calculated and typed in manually. See the section The

Correction Radius for more information.

The plug-in possesses three drop down menus. The first contains camera manufacturers, the second the associated

camera models, and the third, in its turn, the associated recording formats.

When a zlcf file is parsed the plug-in tries to match the data from the header with information from a database. If

the plug-in can identify the camera and the recording format with the data from the header it tells the user about it

by setting the three drop down menus accordingly.

On the other hand, the drop down menus can be used to choose camera and recording format manually. The

underlying data is then used to set the values of the fields “Sensor Width / Height” and “Sensor Pixel W / H”. This is

helpful when the header of the zlcf file does not contain the required metadata or the matching fails for another

reason. At the moment only cameras made by ARRI, RED, or BlackMagic are supported.

Note that you overwrite the values of the fields “Sensor Width / Height” and “Sensor Pixel W / H” when you choose

a recording format.

The Correction Radius The correction radius 𝑅𝑐𝑜𝑟𝑟 can be calculated from the width 𝑊𝑟𝑒𝑐 and the height 𝐻𝑟𝑒𝑐 which define the sub-area of

the sensor covered by the recording format 𝐴 = 𝑊𝑟𝑒𝑐 𝐻𝑟𝑒𝑐 [mm²], the number of pixels along the width 𝑝𝑥𝑙𝑤,𝑟𝑒𝑐

and the height 𝑝𝑥𝑙𝑤,𝑟𝑒𝑐 of that area, and the number of pixels along the width 𝑝𝑥𝑙𝑤,𝑇𝐿 and the height 𝑝𝑥𝑙ℎ,𝑇𝐿 of

the employed timeline / render window:

𝑊𝑢𝑠𝑒𝑑 =1

2𝑊𝑟𝑒𝑐

𝑝𝑥𝑙𝑤,𝑇𝐿

𝑝𝑥𝑙𝑤,𝑟𝑒𝑐

𝐻𝑢𝑠𝑒𝑑 =1

2𝐻𝑟𝑒𝑐

𝑝𝑥𝑙ℎ,𝑇𝐿

𝑝𝑥𝑙ℎ,𝑟𝑒𝑐

𝑅𝑐𝑜𝑟𝑟 = √𝑊𝑢𝑠𝑒𝑑2 + 𝐻𝑢𝑠𝑒𝑑

2

It is important to note that it is assumed that the project setting “Image ScalingInput ScalingMismatch

Resolution Files” is set to “Center crop with no resizing” and that the resolution of the timeline is higher than or

equal to the resolution of the included clips. I.e., 𝑅𝑐𝑜𝑟𝑟 is always smaller than or equal to the (maximal) image circle

of the sensor.

If you use the “Manual Input” mode and provide the “Correction Radius” manually, you must calculated the radius as

given above. I.e., you cannot in general type in the sensor radius of the camera or the radius of the sub-area of the

sensor covered by the recording format. You must provide the radius of the sub-sub-area which is exposed by the

resolution of the timeline / render window:

If the resolution of the timeline is equal to the resolution of the video file then you can simply take the radius of the

sub-area of the sensor covered by the recording format.

The Output of the Plug-in In the current state the plug-in cannot give feedback directly through menus and messages in DaVinci Resolve.

Instead, it writes certain actions and messages to a log file. The log file is an ASCII file and can be opened with every

text editor. However, it is convenient to use an editor which allows to reload an opened file. On Mac you can simply

follow the output using the command “tail –f FULL_FILE_NAME”. The log file can be found here:

Windows: C:\TEMP\lensCorrect\lensCorrectionOFX.txt

Mac: \tmp\lensCorrectionOFX.txt

The following output statements are important for users because they let them know why the plug-in cannot render,

cannot apply the corrections, which files cannot be parsed, which files cannot be found, etc.

In order to distinguish between different plug-in instances – and, thus, different clips - every plug-in instance

possesses a universally unique identifier (uuid). Messages which can appear without explicit actions by the user

contain the uuid of the clip so that you can localize their cause.

1) RENDER ACTION :: XML data NOK and !(MANUAL MODUS) => NO RENDERING BY PLUGIN! (uuid)

The plug-in could either not parse the .fcpxml file or not match the metadata of the clip with this uuid (i.e.,

the metadata from the chosen .zlcf file) with the metadata from .fcpxml file.

2) RENDER ACTION :: no uuid => NO RENDERING BY PLUGIN! (uuid)

The currently highlighted parameter set / clip has not been activated yet.

3) RENDER ACTION :: no lensCorrData from .zlcf => NO RENDERING BY PLUGIN! (uuid)

No .zlcf file has been chosen or parsed successfully for the parameter set / clip with that uuid.

4) RENDER ACTION :: Radius of used sensor area is either < 8 mm or > 21.63 mm => NO RENDERING BY

PLUGIN! (uuid)

The plug-in does only render with corrections if the correction radius of a clip is within the given bounds.

5) DURATION MISMATCH : Clip could not be matched unambigously!

This messages shows up when the plug-in cannot match the current clip with the metadata from the .fcpxml

file. Either the plug-in could not match the name of the video file or the duration of the clip. The former can

happen if the wrong .zlcf file is picked, the latter can happen when the .fcpxml is not up to date, e.g., after

editing the timeline.

6) FPS MISMATCH : Timeline FPS of HOST and XML differ!

This message occurs when the frames per seconds (fps) of the current timeline (in Resolve) differ from the fps

of the timeline given in the .fcpxml file.

7) RENDER ACTION :: Input Image Component Type is not RGBA!

The input does not have the required component type and, thus, the plugin cannot render. Convert it to a

format with RGBA components.

8) RENDER ACTION :: Input Image Pixel Depth is not float!

The input does not have the required pixel depth and, thus, the plugin cannot render.

Trouble Shooting The plug-in is not recognized by DaVinci Resolve

Windows 1) Go to the directory where DaVinci Resolve is installed. Check if the following dlls are there

2) Check whether the directory “C:\Program Files\Common Files\OFX\Plug-ins” exists and if the

“lensCorrect.ofx.bundle” is placed there.

Mac 1) Check if the plug-in bundle is placed in /Library/OFX

The plug-in does not render / produces a black render window

Check the output of the plug-in written to the corresponding log file; see the section The Output for more

information.

The plug-in does not render by default since it cannot produce meaningful results under all circumstances. Consequently, the

following requirements have to be met

o The resolution of the output window must be larger than 1200 pixels vertically and 800 pixels horizontally

(thus, it might not render when proxies are used!)

o The “Correction Radius” must be given (either by the user (“Manual Input”) or by data from the fcpxml and the

drop down menus) AND it must hold: 8 mm <= Radius <= 21.64 mm

o The ZEISS Lens Correction File (zlcf) belonging to the currently highlighted clip (use the “Choose file…” button )

must be read successfully

o The corresponding XML File must be parsed AND matched successfully or the plug-in must be in “Manual

Input” modus (the fcpxml file is not needed then)

Carl Zeiss AG

Camera Lenses

73446 Oberkochen

Germany

www.zeiss.com/cine