Command-Line Options: Difference between revisions

From RawPedia
Jump to navigation Jump to search
(Updated -w and -R section)
(6 intermediate revisions by 2 users not shown)
Line 6: Line 6:


Since RawTherapee 5.1, two executables are provided.
Since RawTherapee 5.1, two executables are provided.
=== RawTherapee GUI ===
=== RawTherapee GUI ===
Use this application to start the version with graphical user interface.
Use this application to start the version with graphical user interface.
Line 11: Line 12:
Usage:
Usage:
: <code>rawtherapee <selected dir></code>
: <code>rawtherapee <selected dir></code>
:: Start [[The_File_Browser_Tab | File Browser]] inside directory.
:: Start [[The_File_Browser_Tab | File Browser]] inside folder.
: <code>rawtherapee <file></code>
: <code>rawtherapee <file></code>
:: Start [[The_Image_Editor_Tab | Image Editor]] with file.
:: Start [[The_Image_Editor_Tab | Image Editor]] with file.


: <code>-w</code>
: <code>-w</code>
:: Do not open the Windows console. This option is available in Windows only. If you pass parameters to the RawTherapee executable it spawns a console window so that you can see the verbose output of your processing. Normally Windows closes this console directly after RawTherapee is terminated. To let you see the output we added a prompt which waits for you to hit a key before closing the console. By specifying <code>-w</code> no console will be opened and therefore no key press is needed. Useful if you want to invoke rawtherapee.exe in batch, e.g. from a PowerShell script.
:: Do not open the Windows console. This option is available in Windows only. If you pass parameters to the RawTherapee executable it spawns a console window so that you can see the verbose output of your processing. Normally Windows closes this console directly after RawTherapee is terminated. To let you see the output we added a prompt which waits for you to hit a key before closing the console. By specifying <code>-w</code> no console will be opened and therefore no key press is needed. Useful if you want to invoke <code>rawtherapee.exe</code> in batch, e.g. from a PowerShell script. Please note that <code>-w</code> will have no effect for "Debug" builds where a console window will be opened unless you're starting RawTherapee from a console window already.
 
: <code>-v</code>
:: Print the RawTherapee version number and exit.
 
: <code>-R</code>
:: "Remote" mode, available since RawTherapee 5.2. When opening an image using "Open with" or by passing its filename as an argument, without using the <code>-R</code> option RawTherapee will open in "no-File-Browser" mode - that is a mode which lacks the File Browser and Queue tabs as well as the Preferences button. Using the new <code>-R</code> mode, RawTherapee will open in a full-fledged instance. Using <code>-R</code> also allows you to open an image in an already-running instance of RawTherapee, if that instance was also started using <code>-R</code>. The no-File-Browser mode exists for historical reasons when RAM requirements were higher and stability was worse. Now that RawTherapee's memory usage is optimized and it can quickly and reliably open folders with thousands of images, users may prefer using the <code>-R</code> mode by default.
 
: <code>-h -?</code>
:: Display these commands.


=== RawTherapee CLI ===
=== RawTherapee CLI ===
Line 26: Line 36:


: <code>-w</code>
: <code>-w</code>
:: Do not open the Windows console. This option is available in Windows only. If you pass parameters to the RawTherapee executable it spawns a console window so that you can see the verbose output of your processing. Normally Windows closes this console directly after RawTherapee is terminated. To let you see the output we added a prompt which waits for you to hit a key before closing the console. By specifying <code>-w</code> no console will be opened and therefore no key press is needed. Useful if you want to invoke rawtherapee.exe in batch, e.g. from a PowerShell script.
:: Do not open the Windows console. This option is available in Windows only. If you pass parameters to the RawTherapee executable it spawns a console window so that you can see the verbose output of your processing. Normally Windows closes this console directly after RawTherapee is terminated. To let you see the output we added a prompt which waits for you to hit a key before closing the console. By specifying <code>-w</code> no console will be opened and therefore no key press is needed. Useful if you want to invoke <code>rawtherapee-cli.exe</code> in batch, e.g. from a PowerShell script.
 
