CamMark

Header image

Usage

CamMark comes as two command line programs, one for the actual camcorder simulation, and one for the calibration of certain distortions from a given pair of reference/copy videos or images. However, please note that CamMark comes with a well-defined set of presets, which obviates the need to create your own calibrations unless you want to explicitly simulate a certain existing setup.

The graphical user interface, which was part of the original first version of CamMark, was removed in version 1.1 and will be replaced soon by a CamMark web service, offering a web-based interface to an entirely server-side processing.

Overview

The CamMark simulation tool reads input in form of video files or a set of single frames, simulates typical artifacts from cam-cording to it such as spatial and temporal distortions, and writes the result in form of a video or set single frames.

Command line syntax

CamMark[.exe] scenario-file source-file [output-file]

scenario-file: XML file specifying the simulation scenario, that is, all distortions that are to be simulated.
See the configuration section for more details on the scenario file.
source-file: Unmodified, original source video file or a set of single frames.
output-file: Optional parameter. This specifies the name of the output file. Currently, the file extension has to be either .avi for outputting a video file, or .png for outputing PNG-compressed single frames.
If omitted, the output file name is generated as source-file-without-ext_sim.avi

Example call from within the CamMark root folder (input video must be provided):

Windows: bin\CamMark.exe scenarios\example_everything-specified.xml input.mp4

Linux: ./bin/CamMark scenarios/example_everything-specified.xml input.mp4

Supported input/output formats

The input can be specified as a relative or absolute path to an existing media file. CamMark can read any video format natively supported by ffmpeg. This includes a broad selection of codes and containers, and should cover all typically used formats.

Alternatively, a set of single frames can be specified, in any common image format (PNG, JPEG, BMP, TIFF, ...). CamMark will automatically detect a frame sequence if the file names contain a running index, starting at zero, with a fixed number of digits. There is no requirement on the number of digits other than being fixed, and the index can be in any part of the file name. However, auto-detection only works if the first frame of the sequence is specified as source file, and its running index has to be zero (so 0000 for a four-digits index).

Examples for automatically detected frame sequence file names:

frm-0000.png, frm-0001.png, frm-0002.png, ...
frm00.jpg, frm01.jpg, frm02.jpg, ...
000000.bmp, 000001.bmp, 000002.bmp, ...
000000-sample.tif, 000001-sample.tif, 000002-sample.tif, ...
frm-00000-mod.png, frm-00001-mod.png, frm-00002-mod.png, ...

As output, either a video file or a set of single frames can be generated. The parameter is the desired output file name, which can also contain a relative or an absolute path. CamMark will try to create any directories that do not exist before creating the output file.

If specifying a file name with .avi extension, an MPEG-4 compressed video is written into an AVI container. Note that there is currently no option to change the video codec, container, or encoding parameters.

To write a sequence of PNG-compressed single frames, specify a file name with .png extension. In this case, a running 6-digit index separated by an underscore is automatically prepended to the filename. /path/to/file/out-frms.png will thus create the frame sequence /path/to/file/000000_out-frms.png, /path/to/file/000001_out-frms.png and so on.

General configuration

The entire configuration of a CamMark simulation run is specified in a so-called scenario. The scenario is provided in form of an XML file, each simulated distortion having a separate XML tag. An XML scenario file, which is configuring all supported distortions as an example, is included in the distribution.

The general structure of the scenario XML file is as follows:

Basic XML scenario file structure.

All configuration data is contained within a <Scenario> tag. There are currently two distortion-independent tags (<CaptureTimespan> and <OverrideSourceFPS>), plus a seperate tag for each distortion to configure (<SpatialDistortion>, <TemporalDistortion>, <AutomaticGainControl>, <AutomaticWhiteBalance>, <ColorFilterArray>, and <Defocus>).

A distortion is only applied if the according tag is specified and its enabled attribute set to true. A detailed description of each of these tags is given further below. An example of a temporal distortion configuration can be seen here:

Example temporal configuration.

Using presets

Instead of specifying each distortion's configuration manually, presets can be used. A preset is nothing else than XML configuration data that is seperately stored and can be easily included by using the preset attritute in the distorion's configuration tag:

Using a preset in the temporal distortion configuration

The preset file can be specifed with an absolute or relative path. If the preset file my-temporal-preset.xml contains the following XML, the configuration is effectively the same as in the previous section's example:

CamMark already comes with a useful set of presets for each distortion, that can be used without having completely understand each distortions configuration.

It is also possible to specify a preset and further configuration tags at the same time. In this case, the directly specified tags have precedence over the tags from the preset. In other words, directly specified tags override tags that are specified in the preset. This way, you can use a preset but still adjust the scenario to your needs.

Using a preset and additional configuration tags.

The following sections describe each distortion's individual configuration.

Distortion-independent configuration

<CaptureTimespan start-time="float" end-time="float" /> (opt.)
<OverrideSourceFPS value="float" /> (opt.)

