Overview
A command line for merging and processing exposure bracketed photos follows this pattern:
PhotomatixCL [Processing Options] [Output Options] [Input Format] <Input Files>
Input Files
The path or URL for each of the input bracketed photos are supplied one after the other, and after all other options have been supplied. All input photos will be merged together.
Note: The input files must be entered at the end of the command line and are not preceded by an option.
Input Format
If your input images are located on a web server and their URLs don't end with a valid image extension, add the -if option to specify the type of the images.
Processing Options
These include 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 either the name of a Photomatix preset or an XMP file containing Photomatix HDR settings. If multiple XMP files are provided, then multiple output files are produced in the same run.
Output Options
This is where you set the output path as well as options for the file format. There are two ways to supply the output path:
- 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.
- 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.)
If you specify the ‑d option rather than ‑o, then the ‑n and ‑q options determine what the file name will be.
The ‑n option determines the naming type. Types 1-4 need a set number supplied using the ‑q option. This can be any value you like; you might increment this for each set you process for example.
For all the naming types except number 4, if you process with more than one preset, the name of the processing algorithm will be appended to the name. Note that this is not always the same as the preset name. You can use the ‑xn name option to explicitly set the name that will be appended.
Here are some examples of what the different options do, when processing three images called Image1.jpg, Image2.jpg, and Image3.jpg. The third column is an example of the output if processing with more than one preset, and one of them used the Detail Enhancer algorithm.
| Argument | Name if only one preset | Name if multiple presets |
|---|---|---|
| -n 0 | Image1_2_3.jpg | Image1_2_3Enhancer.jpg |
| -n 1 -q 6 | Set063from_Image1.jpg | Set06Enhancer3from_Image1.jpg |
| -n 2 -q 6 | Set06.jpg | Set06Enhancer.jpg |
| -n 3 -q 6 | 3from_Image1Set06.jpg | Enhancer3from_Image1Set06.jpg |
| -n 4 -q 6 | Set06.jpg | Set06.jpg |
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 apply the the HDR settings in the 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"
See more samples on the Examples page or generate your own command samples with the PhotomatixCL Command Generator.
Options Reference
| Pre-processing & Merge to HDR Options | |||
|---|---|---|---|
| -a2 | Align the source images with the "Hand-held (standard)" preset | ||
| -a3 | Same as -a2 but without including perspective correction | ||
| -a2n (or -a3n) | Align without cropping the aligned results. This is recommended only if the result image has to be the same size as the input images, and may result in some small unusable areas around the edges that are left over from the alignment process. | ||
| -a2s (or -a3s) | Align and save the aligned results | ||
| -a2ns (or -a3ns) | Align without cropping the aligned results, and save the aligned results | ||
| -am <num> | Maximum 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 | ||
| -gn -gh -g <num> | Attempt to remove ghosts: -gn for normal ghosting detection, -gh for high ghosting detection, -g num for custom ghosting detection strength, where num is between 0 and 100 | ||
| -no0 -no1 -no2 | Reduce Noise: -no0 to reduce noise in underexposed photos, -no1 for normal and underexposed photos, -no2 for all photos | ||
| -nr <num> | Noise reduction strength for -n0, -n1 and -n2 options - e.g. -nr 100 (valid values vary between 50 and 150) | ||
| -e <num> | EV 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. | ||
| -lc | Perform 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 | ||
| -wb <num> | Color temperature for RAW conversion when source images are RAW files, e.g. -wb 7500 | ||
| -wbo <num> | Color temperature for overexposed RAW files only, e.g. -wbo 7500 | ||
| -wbn <num> | Color temperature for normal exposure RAW file only | ||
| -wbu <num> | Color temperature for underexposed RAW files only | ||
| -rb auto -rb fixed | Turn on or off automatic brightness adjustments when loading RAW files. Options are:
-af | When processing a single RAW file, automatically generate 'fake' exposures from the image in order to support Fusion presets. | |
| -tr | Consider files with the .tif extension coming from the Canon 1Ds and Phase One P45 as RAW files | ||
| HDR Processing (Tone Mapping/Fusion) Options | |||
| -x <preset> | HDR settings to use for tone mapping or fusing your images. The HDR settings can be provided using one of these two options:
You can also process with multiple presets by using multiple -x options, e.g. -x MyPreset1.xmp -x MyPreset2.xmp You can create an HDR settings XMP file using the Photomatix Pro application (you don't need a Photomatix Pro license to create and save an HDR settings file). | ||
| Finishing Options | |||
| -sa <num> | Sharpening Amount, e.g. -sa 50 (valid values are between 0 and 150) | ||
| -sr <num> | Sharpening Radius (only works if -sa is greater than 0), e.g. -sr 0.9 (valid values are between 0.5 and 3) | ||
| -st <num> | Sharpening Threshold (only works if -sa is greater than 0), e.g. -st 2 (valid values vary between 0 and 20) | ||
| -ch <num> | Contrast adjustment for highlights, e.g. -ch 10 (valid values are between 0 and 100) | ||
| -cl <num> | Contrast adjustment for lights, e.g. -cl 10 (valid values are between 0 and 100) | ||
| -cd <num> | Contrast adjustment for darks, e.g. -cd -10 (valid values are between 0 and -100) | ||
| -cs <num> | Contrast adjustment for shadows, e.g. -cs -10 (valid values are between 0 and -100) | ||
| Performance Options | |||
| -mp <num> | Specify maximum number of cores / CPUs to use when processing images - e.g. -mp 4 to use up to 4 CPUs. Default is 1. | ||
| -md | Use scratch disk option for Details Enhancer and Fusion/Natural methods (reduces needed memory by a factor of 3). | ||
| -sd <path> | Scratch directory to use for the temporary files when required (without this option the standard temp directory will be used), e.g. -sd E:\temp | ||
| Input Options | |||
| -if <format> | When you supply URLs as input, add this option to specify the format of the input images (e.g. -if jpg, -if raw). | ||
| Output / Saving Options | |||
| -o <path> | Name of the resulting image (without the extension) if -n option is not specified | ||
| -d <path> | Destination path for the resulting image, including the last "\" or "/" character if applicable. E.g. -d C:\images\ | ||
| -n <num> | Naming options for the resulting images. Options are:
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 | ||
| -ns <num> <suffix> | Naming options for the output images (same as above) with appended suffix. E.g. -ns 0 trial1 | ||
| -xn | Override suffix that is applied to output file names when there is more than one preset used (i.e. multiple -x options are supplied). If this option follows a -x option, then the suffix passed here will be used for output files processed with this preset, rather than the name of the algorithm that was applied. This option requires using the -x option listed in the Setting Options section. E.g. -x mypreset1.xmp -xn MyPreset1. It has no effect if only one -x option is supplied. | ||
| -s jpg -s dng -s tif | Save output image in a format different from the one of the source images: JPEG, DNG and TIFF respectively. | ||
| -j <num> | Jpeg quality for output image saved in the JPEG format, e.g. -j 90 (default is 100) | ||
| -bi <num> | Bit-depth of output image when saving as TIFF or DNG: -bi 8 for 8 bits/channel, -bi 16 for 16/bits channel | ||
| -k <keyword> | Tag saved files with this keyword | ||
| -rs <num> <num> 0 -rs <num> 1 1 | 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. | ||
| -p | Create output image as a 360 degree panorama suitable to be viewed in a panorama viewer - useful for methods Details Enhancer and Fusion/Natural only. | ||
| -h <format> | HDR saving options The default format to save 32-bit HDR images is Radiance (.hdr). The -h options change that:
| ||
| -co <num> | Output 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 | |||
| -ll <key> | Load license key: -ll YourLicenseKeyCodeNumber | ||
| -lq | Print number of HDR merges remaining for the current month (printed as a sentence) | ||
| -lqs | Print 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 | ||
| -trial | Apply a watermark to the image and do not decrement the number of HDR merges, even if a valid license is present | ||
Return Codes and Errors
If PhotomatixCL fails to process the files for some reason, it will return a negative exit code. This will generally 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. Some of the more common ones are listed below.
| PhotomatixCL Error Codes | |
|---|---|
| -4, -40 to -44 | Insufficient memory to perform processing |
| -100 to -109 | Invalid options supplied |
| -103 | Unsupported input file type |
| -110 | No more HDR merges available on license |
| -111 | EXIF data not found in image(s), and EV spacing not supplied |
| -112, -113 | Unable to read input file |
| -201 | Images do not all have the same dimensions |
| -202 | Images do not all have the same number of color channels |
| -203 | Images do not all have the same bit depth |
| -301, -302 | Invalid TIFF file |
If you need help interpreting an error code or have any other issues, please contact the Photomatix support team.