Other options used with <code>-c</code>:
: <code>rawtherapee-cli [-o <output>|-O <output>] [-q] [-a] [-s|-S] [-p <files>] [-d] [-j[1-100] [-js<1-3>]|[-b<8|16>] <[-t[z] | [-n]]] [-Y] [-f] -c <input></code>
 
: <code>-c <files></code>
:: Specify one or more input files or folders.
:: When specifying folders, RawTherapee will look for image files which comply with the selected parsed extensions (see the <code>-a</code> option).
:: The <code>-c</code> option must always be the last one.


Other options used with <code>-c</code> (<code>-c</code> must be the last option):
: <code>rawtherapee-cli [-o <output>|-O <output>] [-q] [-a] [-s|-S] [-p <files>] [-d] [-j[1-100] [-js<1-3>]|[-b<8|16>] <[-t[z] | [-n]]] [-Y] -c <input></code>
: <code>-q<file>|<dir></code>
:: Quick Start mode : do not load cached files to speedup start time.
: <code>-o <file>|<dir></code>
: <code>-o <file>|<dir></code>
:: Select output file or directory.
:: Select output file or folder.
:: Saves output file alongside input file if -o is not specified.
 
: <code>-O <file>|<dir></code>
: <code>-O <file>|<dir></code>
:: Select output file or directory and copy PP3 file into it.
:: Select output file or folder and copy PP3 file into it.
:: Saves output file alongside input file if -O is not specified.
 
: <code>-q<file>|<dir></code>
:: Quick-start mode. Does not load cached files to speedup start time.
 
: <code>-a<file>|<dir></code>
: <code>-a<file>|<dir></code>
:: Stands for 'all'. When specifying a directory, process all images specified in the extension list from the options file, even those not actually selected.
:: Process all supported image file types when specifying a folder, even those not currently selected in Preferences > File Browser > Parsed Extensions.
 
: <code>-s</code>
: <code>-s</code>
:: Include the PP3 file next to the input file (with the same name) to build the image parameters, e.g. for photo.raw there should be a photo.raw.pp3 file in the same directory. If the file does not exist, internal default (neutral) values (not those in "Default.pp3") will be used.
:: Use the existing sidecar file to build the processing parameters, e.g. for photo.raw there should be a photo.raw.pp3 file in the same folder. If the sidecar file does not exist, neutral values will be used.
 
: <code>-S</code>
: <code>-S</code>
:: Like <code>-s</code> but skip if the PP3 file does not exist.
:: Like <code>-s</code> but skip if the sidecar file does not exist.
 
: <code>-p <file.pp3></code>
: <code>-p <file.pp3></code>
:: Specify PP3 file to be used for all conversions. You can specify as many <code>-p</code> options as you like (see description below).
:: Specify processing profile to be used for all conversions. You can specify as many sets of "-p <file.pp3>" options as you like, each will be built on top of the previous one, as explained below.
 
: <code>-d</code>
: <code>-d</code>
:: Use the default raw or non-raw PP3 file as set in "[[Main_Page#Preferences | Preferences]] > [[Image_Processing_Tab | Image Processing]] > [[Image_Processing_Tab#Default_Processing_Profile | Default Processing Profile]]"
:: Use the default raw or non-raw PP3 file as set in "[[Main_Page#Preferences | Preferences]] > [[Image_Processing_Tab | Image Processing]] > [[Image_Processing_Tab#Default_Processing_Profile | Default Processing Profile]]"
: <code>-j[1-100]</code>
: <code>-j[1-100]</code>
:: Specify output to be JPEG (on by default). Optionally add compression 1-100 (default value: 92).
:: Specify output to be JPEG (default, if -t and -n are not set).
:: Optionally, specify compression 1-100 (default value: 92).
 