CaptureTimespan: If the tag is completely omitted, both start-time and end-time are set to zero.
start-time (opt.): A floating-point value specifying the capture start time in seconds (sec).
If this attribute is omitted or set to zero, the source video's start time is used.
end-time (opt.): A floating-point value specifying the capture end time in seconds (sec).
If this attribute is omitted or set to zero, the source video's end time is used.

OverrideSourceFPS: If the tag is completely omitted, the original source video frame rate is used.
value: A floating-point value specifying the source video's actual frame rate.
This is only needed if the source frame rate cannot be detected automatically or when using a sequence of single frames as input.

Spatial distortion configuration

If you do not want to configure spatial distortion yourself, you can find a description of the predefined presets here.

<SpatialDistortion enabled="boolean">
    <DisplayResolution width="int|string" height="int|string" aspect-ratio-mode="string" /> (opt.)
    <CameraResolution width="int|string" height="int|string" /> (opt.)
    <TransformationFile path="filename" background-insertion="boolean" /> (opt.)
    <SoftenBorders extend-border-px="int" fade-border-px="int" /> (opt.)
</SpatialDistortion>

DisplayResolution: If the tag is completely omitted, its width and height attribute are set to zero,
and the default aspect-ratio mode 'Letterbox' is used.
width/height (opt.): Integer values specifying the width/height of the simulated display's resolution.
If the width/height attribute is omitted or set to zero, the width/height is calculated based on the source video's width/height and the transform file's original display aspect-ratio.
If the string "source" is specified, the source video's width/height is used directly.
If the string "calib" is specified, and a transformation file is used, the original width/height of the monitor that was used to calibrate the transformation is used.
aspect-ratio-mode (opt.): Specifies the aspect-ratio mode of the simulated display/player. This is relevant if the source video's aspect-ratio differs from the simulated display resolution's aspect-ratio. Possible modes are: "Letterbox", "Crop", and "Resize". If the attribute is omitted, letterboxing is used.

CameraResolution: If the tag is completely omitted, its width and height attribute are set to zero.
width/height (opt.): Integer values specifying the width/height of the simulated camera's resolution.
If the width/height attribute is omitted or set to zero, the width/height is calculated based on the simulated display's width/height and the transform file's original camera aspect-ratio.
If the string "source" is specified, the source video's width/height is used directly.
If the string "calib" is specified, and a transformation file is used, the original width/height of the camera that was used to calibrate the transformation is used.

TransformationFile: The transformation file stores and describes all perspective as well as lens distortion. It can either contain just one transformation (static case), or a sequence of transformations describing a continously changing spatial distortion (movement case). Transformation files are generated using the CamMarkCalibration tool, but CamMark also provides a large set of transformation files already. If the tag is completely omitted, no transformation file is loaded/applied.
path: Mandatory attribute that specifies an absolute or a relative path to a transformation file.
The path can be either relative to the current path, or to the scenario file's path.
background-insertion (opt.): If background data exists for the chosen transformation file, specifies whether to insert the background into the simulated video or not. Not specifying this attribute disables insertion.

SoftenBorders: This tag controls softening of the borders after spatial transformation. This is a purely visual effect and simply makes a spatially transformed video blend more naturally with an inserted background. If the SoftenBorders tag is omitted, no softening is applied.
extend-border-px (opt.): The number of rows/columns by which a frame is extended. The extension is accomplished by blurring the prevously outmost pixels rows and colomns into new, extended rows/columns.
If the SoftenBorders tag is specified, but this attribute omitted, a default value of 3 is used.
fade-border-px (opt.): The number of outer rows/columns used to fade to the background image.
Combine this attribute with border extension to avoid a reduced visible frame size.
If the SoftenBorders tag is specified, but this attribute omitted, a default value of 3 is used.

Temporal distortion configuration

If you do not want to configure temporal distortion yourself, you can find a description of the predefined presets here.

<TemporalDistortion enabled="true">
    <Display refresh-rate="float" fading-time="float" vsync="boolean" /> (opt.)
    <LCDBacklightDimming pwm-duty-cycle="float" pwm-frequency="float" /> (opt.)
    <Capture fps="float" exposure-time="float" readout-time="float" /> (opt.)
</TemporalDistortion>

Display: If this tag is completely omitted, the default values for all attributes are used.
refresh-rate (opt.): The simulated display's refresh rate in Hertz (Hz). If omitted or set to zero, the source video's frame rate is used. Although displays typically work at fixed rates such as 59,94 or 60 Hz, this avoids distortions from frame timing adjustments or tearing to be simulated unless explicitly wanted.
fading-time (opt.): A time in milli-seconds (ms) that the simulated display needs to switch from a currently displayed frame to new one, resulting in the old frame fading out and the new frame fading in. Although this time typically depends on each pixel's current and new brightnesses, this is an abstraction and will be applied to all pixels regardless of the pixel's current/new brightnesses.
vsync (opt.): Flag to specify if the simulated video player applies a v-sync mechanism. If not specified, the default value is true, as almost all players do this to avoid tearing artifacts. Simulating v-sync is only useful if the simulated display's refresh rate is different to the source video's frame rate.

