Command line interface

The command line enables a user a more automatic-labor approach which is useful when one, let’s say, have a folder piled with images and a script (dos batch, python, choose your favorite scripting style…) that iterates the files, you can use the command line interface to interact with the app w/o actually doing any mouse/keyboard manual labor.
You can also use it to customize a flavor like opening images in compare mode or delegate a static crop region and so on…
One extra advantage is the lower memory footprint of the app as there’s an option to work completely off the GUI flow, enabling to omit the overhead of display canvases. For large scale images, this might prove the dead-or-alive difference.

Arguments are in affect from left to right (1, 2, 3, …) and every opened / created image is assigned with a HK id as if it was done from the app GUI.
The only exceptional argument is the file name which can be entered in a sequence but from the first encountered argument that uses a switch (-,– hyphen) and that isn’t part of the open image ‘specific’ switches (see -op), you must use also the -op (–open) switch to open following files.
e.g. RawImageAnalyser red1.jpg blue2.png pink3.8b.raw -cmp –open white4.422.yuv
This will load from local path the 3 first images and will start the app directly in compare mode (of the first 3 assuming they share dimensions and can be opened) and will also open a 4th image (use HK 4 to switch to it).

If you have input that comes with spaces (like windows folder or complex expressions), remember to surround them with double quotation mark (“i have spaces”) in order for them to count as single argument (same goes when using the –batch_file switch).

Syntax: RawImageAnalyser [<file path>, [<-wh> <size>] [<-fmt> <string>]], …,
[-<h|op|bt|ff|cf|n|d|cmp|flt|roi|s|sst|spng|cnv|e|cls|q> <secondary options>]

Note about secondary options that allow to supply image HK number. If non given, the last (most recent) opened image will be used else supply a HK from 1..N. You can also give reverse numbering so -1 is like stating the last image (e.g. -3 is the 3rd last).

The -q (–quit) switch has a special underlying meaning which states that the user wishes to perform all actions but exit the app afterwards w/o ever entering its GUI state. This is effective in batch processing when one desires, for an example, to use the app as some sort of RAW image processing utility. Take note that if -q isn’t used, all app dialogs are in affect which includes any multi-thread progress control.

Command	Alias	Short description
-h	–help	Outputs to the console short / long help info
-op	–open	Opens an image file
-bt	–batch_file	Process all commands from a batch file
-ff	–fmt_file	Load a specific RAW format file
-cf	–cfg_file	Load a specific app config file
-n	–new	Creates a new image duplicate (full or ROI)
-d	–diff	Performs a difference between 2 images
-cmp	–compare	Enter compare mode by supplied images
-flt	–filter	Performs a filter on an image
-roi	–reg_of_interest	Sets a ROI selection
-s	–save	Saves as RAW image
-sst	–save_stat	Saves an image statistical info + histogram (text)
-spng	–save_png	Saves an image as PNG RGB-8 file
-cnv	–convert	Converts an image into a new RAW image
-e	–ieval	Performs an I-Eval on a given expression
-cls	–close	Closes up to 8 given images or all
-q	–exit –quit	Silent mode, no GUI. Quits after batch processing

Switches:

[-h|–help]

Outputs to stdout (console) a basic command line layout (-h) or this full user manual.
The app will not enter the GUI and leave after displaying the help text.

[-op|–open] <image path> [<-dims|-wh> <width x height>] [<-fmt|-format_str|-expr_str> <string>]

Opens an image file. If the file path carries a known extension (like JPG), it will be loaded (assuming parse-able) into the app else it’s assumed to be a RAW image and if a match will be found in the RAW formats file it will be loaded else a dialog of “Open Raw Image” will pop-up (assuming –quit wasn’t invoked, see its switch description) and allow a user entered format. As noted previously, you can also simply open a file by entering the first arguments supplying an explicit path w/o using any hyphen (-,–) switch until first usage of any command switch.
Use double-quotes if you have spaces in the file path.
Extra control options:
-dims, -wh <width x height>

Force the RAW image’s dimensions (w/o qualifying for some reg-ex match). You should supply the size in the form width x height (e.g. 640×480).

-fmt, -format_str, -expr_str <string>

Force the RAW image’s format to be the specified string. See Format’s file manual for full syntax.
Note that all extra control options are optional so if omitted, the format’s loader will try to match a missing datum via the reg-ex engine. If non found, the open image action will fail (full abort of the arguments parsing and application’s exit).

[-bt|–batch_file] <batch file path>