: <code>-js<1-3></code>
: <code>-js<1-3></code>
:: Specify the JPEG [http://en.wikipedia.org/wiki/Chroma_subsampling chroma subsampling] parameter, where:
:: Specify the JPEG [http://en.wikipedia.org/wiki/Chroma_subsampling chroma subsampling] parameter, where:
Line 56: Line 84:
::: 3 = Best quality:    1x1, 1x1, 1x1 (4:4:4)
::: 3 = Best quality:    1x1, 1x1, 1x1 (4:4:4)
::::    No chroma subsampling.
::::    No chroma subsampling.
: <code>-b<8|16></code>
: <code>-b<8|16></code>
:: Specify bit depth per channel (only applies to TIFF and PNG output).
:: Specify bit depth per channel (16 by default).
:: Only applies to TIFF and PNG output, JPEG is always 8.
 
: <code>-t[z]</code>
: <code>-t[z]</code>
:: Specify output to be TIFF (16-bit if <code>-b8</code> is not set).
:: Specify output to be TIFF (16-bit if <code>-b8</code> is not set).
:: Uncompressed by default, or ZIP compression with 'z'.
:: Uncompressed by default, or ZIP compression with 'z'.
: <code>-n</code>
: <code>-n</code>
:: Specify output to be compressed PNG (16-bit if <code>-b8</code> is not set).
:: Specify output to be compressed PNG (16-bit if <code>-b8</code> is not set).
:: Compression is hard-coded to level 6.
: <code>-Y</code>
: <code>-Y</code>
:: Overwrite output if present.
:: Overwrite output if present.
: <code>-f</code>
:: Use the custom fast-export processing pipeline.


Your PP3 files can be incomplete, RawTherapee will set the values as follows:
Your PP3 files can be incomplete, RawTherapee will set the values as follows:
# A new profile is created using internal default (neutral) values (hard-coded into RawTherapee),
# A new processing profile is created using neutral values,
# then overridden by those found in the default raw or non-raw PP3 file (if <code>-d</code> has been set),
# If the <code>-d</code> option is set, the values are overridden by those found in the default raw or non-raw processing profile,
# then overridden by those found in the PP3 files provided by <code>-p</code>, each one overriding the previous values,
# If one or more <code>-p</code> options are set, the values are overridden by those found in these processing profiles,
# then overridden by the sidecar file if <code>-s</code> is set and if the file exists; the time where the sidecar file is used depends on the position of the <code>-s</code> switch in the command line relative to the <code>-p</code> parameters, e.g.
# If the <code>-s</code> or <code>-S</code> options are set, the values are finally overridden by those found in the sidecar files.
#: <code>-p first.pp3 -p second.pp3 -s -p fourth.pp3</code>
The processing profiles are processed in the order specified on the command line.


== Redirect Output ==
== Redirect Output ==
Line 83: Line 120:
== Examples ==
== Examples ==
=== Example 1 ===
=== Example 1 ===
In Linux, process a single raw which resides in /tmp and is called "photo.raw", use its sidecar file "photo.raw.pp3" during conversion, save it in the same directory as "foo.tif", and overwrite the file "foo.tif" if it exists:
In Linux, process a single raw which resides in /tmp and is called "photo.raw", use its sidecar file "photo.raw.pp3" during conversion, save it in the same folder as "foo.tif", and overwrite the file "foo.tif" if it exists:
  <code>rawtherapee-cli -o /tmp/foo.tif -s -t -Y -c /tmp/photo.raw</code>
  <code>rawtherapee-cli -o /tmp/foo.tif -s -t -Y -c /tmp/photo.raw</code>


=== Example 2 ===
=== Example 2 ===
In the next example, we'll assume that you want to quickly process all your raw photos from the /tmp/jane01 directory to a web sub-directory by using the default profile as a basis, using the sidecar profile if it exist, but with removing some Exif tags (e.g. the camera's serial number) and adding some IPTC tags (e.g. your usual copyright parameters), plus resize and sharpen the image for the web (spread over multiple lines for clarity):
In the next example, we'll assume that you want to quickly process all your raw photos from the /tmp/jane01 folder to a web sub-folder by using the default profile as a basis, using the sidecar profile if it exist, but with removing some Exif tags (e.g. the camera's serial number) and adding some IPTC tags (e.g. your usual copyright parameters), plus resize and sharpen the image for the web (spread over multiple lines for clarity):
  <code>rawtherapee-cli -o /tmp/Jane01/web -p ~/profiles/iptc.pp3 -s -p ~/profiles/exif.pp3 -p ~/profiles/web.pp3 -t -Y -d -c /tmp/Jane01/</code>
  <code>rawtherapee-cli -o /tmp/Jane01/web -p ~/profiles/iptc.pp3 -s -p ~/profiles/exif.pp3 -p ~/profiles/web.pp3 -t -Y -d -c /tmp/Jane01/</code>