LCDBacklightDimming: If this tag is completely omitted, no LCD backlight dimming is simulated. If it is specified, it enables the simulation of a pulse-width-modulated LCD backlight. Such a backlight is typically found in any LCD display and is used to dim the display's brightness. The temporal sampling of the capturing, especially when using a rolling shutter, will induce a flickering effect in the recorded video.
pwm-duty-cycle (opt.): A floating-point value between 0.0 and 1.0, representing a percentage of time that the pulse-width-modulated LCD backlight is on. The percentage directly corresponds to the simulated LCD brightness, with 100% (1.0) being the highest brightness, and 0% (0.0) being enirely dark.
If the attribute is not specified, a default value of 1.0 is used (no dimming).
pwm-frequency (opt.): The frequency of the pulse-width-modulation (PWM) in Hertz (Hz). If this attibute is not specified, 180 Hz is used, as this is a typical frequency for LCD backlights to operate on.

Capture: If this tag is completely omitted, the default values for all attributes are used.
fps (opt.): The frame rate the camera operates on.
If omitted or set to zero, the source video's frame rate is used.
exposure-time (opt.): The camera's exposure time in milli-seconds (ms). Must not be longer than 1000/fps ms.
If not specified or set to zero, it is automatically calculated as (1000/fps)/2 ms.
readout-time (opt.): Readout-time of the camera's image sensor in milli-seconds (ms). Omitting this attribute or setting it to zero simulates a global shutter. A positive non-zero value simulates a rolling shutter, which is very common for the widely used CMOS-sensors. Must be shorter or equal to the exposure time.

Automatic gain control configuration (AGC)

If you do not want to configure AGC distortion yourself, you can find a description of the predefined presets here.

<AutomaticGainControl enabled="true">
    <Method name="string" /> (mandatory)
    <LowerBound count="int" thresh="float" adjust="float" /> (mandatory)
    <UpperBound count="int" thresh="float" adjust="float" /> (mandatory)
</AutomaticGainControl>

Method: Mandatory tag specifying the method used to simulate the AGC.
name: The two currently supported methods are "Mean-Threshold-Offset-FixAdjustment" and "Mean-Threshold-Offset-PecentualAdjustment. Both specify a lower and an upper threshold of the overall frame brightness (thresh). If the actual frame brightness violates this threshold for count frames, the gain (currently simulated via an offset) is adjusted (adjust).
For the FixAdjustment method, the offset is simply adjusted by a fix value, while the PecentualAdjustment adjusts based on how far the actual brightness is away from the threshold.

Lower/UpperBound: Mandatory tags specifying the parameters to the AGC method.
count: Non-negative interger value that specified for how many frames the lower/upper threshold can be violated before the simulated gain is adjusted.
thresh: Non-negative floating-point value between 0 and 255. The value specified for the upper bound must be greater than the value specified for the lower bound.
adjust: Floating-point value for fix or percentual adjustment.
Percentual values need to be specified in range 0.0 to 1.0.

Automatic white balance configuration (AWB)

If you do not want to configure ABW distortion yourself, you can find a description of the predefined presets here.

<AutomaticWhiteBalance enabled="true">
    <Method name="string" /> (mandatory)
</AutomaticWhiteBalance>

Method: Mandatory tag specifying the method used to simulate the AWB.
name: The two currently supported methods are "Grayworld" and "Weng".
Greyworld is a quite simple approach that is likely to produces color-cast artifacts.
The method by Weng et al. is less likely to produce these artifacts.
(See the CamMark publications for more details both approaches.)

Color filter array configuration (CFA)

If you do not want to configure CFA distortion yourself, you can find a description of the predefined presets here.

<ColorFilterArray enabled="true">
    <Method name="string" /> (mandatory)
    <AAFilter enabled="boolean" /> (opt.)
</ColorFilterArray>

Method: Mandatory tag specifying the method used to simulate the CFA.
name: The only currently supported method is "SimpleBayer", simulating the typical sampling artifacts from the original Bayer color filter array.

AAFilter: Omitting this tag is equivalent to setting its enabled attribute to false.
enabled: If set to true, an anti-aliasing filter is simulated in front of the color filter array.
Most cameras that used color filter arrays employ such a filter.

Defocussing configuration

If you do not want to configure defocussing yourself, you can find a description of the predefined presets here.

<Defocus enabled="true">
    <GaussianBlur kernel-size="int" sigma="float" /> (opt.)
</Defocus>

GaussianBlur: Since this is currently the only supported defocussing tag,
defocussing distortion is not simulated if it is omitted.
kernel-size: The size of the filter-kernel for the Gaussian filter in pixels (px). If only the kernel-size is specified, the standard deviation sigma is automatically calculated from the filter size.
sigma: The desired standard daviation for the Gaussian filter. If only the standard deviation sigma is specified, the kernel-size is automatically calculated from sigma.

CamMark A Camcorder Copy Simulator