More CLI examples of load parameters including EXR, EXIF meta-data re…

…orientation for JPG files, and exposure control for HDR DDS files.

Src/CommandHelp.cpp

@@ -179,10 +179,10 @@ are sufficient. Image types with load parameters:
         srgb  - Apply gamma compression by applying a Linear->sRGB transform.
   gamma:Gamma value. Used when an encoding-gamma is needed. Default is 2.2*.
         Range is [0.5,4.0]
-  tone: For HDR images. Tone-map exposure applied if this is >= 0.0. A value
-        of 0.0 is black. A value of 4.0 is over-exposed. Negative means do
-        not apply tone-map exposure function. Default is -1.0*. Non-negative
-        valid range is [0.0,4.0]
+  tone: For HDR images. Tone-map exposure applied if this is >= 0.0. The
+        non-negative valid range is [0.0,4.0]. A value of 0.0 is black and 4.0
+		is over-exposed. A value of 1.0 is neutral. Negative values do not
+        apply tone-map exposure. Default is -1.0* for no application.
 
 --inDDS
   corr: Gamma correction mode. Possible values:
@@ -191,10 +191,10 @@ are sufficient. Image types with load parameters:
         gamc  - Apply gamma compression using an encoding-gamma of 1.0/gamma.
         srgb  - Apply gamma compression by applying a Linear->sRGB transform.
   gamma:Gamma value. Used when an encoding-gamma is needed. Default is 2.2*.
-  tone: For HDR images. Tone-map exposure applied if this is >= 0.0. A value
-        of 0.0 is black. A value of 4.0 is over-exposed. Negative means do
-        not apply tone-map exposure function. Default is -1.0*. Non-negative
-        valid range is [0.0,4.0]
+  tone: For HDR images. Tone-map exposure applied if this is >= 0.0. The
+        non-negative valid range is [0.0,4.0]. A value of 0.0 is black and 4.0
+		is over-exposed. A value of 1.0 is neutral. Negative values do not
+        apply tone-map exposure. Default is -1.0* for no application.
   spred:Spread single channel. Boolean true* or false. For DDS files with a
         single Red or Luminance componentconly, spread it to all the RGB
         channels if set to true. If false the red channel takes the value.
@@ -231,10 +231,10 @@ are sufficient. Image types with load parameters:
         gamc  - Apply gamma compression using an encoding-gamma of 1.0/gamma.
         srgb  - Apply gamma compression by applying a Linear->sRGB transform.
   gamma:Gamma value. Used when an encoding-gamma is needed. Default is 2.2*.
-  tone: For HDR images. Tone-map exposure applied if this is >= 0.0. A value
-        of 0.0 is black. A value of 4.0 is over-exposed. Negative means do
-        not apply tone-map exposure function. Default is -1.0*. Non-negative
-        valid range is [0.0,4.0]
+  tone: For HDR images. Tone-map exposure applied if this is >= 0.0. The
+        non-negative valid range is [0.0,4.0]. A value of 0.0 is black and 4.0
+		is over-exposed. A value of 1.0 is neutral. Negative values do not
+        apply tone-map exposure. Default is -1.0* for no application.
   spred:Spread single channel. Boolean true* or false. For KTX files with a
         single Red or Luminance componentconly, spread it to all the RGB
         channels if set to true. If false the red channel takes the value.

docs/cli.md

@@ -17,20 +17,26 @@ tacentview.exe -c
 This is the simplest conversion command-line. The `-c` (alternatively `--cli`) simply means do not launch the GUI. The input images are all the files in the current directory (since no directory was specified). By default all image types are processed unless you specify the input image types with `-i` or `--in`. Similarly, output types can be specified with `-o` or `--out`. If this is missing the default is to output TGA files.\
 \
 \
+**Example {% increment egnum %} - Convert Single JPG to TGA**
+```
+tacentview.exe -c TactileConceptDevelopment.jpeg
+```
+This example shows why the `-c` option is needed -- without it GUI-mode is activated and the images on the command-line are opened in the full graphical user interface. Note that some input types have multiple valid extensions. e.g. A JPeg may have `jpg` or `jpeg` extensions and a Tiff may have `tif` or `tiff`.\
+\
+\
 **Example {% increment egnum %} - Convert PKM Files to PNG**
 ```
 tacentview -c --in pkm --out png
 ```
-Similar to Example 1 except the type of the input and output files is specified explicitly. Since the `exe` extension is optional when using the command prompt, it has been removed from subsequent examples. Additionally, the executable in Linux will not have this extension.\
+Here the types of the input and output files is specified explicitly. Since the `exe` extension is optional when using the command prompt, it has been removed from subsequent examples. Additionally, the executable in Linux will not have this extension.\
 \
 \
 **Example {% increment egnum %} - Convert PKM and JPG Files to PNG and BMP**
 ```
 tacentview -c --in pkm,jpg --out png,bmp
 tacentview -c --in pkm -i jpg -o png --out bmp
 ```
-You can specify multiple types for both the input and output. Both command-lines above do the same thing. In the first more concise example, all types are specified with a single `--in` or `--out` option. The second just shows that individual specifications get combined.
-\
+You can specify multiple types for both the input and output. Both command-lines above do the same thing. In the first more concise example, all types are specified with a single `--in` or `--out` option. When using this comma-separated list format, do not put spaces after the commas. The second just shows that individual specifications get combined.\
 \
 \
 **Example {% increment egnum %} - Create GIFs from Manifest**