Line 101: Line 138:


=== Example 3 ===
=== Example 3 ===
In the third example, we will see how long it takes to process every raw file in a directory, assuming that each raw photo has a corresponding processing profile, and discard each output file:
In the third example, we will see how long it takes to process every raw file in a folder, assuming that each raw photo has a corresponding processing profile, and discard each output file:
  <code><nowiki>time {
  <code><nowiki>time {
  for f in /home/user/photos/2011-11-11/*.raw; do
  for f in /home/user/photos/2011-11-11/*.raw; do
   rawtherapee -o /dev/null -S -t -Y -c "$f";
   rawtherapee-cli -o /dev/null -S -t -Y -c "$f";
  done
  done
  }</nowiki></code>
  }</nowiki></code>

Revision as of 21:20, 22 August 2017

Explanation

<Chevrons> indicate parameters you can change.
[Square brackets] mean the parameter is not mandatory.
The pipe symbol | indicates a choice of one or the other.
The dash symbol - denotes a range of possible values from one to the other.

Since RawTherapee 5.1, two executables are provided.

RawTherapee GUI

Use this application to start the version with graphical user interface.

Usage:

rawtherapee <selected dir>
Start File Browser inside folder.
rawtherapee <file>
Start Image Editor with file.
-w
Do not open the Windows console. This option is available in Windows only. If you pass parameters to the RawTherapee executable it spawns a console window so that you can see the verbose output of your processing. Normally Windows closes this console directly after RawTherapee is terminated. To let you see the output we added a prompt which waits for you to hit a key before closing the console. By specifying -w no console will be opened and therefore no key press is needed. Useful if you want to invoke rawtherapee.exe in batch, e.g. from a PowerShell script. Please note that -w will have no effect for "Debug" builds where a console window will be opened unless you're starting RawTherapee from a console window already.
-v
Print the RawTherapee version number and exit.
-R
"Remote" mode, available since RawTherapee 5.2. When opening an image using "Open with" or by passing its filename as an argument, without using the -R option RawTherapee will open in "no-File-Browser" mode - that is a mode which lacks the File Browser and Queue tabs as well as the Preferences button. Using the new -R mode, RawTherapee will open in a full-fledged instance. Using -R also allows you to open an image in an already-running instance of RawTherapee, if that instance was also started using -R. The no-File-Browser mode exists for historical reasons when RAM requirements were higher and stability was worse. Now that RawTherapee's memory usage is optimized and it can quickly and reliably open folders with thousands of images, users may prefer using the -R mode by default.
-h -?
Display these commands.

RawTherapee CLI

Use this application to start the command line only version. You'll find all command line options to develop your photos without any graphical user interface.

Usage:

rawtherapee-cli <options> -c <dir>|<files>
Convert files in batch with default parameters if no <options> specified.
-w
Do not open the Windows console. This option is available in Windows only. If you pass parameters to the RawTherapee executable it spawns a console window so that you can see the verbose output of your processing. Normally Windows closes this console directly after RawTherapee is terminated. To let you see the output we added a prompt which waits for you to hit a key before closing the console. By specifying -w no console will be opened and therefore no key press is needed. Useful if you want to invoke rawtherapee-cli.exe in batch, e.g. from a PowerShell script.

Other options used with -c:

rawtherapee-cli [-o <output>|-O <output>] [-q] [-a] [-s|-S] [-p <files>] [-d] [-j[1-100] [-js<1-3>]|[-b<8|16>] <[-t[z] | [-n]]] [-Y] [-f] -c <input>
-c <files>
Specify one or more input files or folders.
When specifying folders, RawTherapee will look for image files which comply with the selected parsed extensions (see the -a option).
The -c option must always be the last one.
-o <file>|<dir>
Select output file or folder.
Saves output file alongside input file if -o is not specified.
-O <file>|<dir>
Select output file or folder and copy PP3 file into it.
Saves output file alongside input file if -O is not specified.
-q<file>|<dir>
Quick-start mode. Does not load cached files to speedup start time.
-a<file>|<dir>
Process all supported image file types when specifying a folder, even those not currently selected in Preferences > File Browser > Parsed Extensions.
-s
Use the existing sidecar file to build the processing parameters, e.g. for photo.raw there should be a photo.raw.pp3 file in the same folder. If the sidecar file does not exist, neutral values will be used.
-S
Like -s but skip if the sidecar file does not exist.
-p <file.pp3>
Specify processing profile to be used for all conversions. You can specify as many sets of "-p <file.pp3>" options as you like, each will be built on top of the previous one, as explained below.
-d
Use the default raw or non-raw PP3 file as set in " Preferences > Image Processing > Default Processing Profile"
-j[1-100]
Specify output to be JPEG (default, if -t and -n are not set).
Optionally, specify compression 1-100 (default value: 92).
-js<1-3>
Specify the JPEG chroma subsampling parameter, where:
1 = Best compression: 2x2, 1x1, 1x1 (4:2:0)
Chroma halved vertically and horizontally.
2 = Balanced: 2x1, 1x1, 1x1 (4:2:2)
Chroma halved horizontally.
3 = Best quality: 1x1, 1x1, 1x1 (4:4:4)
No chroma subsampling.
-b<8|16>
Specify bit depth per channel (16 by default).
Only applies to TIFF and PNG output, JPEG is always 8.
-t[z]
Specify output to be TIFF (16-bit if -b8 is not set).
Uncompressed by default, or ZIP compression with 'z'.
-n
Specify output to be compressed PNG (16-bit if -b8 is not set).
Compression is hard-coded to level 6.
-Y
Overwrite output if present.
-f
Use the custom fast-export processing pipeline.

Your PP3 files can be incomplete, RawTherapee will set the values as follows:

  1. A new processing profile is created using neutral values,
  2. If the -d option is set, the values are overridden by those found in the default raw or non-raw processing profile,
  3. If one or more -p options are set, the values are overridden by those found in these processing profiles,
  4. If the -s or -S options are set, the values are finally overridden by those found in the sidecar files.

The processing profiles are processed in the order specified on the command line.

Redirect Output

To redirect RawTherapee's output to a text file, you have to start it from a console and append the redirection code as follows:

Windows (cmd.exe)
rawtherapee.exe > rtlog.txt 2>&1
Linux
rawtherapee &> rtlog.txt

Examples

Example 1

In Linux, process a single raw which resides in /tmp and is called "photo.raw", use its sidecar file "photo.raw.pp3" during conversion, save it in the same folder as "foo.tif", and overwrite the file "foo.tif" if it exists:

rawtherapee-cli -o /tmp/foo.tif -s -t -Y -c /tmp/photo.raw

Example 2

In the next example, we'll assume that you want to quickly process all your raw photos from the /tmp/jane01 folder to a web sub-folder by using the default profile as a basis, using the sidecar profile if it exist, but with removing some Exif tags (e.g. the camera's serial number) and adding some IPTC tags (e.g. your usual copyright parameters), plus resize and sharpen the image for the web (spread over multiple lines for clarity):

rawtherapee-cli -o /tmp/Jane01/web -p ~/profiles/iptc.pp3 -s -p ~/profiles/exif.pp3 -p ~/profiles/web.pp3 -t -Y -d -c /tmp/Jane01/

The processing profile will be built as follows:

  1. A new profile is created using internal default values (hard-coded into RawTherapee),
  2. then overridden by those from the default raw profile (-d),
  3. then overridden by those found in iptc.pp3,
  4. then overridden by those found in the sidecar file (-s) if it exists, so you can force some IPTC tags even if already set by iptc.pp3,
  5. then overridden by those found in exif.pp3, so you can force the profile to erase some tags,
  6. then overridden by those found in web.pp3, to resize and sharpen the image, and make sure that the output colorspace is sRGB.

As you can see, the position of the -s switch tells when to load the sidecar profile relative to the other -p parameters. That is not the case for the -d switch.

Example 3

In the third example, we will see how long it takes to process every raw file in a folder, assuming that each raw photo has a corresponding processing profile, and discard each output file:

time {
 for f in /home/user/photos/2011-11-11/*.raw; do
   rawtherapee-cli -o /dev/null -S -t -Y -c "$f";
 done
 }