Must be entered as first argument in order to be used. Very useful when you need to use a long batch processing and the command line isn’t long enough or comfort. If this command is invoked, all extra switches are ignored and all actions are performed from the input file (which is practically, unlimited). One other advantage of this, is its ability to accept comment lines (signed with # at start of line).

[-ff|–fmt_file] <format file path>

Allows an explicit loading of a RAW format loader file. After loaded, it will replace any currently active format file. This can be handy in case you wish to invoke a file which is specific to some folder(s) or has some regex rules which conflict with your regular format file.

[-cf|–cfg_file] <configuration file path>

Allows overriding the default config file. Again, useful when one requires a different flavor of the app settings in certain scenarios like specific work path or comparison limit and so on. See Config file for further info.

[-n|–new] <use_roi|image HK>

Creates a new image duplicate either from a full size image or, if ROI was selected, you can choose to make a new image from the active ROI (add the use_roi command).
If you don’t supply arguments after the -n (or –new) then the last opened image is used i.e. with highest HK number. If you supply some HK number, then it’s the one that will be used.,

Performs a difference between 2 images by a given diff type (default is all_bin).
You can use acronym like type1 through type4 instead of supplying the long names. You must supply 2 distinct HK (else the last 2 opened will be used). A new image is created as an after effect (with HK ‘old max’+1).

[-cmp|–compare] <image1 HK, image2 HK, …>

Moves the app into comparison mode. This one affects only the GUI state of the app or special commands like I-Eval that are aware of the comparison party.
If no image HK will be supplied, the last opened image will be taken as anchor and the app will try to layout a comparison party of all other images that share its dimensions (given they don’t exceed the comparison party limit).

[-flt|–filter] <image HK> <all_comp_qlfy> <sep_comp> [<filter_expr|fexpr> <string>] [<neg_expr|nexpr> <string>]

Performs a filter on an image.
Extra control options:
all_comp_qlfy

Pixel is valid if all 3 components are in range.

sep_comp

Separate to image per component.

filter_expr, fexpr <string>

See guidelines in Filter user dialog.

neg_expr, nexpr <string>

See guidelines in Filter user dialog.
Note that if you wish to filter w/o affecting the original image, perform something like -n (–new) and then don’t supply an image HK when filtering. Also, filtering is always performed on the currently active ROI if exists.

[-roi|–reg_of_interest] <image HK> <[minX,minY..maxX,maxY]|[minX,minY..Width x Height]>

Activates a ROI selection on some image given a rectangular region of interest by either giving a start and end point / image coordinate (e.g. 20,30..22,40) or a start point and size (e.g. 20,30,3×11).

Saves a RAW image (default is binary with original packing and x86 little-endian).
Extra control options:
text

Save the data into a text file (pixel value), depending on the layout format (planner, interleave, etc.).

hex_text

Save the data into a text file by writing a hexa layout of the data as in common hex-viewers (refer to [Developer] section for other writing format options).

plnr, planner

Force the output packing type to be planner.

intrlv, interleave

Force the output packing type to be interleave.

be, big_end

Force the output byte-order to follow Big-Endianness rules (like Apple’s native layout).

ovr, overwrite_exist

Force an overwriting of the input if exist w/o prompting. If in GUI mode, a dialog will pop-up if the file exists else the operation will simply fail.
Use this to avoid any sort of output validation.

name <path>

You can force an output name even if in auto-naming state. This gives better flexibility when working with batch processing.

[-sst|–save_stat] <image HK> <ovr|overwrite_exist> [name <path>]

Saves an image statistical info (+histogram) into a file.
The extra control options follow -s rules.

[-spng|–save_png] <image HK> <ovr|overwrite_exist> [name <path>]

Saves (exports) an image to a PNG (RGB 8bpp) file.
The extra control options follow -sst rules.

[-cnv|–convert] <image HK> [<fmt_expr|format_str|fmt> <string>] <use_def_trans> [col_trans <c1, …, c2>] [resize <width expr;height expr{;ofs x;ofs y}>] <resize_tiled>

Converts an image into a new RAW image.
Extra control options:
fmt_expr, format_str, fmt <string>

Specifies the raw format expression (e.g. P,Y,-16 or I,RGB,8) as noted in the formats file manual.

use_def_trans

Forces the color transform (if required) to use the app’s system default no matter what is defined in the configuration file.

col_trans

Supply a custom color transformation matrix (4×3) for the conversion to use.
Please note that the color transform will be in affect only if the destination format has a different color space notation, otherwise this value is ignored.
If not supplied, the used transformation will be the one noted in the configuration file (else the app’s system default is used). This option is mutually exclusive to ‘use_def_trans’.

[-e|–ieval] <image HK> [ieval_expr <string>] <oor <string>> <out_ovrd <string>> <in_roi> <out_ch_ctx_yuv|out_ch_single> <bpp8|bpp16|bpp32>

Performs an I-Eval on ‘ieval_expr’ string. You can assume the saved I-Eval list is loaded so you can use any form of an I-Eval (as if it was entered directly via the dialog).
The default activation is with out-of-range as 0, entire image is applied, creates a new image, output channel by context (RGB layout) and BPP is also by context.
Note that the I-Eval engine is aware of any active comparison party but still, if you enter a ‘image HK’ it takes precedence (and disables any currently active comparison party on forth).
Extra control options:
oor <string>

Sets an out-of-range value string. See I-Eval rules for the respected dialog item.

out_ovrd <string>

Sets an output override list string. See I-Eval rules for the respected dialog item.

in_roi

If there’s an active ROI, will apply the I-Eval only in it.

out_ch_ctx_yuv, out_ch_single

Controls the output channels while ‘out_ch_ctx_yuv’ will set the channels by context but with YUV layout (if of 3 channels type) and ‘out_ch_single’ forces a single channel output.
Please refer to I-Eval manual for further clarifications.

bpp8, bpp16, bpp32

Suppresses the default selection by context of BPP and sets one the above values.

[-cls|–close] <image1 HK, image2 HK, …> <all>

Closes up to 8 given images or all (if ‘all’ is specified). Useful if you finish some batch processing phase and you wish to free some HK slot or reset a new commands set.

[-q|–exit|–quit]

Whenever encountered in the argument’s list (or the batch file commands), will signal the application to work in no-GUI mode so after the arguments are parsed and performed, the application will return to the command prompt.
Also, this means all errors or app’s output will be directed only to stdout / stderr.
To avoid misunderstanding, if the app logs are active from the config file, they will still be used (orthogonal behavior).

Several usage examples

Note we assume all input images are open-able by the app (either a common image format or parse-able by the format’s file).

Example 1

We assume we have a batch processing listed in file ria_batch_cmd1.txt so the command argument is:
RawImageAnalyser –batch_file ria_batch_cmd1.txt

We wish to take a disproportional input raw image (format yuv-422) and rotate it so the width will be bigger than the height and save it to a RGB-8 file with planner BGR packing.
The batch file listing is (note that comments are prefixed with #):

    "D:\Test Images\image_input_x496_y640_422.yuv"
    # Convert and resize the most recently opened image (HK 1)
    -cnv fmt p,b,g,r,8 resize "max(w,h); max(w,h)"
    # Use the I-Eval to mirror the image
    -e ieval_expr i[y,x]
    # Save it to some self defined name (overwrite if exists)
    -s ovr name yuv_trans.640x496.bgr.p.raw
    # Avoid any GUI (batch processing only)
    -q

Example 2

We wish to smart difference 2 luma images by only considering a diff if values that are higher than 128 have delta of less than 5 and take this diff image and make it gray scale so each difference level will be quite noticeable and save it to a Y8 file.
We assume we have a batch file ria_batch_cmd2.txt and here is its listing:

    luma_in1_100x90.raw luma_in2_100x90.raw
    # Use I-Eval to express the noted semantics
    --ieval ieval_expr "(i1 > 128 && i2 > 128)*(abs(i2-i1) < 5)*(1+(abs(i2-i1)))*255/5"
    -s name diff_luma_in1_2_gray.100x90.raw
    -q

Example 3

We wish to take a known portion of our image (let’s say our face) at <80,100> with size 100×100 and make a pseudo-passport out of it (4×4) while dimming the image a bit (20%) but only the actual data (luminance, not the colors).
We assume the image input is RGB8 (in jpeg) and that we have ria_batch_cmd3.txt so its listing will be:

    
    # Let's assume the size is 400x300 or so...
    my_passport_img.jpg
    # Mark the face ROI
    -roi 80,100,100x100
    # Create a new image consisting only of the face
    -n use_roi
    # Convert to YUV while resizing to our final "passport" output
    --convert fmt i,yuv,8 resize w*4;h*4 resize_tiled
    # Dimmer the luminance only  
    -e ieval_expr "c1*0.8; c2; c3" out_ch_ctx_yuv
    # Export to PNG (we're getting a back to RGB conversion for free).
    # Note you can play with the default color transformations if you don't like the 
    # way it looks...
    --save_png name my_passport_img.png 
    # Leave us in GUI state so we can monitor more closely the results