Metadata
From VFXPedia
Contents |
So-called metadata is a set of variables that are attached to an image and are passed alongside pixel data through the comp. It is either loaded with an image from disk (the camera might have stored metadata inside the files), created or modified in your comp by certain tools and saved to disk in Saver tools (not every file format supports storing metadata though).
Viewing Metadata
To check what metadata is present in an image at a specific point inside your comp, you need to enable the metadata subview using the SubV button that is present below each image viewer. An overlay will list all the metadata (if any) that is present in the image in key/value pairs. Values can be numbers or strings but also tables when variables are nested.
A file's metadata is also displayed by the file requester when selecting a clip for a Loader tool.
Modifying Metadata using Tools
First of all, metadata gets loaded with certain image formats (exr, dpx, ...) by the Loader. There are three main tools that allow you to add, delete or modify metadata and they are all found in the Metadata section of the Tools menu:
CopyMetadata
CopyMetadata allows you to merge the metadata of your background image with that of a foreground image. Its only control allows you to choose whether you want to merge, replace or clear the variables. The latter option doesn't require a foreground image.
SetMetadata
SetMetadata allows you to add a single key/value pair to your image's metadata by entering a Field Name (key) and Field Value. You can also nest variables by using the dot notation for the field name, e.g. Studio.Artist = xxx, Studio.Department = xxx.
Since Fusion's metadata subview currently displays only one level of key/value pairs, such nested variables will be printed as a table within a single line: Studio = {Artist = xxx, Department = xxx} This is unfortunate if you nest many variables so if you're not in danger of namespace clashes and need to monitor metadata constantly, you might consider calling your variables Studio_Artist and Studio_Department instead.
Field Value can also contain tables. You need to use LUA's syntax here: { 1, 2, 3 }. If you want to add a string, you need to add double quotes so it's recognized as such: { "aaa", "bbb" }
SetTimeCode
This tool was added in version 6.2 and allows you to add a timecode stamp to your images.
Preserving Metadata
The saver will write all metadata that is present in the image as long as it is supported by the output file's type. It is often paramount that the input file's metadata (especially its TimeCode attribute) is preserved throughout the production pipeline. Fusion's tools will pass on all the metadata that is present in the input image except for a few special cases: nodes that have more than one input (Merge nodes for example) will only pass on metadata from their main input. This means that whenever you merge an image onto a new background you will lose its metadata since only the background image's metadata gets passed on. Use the CopyMetadata fuse to restore metadata if it got deleted at some point in your comp. Another solution might be to arrange the order of layers in your comp so that the background image is the one that contains the metadata that should be written to disk.
Metadata and Scripts
Metadata can also be accessed by expressions and InTool-Scripts. The metadata is part of the image object that is can be accessed by image inputs and outputs. For example, this expressions on a Text+ tool's StyledText field will print the time code of the frame that is currently loaded by "Loader1":
Text("TimeCode:"..Loader1.Output.Metadata.TimeCode)
A Gamut tool can set the Source Space automatically from the input using this expression set to the Source Space input.
self.Input.Metadata.ColorSpace
You can also access metadata inside a frame render script (InTool-Script). The following example can even modify metadata and is a useful alternative to using several SetMetadata fuses in a row (taken from the scripting manual):
img = Input md = img.Metadata -- Read metadata print("Image was loaded from ".. md.Filename) -- Add/change metadata md.Project = "Filmy Stuff" md.Creator = "Studiosity Inc" md.CreationTime = os.date() -- Duplicate the image, and write the whole table back at once newimg = img:Copy() img:SetData("Metadata", md) Input = newimg
These scripting commands will not work on the console since they reference a tool's image data. These objects are only available when a comp is being rendered, hence the need for InTool-scripts.
-- won't work
==Loader1.Output.Metadata.Filename
Metadata and Fuses
This section describes what you need to know about metadata when writing Fuses.
The metadata is stored in a member variable of every Image object called .Metadata (it's nil if no metadata is available) that can both be read and written. Using the LUA functions eyeon.writestring() and eyeon.readstring(), you can place almost anything into the metadata that gets passed around.
To copy the metadata of your input image, it is recommended to use the IMG_Like attribute when creating your output image, even if you then define a different size or channel configuration. This will make sure the metadata of the input image is preserved.
All the metadata tools described above are Fuses so you can easily learn from their source code and adapt them for your own use cases. The SparseColor Fuse is another example of how to read and write metadata.
Supported File Types
Not every file type can store metadata. Traditionally, only cineon (.cin) and dpx files were used in conjunction with metadata and they can only store a pre-defined set of attributes. OpenEXR (.exr) files can be used to store any metadata you like and so can Fusion's .raw files that are used for disk caches. PNG files are able to store color space and gamut metadata. Other popular file formats like Tiff or Jpeg don't support metadata (at least Fusion can't save it to these file types).
List of known Metadata
This is a list of some of the metadata attributes that you might encounter, either because they come with certain image files or because they allow you to do nice things with them inside Fusion.
| Metadata field name | Source | Description |
|---|---|---|
| Filename | Loader | This metadata is added by every Loader and contains the full path, frame number and extension of the currently loaded file. |
| FrameFilename | Loader | If the Loader points to an IFL file (text files, where each line contains the name of a file to be loaded), this variable will be added and contains the frame's actual filename while the Filename field will contain the (unchanging) path to the IFL file. |
| OriginalFilename | dpx files | Contains the "Filename" metadata of the source image that was subsequently saved as the dpx file you're currently viewing. |
| Project | dpx files | Contains the path and file name of the comp that rendered the current dpx file. |
| TimeCode | dpx files, mov (and others?) | Contains the current frame's time code. For DPX this is usually generated by the camera and subsequently carried along through the pipeline unchanged. For Quicktime movies it depends on the mov's timecode track. You can use the SetTimeCode Fuse to set this manually. Format is HH:MM:SS:FF |
| FrameRate | mov | Contains the Quicktime movie's frame rate. SetTimeCode will also set this parameter but it may not be written to the output file. |
| CreationTime | dpx files (and others?) | Contains the real world's time when this frame was recorded by the camera. |
| Creator UserBits FramePosition Offset Center OriginalSize FilmFormat FrameID SlateInfo | dpx files | various attributes you may encounter in dpx files |
| InputDevice InputSerial | dpx files and Saver tool | Fusion writes this to every dpx file. |
| screenWindowWidth screenWindowCenter | exr files | These properties are part of the exr file standard and contain the position of the image's DoD |
| Gamma | dpx & png files | The image's gamma. Written to PNG files by the Saver tool but encountered in logarithmic dpx files as well where it might denote the conversion gamma (unconfirmed). |
| ColorSpace | Gamut tool | Contains the name of the output color space that has been selected in Fusion's Gamut tool. |
| WhitePointX WhitePointY RedChromaX RedChromaY GreenChromaX GreenChromaY BlueChromaX BlueChromaY | Gamut tool | These variables contain the coordinates of white point and color primaries as converted by the Gamut tool since the previously mentioned ColorSpace variable is just a user-friendly label (e.g. "sRGB") that contains little information for applications that deal with color science. These parameters can't be written to DPX files. Use OpenEXR instead. PNG files are also able to save this information. |
| Stereo.Method | Combiner tool | If Add Metadata is enabled in the Combiner tool, Fusion will attach this attribute to the output image to denote the stacking method of the current image. Valid values are "hstack" and "vstack" for horizontal and vertical stacking. |
| Stereo.Swap | manual | This property, if set to "true", will override the viewer's stereo display option. It's useful if you need to temporarily swap eyes somewhere inside your comp but you don't want to toggle the "swap eyes" option in the viewer by hand. |
| Stereo.Offset | manual | This "hidden" property needs to be set to an X and Y offset in pixels (e.g. {10, 0}) and will shift left and right eye when the viewer's stereo mode is enabled. It's very useful to add this property if your footage was shot with parallel cameras where zero disparity would occur on the horizon and everything would end up sticking out of the screen. Often, a preliminary per-shot depth grading value is supplied with the source footage to push the image back. Instead of actually transforming your left and right eye images and reverting this before the Saver, use Stereo.Offset like a viewer LUT: you'll be able to work on your raw footage while previewing the desired depth grade in the viewers. |
| nuke/node_hash | Nuke (exr files) | This is a checksum of the script that generated the image and is written to EXR files by Nuke. |
