PhotomatixCL documentation

PhotomatixCL is a command line program running on Windows and Linux. It provides a way to automate HDR processing and integrate HDR processing into a larger system, workflow or application.

PhotomatixCL takes a set of exposure bracketed images (JPEG, TIFF or RAW), merges the images to HDR, and outputs a tone mapped or fused image saved as JPEG or TIFF, and optionally a 32-bit merged HDR image saved as EXR or Radiance.

You can download PhotomatixCL and try it for free from its download page.

Usage

A command line for processing bracketed photos follows this pattern:

[Processing Options] [Output Options] [Input Files]

[Processing Options] refers to your choice for pre-processing (merge to HDR, alignment, deghosting, etc.), HDR processing (tone mapping/fusion) and finishing.

The options for HDR processing are supplied using the -x option followed by the XMP preset file containing tone mapping/fusion settings. If multiple XMP files are provided, then multiple output files are produced in the same run.

You can create an XMP preset file using the Photomatix Pro application (you don't need a Photomatix Pro license to save a preset file).

[Output Options] refers to the output path as well as options for the file format. There are two ways to supply the output path:

  1. with the -o option followed by the path to the output filename but without its extension. Use this option when you want to choose a specific output filename for the resulting image.
  2. with the -d option followed by the path to the output folder and ending with the "\" character. The filename of the output image will be created by Photomatix similarly to how the batch of Photomatix Pro does it. (On Windows, due to the way its command line works, if you have this path in quotes, you need two backslash "\" characters at the end rather than one.)

[Input Files] refers to the path of each of the source photos supplied one after the other.

This means that the input files must be entered at the end of the command line and are not preceded by an option.

Sample:

The following sample command (run on a Windows OS) aligns and merges to HDR the files Image1.jpg, Image2.jpg and Image3.jpg, and processes them with the preset in the MyPreset.xmp file:

PhotomatixCL -a2 -x "c:\Presets\MyPreset.xmp" -d c:\Images\ResultFolder\ "c:\Images\Image1.jpg" "c:\Images\Image2.jpg" "c:\Images\Image3.jpg"

Return codes and errors

If PhotomatixCL fails to process the files for some reason, it will return a negative exit code. Sometimes this will be accompanied by an error message, but the exit code is the most reliable way to determine if it succeeded.

There are many different internal negative error codes occurring in various situations. A return code of -4 always means that there wasn't enough memory to perform the processing.

If you need help interpreting an error code or have any other issues, please contact the Photomatix support team.

Options Reference

Pre-processing / Merge to HDR Options
-a2Align the source images with the "Hand-held (standard)" preset
-a3Same as -a2 but without including perspective correction
-a2n(or -a3n) Align without cropping the aligned results
-a2s(or -a3s) Align and save the aligned results
-a2ns(or -a3ns) Align without cropping the aligned results, and save the aligned results
-amMaximum shift between the images that will be considered when aligning, as a percentage of image width/height - e.g. -am 20 to allow an image to be shifted by 20% of its size with respect to the others
-gAttempt to reduce ghosting artifacts: -gn for normal detection, -gh for high detection, -g num for custom ghost reduction strength, where num is between 0 and 100
-caReduce Chromatic Aberrations
-noReduce Noise: -no0 to reduce noise in underexposed photos, -no1 for normal and underexposed photos, -no2 for all photos
-nrNoise reduction strength for -n0, -n1 and -n2 options - e.g. -nr 100 (valid values vary between 50 and 150)
-afAllow exposure fusion presets to be used on a single RAW image by automatically generating multiple exposures from the image
-lcPerform automatic lens correction of RAW images if the camera and lens used to take the photo can be determined with certainty, and lens correction information is available for that lens and camera
-wbColor temperature for RAW conversion when source images are RAW files, e.g. -wb 7500
-wboColor temperature for overexposed RAW files only, e.g. -wbo 7500
-wbnColor temperature for normal exposure RAW file only
-wbuColor temperature for underexposed RAW files only
-rb

Turn on or off automatic brightness adjustments when loading RAW files. Options are:

  • -rb auto — automatically adjust the brightness of the image when loading (default)
  • -rb fixed — load the image without any brightness adjustments
-trConsider files with the .tif extension coming from the Canon 1Ds and Phase One P45 as RAW files
-eEV spacing for merging to HDR when exposure information not found on source files, e.g. -e 2.0 for images with a two EV difference between them.
-cuTonal curve for HDR generation. Options are -cu 0 for tonal curve of ICC profiles of source images (default), -cu 1 to attempt to recover tone curve applied
HDR Processing / Settings Options
-x

Name of the Photomatix preset XMP file containing the HDR settings to use for tone mapping or fusing your images, e.g. -x mypreset.xmp

You can also process with multiple presets by using multiple -x options, e.g. -x mypreset1.xmp -x mypreset2.xmp
Finishing Options
-saSharpening Amount, e.g. -sa 50 (valid values are between 0 and 150)
-srSharpening Radius (only works if -sa is greater than 0), e.g. -sr 0.9 (valid values are between 0.5 and 3)
-stSharpening Threshold (only works if -sa is greater than 0), e.g. -st 2 (valid values vary between 0 and 20)
-chContrast adjustment for highlights, e.g. -ch 10 (valid values are between 0 and 100)
-clContrast adjustment for lights, e.g. -cl 10 (valid values are between 0 and 100)
-cdContrast adjustment for darks, e.g. -cd -10 (valid values are between 0 and -100)
-csContrast adjustment for shadows, e.g. -cs -10 (valid values are between 0 and -100)
Performance Options
-mpSpecify maximum number of cores / CPUs to use when processing images - e.g. -mp 4 to use up to 4 CPUs. Default is 1.
-mdUse scratch disk option for Details Enhancer and Fusion/Natural methods (reduces needed memory by a factor of 3).
-sdScratch directory to use for the temporary files when required (without this option the standard temp directory will be used), e.g. -sd E:\temp
Output / Saving Options
-oName of the resulting image (without the extension) if -n option is not specified
-dDestination path for the resulting image, including the last "\" character if applicable. E.g. -d C:\images\
-n

Naming options for the resulting images. Options are:

  • -n 0 for output name starting with name of first image in the set (default)
  • -n 1 for name starting with set number
  • -n 2 for shortened version starting with set number
  • -n 3 for name ending with set number
  • -n 4 for shortened version starting with set number, and method name if more than one method used.

In the case of 1, 2, 3 or 4 set number has to be given with argument -q, e.g. -q 3

-o option is ignored if you use one of these options
-nsNaming options for the output images (same as above) with appended suffix. E.g. -ns 0 trial1
-xn

String that refers to the preset XMP file (used to process the image with the option -x) in the filename of the output image.

This option requires using the -x option listed in the Setting Options section. E.g. -x mypreset1.xmp -xn "My Preset 1"

-sSave output image in a format different from the one of the source images. Options are: -s tif, -s jpg and -s dng
-jJpeg quality for output image saved in the JPEG format, e.g. -j 90 (default is 100)
-biBit-depth of output image when saving as TIFF or DNG: -bi 8 for 8 bits/channel, -bi 16 for 16/bits channel
-kTag saved files with this keyword
-rs

Resize the output image.

Specify both the longer and shorter side lengths like this for example: -rs 1024 768 0 to resize the image to 1024x768 or 768x1024, depending on aspect ratio

If you specify only the longer side length, the shorter side will be calculated from the original image size - for example: -rs 1024 1 1 to have the longest side be 1024.

Note that regardless of whether the images are portrait or landscape, the longest side is always specified first. This option requires that the new width and height are smaller than the original image's ones.

-pCreate output image as a 360 degree panorama suitable to be viewed in a panorama viewer - useful for methods Details Enhancer and Fusion/Natural only.
-hHDR saving options: -h "exr" will save the HDR image in the OpenEXR format, -h "remove" will remove the HDR image after having tone mapped it.
-coOutput color space when source images are RAW files. Options are -co 0 for sRGB, -co 1 for AdobeRGB (default), -co 2 for ProPhotoRGB
Licensing Options
-llLoad license key:   -ll YourLicenseKeyCodeNumber
-lqPrint number of HDR merges remaining for the current month (printed as a sentence)
-lqsPrint number of HDR merges remaining for the current month (just the number is printed)
-allowwatermark  If there are no more HDR merges remaining, apply a watermark to the image rather than exiting with an error
-trialApply a watermark to the image and do not decrement the number of HDR merges, even if a valid license is present
Legacy / Compatibility Options (only relevant if you had been using very old versions of PhotomatixCL)
-0Combine the source images with Average
-1Combine the source images with Fusion/Auto
-2Combine the source images with Fusion/Natural
-2aAccentuation for method "Natural" e.g. -2a 0.5 (valid values are between -10 and 10)
-2bBlending Point for method "Natural" e.g. -2b 0.5 (valid values are between -10 and 10)
-2cColor Saturation for method "Natural" e.g. -2c 0.5 (valid values are between -10 and 10)
-2hSharpness for method "Natural" e.g. -2h 0.5 (valid values are between 0 and 10)
-2kBlack Point for method "Natural" e.g. -2k 0.5 (valid values are between 0 and 10)
-2mMidtone for method "Natural" e.g. -2m 0.5 (valid values are between -10 and 10)
-2sShadows for method "Natural" e.g. -2s 0.5 (valid values are between -10 and 10)
-2wWhite Point for method "Natural" e.g. -2w 0.5 (valid values are between 0 and 10)
-4Combine the source images with Fusion/Intensive
-4cColor Saturation for method "Intensive" e.g. -4c 0.5 (valid values are between -10 and 10)
-4rRadius for method "Intensive" e.g. -4r 30 (valid values are between 10 and 70)
-4sStrength for method "Intensive" e.g. -4s 0.5 (valid values are between -10 and 10)
-5Combine the source images with Fusion/Realistic
-5aStrength for method "Realistic" e.g. -2a 0.5 (valid values are between -10 and 10)
-5cColor Saturation for method "Realistic" e.g. -2c 0.5 (valid values are between -10 and 10)
-5hSharpness for method "Realistic" e.g. -2h 0.5 (valid values are between 0 and 10)
-3Merge the source images into an HDR image (by default saved in Radiance ".hdr" format)
-a1Align the source images with the "by correcting shifts" method
-t1Tone map HDR image with "Details Enhancer"
-t2Tone map HDR image with "Tone Compressor"
-x1Settings file in XMP format for tone mapping method "Details Enhancer", .e.g. -x1 EnhancerSettings.xmp
-x2Settings file in XMP format for tone mapping method "Tone Compressor", .e.g. -x2 CompressorSettings.xmp