@@ -49,6 +55,27 @@ MoreImages/
 The `--outGIF` is optional and specifies any non-default parameters for creating the GIFs. In this case a 2-bit (4 colour) palette is used, the _neu_ algorithm is used for colour quantization, and the transparency threshold is 120. There are more options for GIF output not shown here including things like loop behaviour, frame duration, etc.\
 \
 \
+**Example {% increment egnum %} - Adjust EXR Exposure and Save to TGA**
+```
+tacentview -c --in exr --inEXR gamma=1.8,expo=3.5
+```
+Many image formats have additional load parameters that may be specified. In this example EXR files are loaded with a gamma-correction of 1.8 (default is 2.2) and an exposure value of 3.5. Exposure ranges from -10.0 to 10.0 with the neutral default being 1.0. For EXR files additional load parameters, not shown here, include defogging (`defog`), and adjusting _knee_ values (white and middle points) using knee-low (`knelo`), and knee-high (`knehi`).\
+\
+\
+**Example {% increment egnum %} - Convert JPG to TGA Respecting EFIF Orientation**
+```
+tacentview -c --in jpg --inJPG strct=true,exifo=true
+```
+Some JPG files have meta-data that indicates, among other things, what orientation the camera was when the picture was taken. By specifying `exifo=true` we can undo this orientation automatically for JPG files. The resultant TGA will always be oriented correctly when we do this. The default is to not take the EFIX orientation into account. The `strct=true` load parameter means that any input JPG files must be well-defined and _strictly_ meet the JPeg specification. Setting this to false allows some non-conformant images to still be loaded.\
+\
+\
+**Example {% increment egnum %} - Convert DDS to TGA Specifying Load Parameters**
+```
+tacentview -c --inDDS corr=gamc,gamma=1.8,tone=2.1,spred=F,strct=T ImgA.dds ImgB.dds
+```
+This example shows loading two DDS files (`ImgA.dds` and `ImgB.dds`) setting all the supported input parameters. The `corr` parameter specifies the gamma-correction mode, the `gamma` parameter specifies 1.8 to be used for the correction gamma (default is 2.2). Assuming the dds files are encoded with an HDR format like BC6s or one of the ASTC encodings, the `tone` parameter controls the exposure. The value of 2.1 pushes the exposure higher (brighter). The spread (`spred`) parameter applies to single-colour-channel DDS files. It means do not spread that channel to the other colour channels. Finally, `strct=T` means do not load DDS files that have errors or inconsistencies in their header -- the default is false which is a bit more forgiving for some DDS files found in the wild. Since no `--out` types were specified, TGA files will be generated from the two input DDS files.\
+\
+\
 **Example {% increment egnum %} - Resize Images Preserving Aspect**
 ```
 tacentview -cw . --op resize[1920,-1] -o jpg
@@ -138,7 +165,7 @@ tacentview -c --op rotate[12,resize,bilinear,none]
 Rotates 12 degrees anti-clockwise. Resize mode does the same as crop mode but then resizes the image back to the original dimensions. Useful for rotating horizons in photos where you don't want to use a fill and want the final image size to be the same. Using `none` for the down-filter uses a custom down-sample method that keeps edges sharper.\
 \
 \
-**Example {% increment egnum %} - Levels All Channels**
+**Example {% increment egnum %} - Adjust Levels**
 ```
 tacentview -c --op levels[0.1,*,0.9,*,*]
 ```
@@ -149,7 +176,7 @@ Adjusts image levels in a manner similar to other photo-editing software where y
 ```
 tacentview -c --op levels[0.2,0.6,0.8,0.1,0.9,4,R,false]
 ```
-Adjusts image levels like _Example 16_ except we specify all five black and white points explicitly. The 4 is the zero-based frame number to operate on if you have an animated or multi-page input image. If this is set to -1 or * it adjusts levels on all frames. The `R` means the red channel only. Choices are R, G, B, RGB (the default), and A. The last argument lets you specify a continuous or discontinuous function for the mid-point gamma algorithm. False means discontinuous at gamma 1 (approximates Photoshop). True means use a continuous base-10 power curve that smoothly transitions the full range (similar to the GIMP).\
+Adjusts image levels like the previous example except we specify all five black and white points explicitly. The 4 is the zero-based frame number to operate on if you have an animated or multi-page input image. If this is set to -1 or * it adjusts levels on all frames. The `R` means the red channel only. Choices are R, G, B, RGB (the default), and A. The last argument lets you specify a continuous or discontinuous function for the mid-point gamma algorithm. False means discontinuous at gamma 1 (approximates Photoshop). True means use a continuous base-10 power curve that smoothly transitions the full range (similar to the GIMP).\
 \
 \
 **Example {% increment egnum %} - Contrast**
@@ -205,7 +232,7 @@ Blends a grey-blue backgraound into the RGB components of the input images. Each
 ```
 tacentview -ca --op channel[spread,G]
 ```
-Spreads (copies) the green (G) channel of each pixel into the red and blue channels. Spread always taks in a single channel and spreads it to the RGB channels of the image.\
+Spreads (copies) the green (G) channel of each pixel into the red and blue channels. Spread always takes in a single channel and spreads it to the RGB channels of the image.\
 \
 \
 **Example {% increment egnum %} - Set Channels to Intensity**