parameters - Documentation

factory parameters

Setter parameters for commands.

General mechanism
Available commands
- grab Grabs an image from a source device.
- load Loads an image from a source file.
- save Saves an image in files.
- cache Caches an image in memory.
- copy Copies an image from a source image.
- crop Crops a rectangle image from a source image.
- rectify Crops a quadrilateral from a source image.
- intensity Calculates image intensity statistics.
- histogram Calculates image histograms.
- similarity Computes the similarity with respect to a source image.
- balance Balances the image intensity.
- median Smooths the image intensity.
- fovea Defines a foveal mask of transparency to limit image border influence.
- resize Resizes an image.
- bgr Converts the Blue-Green-Red input in float format.
- hsv Computes the Hue-Saturation-Value input in float format.
- smooth Smooths the input using an exponential filter in float format.
- edge Computes the image edges in float format.
- subtract Subtracts a background from this image.
- blob Thresholds a colored blob in this image.
- segment Segments and parse blobs in this image.
- match Matches the image against source·s images.
- draw Draws elements on a copy of this image input.
- show Displays channel·s in popup window·s.
Caution about bug and caveat

General mechanism

Each command is defined by:
- A name given in the do field.
- A set of input parameters, stored in the Image parameters under the command name on output.

Remarks:

Each command is designed to be applied once on an Image, otherwise image copied is to advised.
Other mechanisms can be implemented via the Setter hook.

Available commands

[grab] { do: grad device: $device-index } or $device-index.
- Grabs a RGB image from an input device.
- Input parameter:
  - The device index, it can simply be given as a string, without JSON construct.
    - 0,1,2,3 corresponds to the /dev/video$device-number device.
    - 4 On a RPi, it corresponds to the 1280x960 resolution PiCamera.
    - 5 On a RPi, it corresponds to the full-resolution PiCamera using the raspistill utility.
  - clear: if not false image channels and parameters are beforehand cleared.
- Output channel: The raw input image, in CV_8UC3 format.
- Output parameters: Image width and height.
[load] { do: load file: $image-file-name } or $image-file-name.
- Loads a RGB image from, e.g. a .png or other standard file format.
- Input parameter:
  - The file name, it can simply be given without JSON construct.
  - If the alpha: true option is present, an alpha transparency CV_8UC1 channel is added, in any case.
  - clear: if not false image channels and parameters are beforehand cleared.
- Output channel: The raw input image, in CV_8UC3 format.
  - If transparency is present, a separate alpha transparency CV_32SC1 channel is loaded, unless setting alpha: false.
- Output parameters: Image width and height.
[save] { do: save path: $image-files-directory }.
- Saves all image channels and parameters in the target directory path.
- Input parameter:
  - The path, files directory where to store the images.
- Output: A path directory with
  - All cv::Mat images stored under their name.
    - Pixel images (i.e., 3 channels CV_8U image) are stored as .png image.
    - The alpha channel is stored in a distinct CV_8C1 .png image.
    - Index images (i.e., 1 channel CV_32S image) are stored as floating point .exr images.
    - Floating point numeric images (i.e., CV_32F images) are stored as either 1 or 3 channel·s .exr images.
  - The path/parameters.json file contains all parameters
    - Including channels listing each cv::Mat data structure channel parameters.
[cache] { do: cache name: ... what: (get|put|del[ete])}.
- Stores this image in a cache in order to use it as a source for other image processing.
- Input parameter:
  - The unique name of the image image in the cache.
  - Defines what is to be done:
    - put: to put an image into the cache (default if the image name is undefined).
      - If an image is previously defined, it is erased by this operation.
    - get: to copy an image from the cache into this image (default if the image name is defined).
      - clear: if not false image channels and parameters are beforehand cleared.
    - del or delete: to delete an image which is in the cache.
- Output channels: When get, all channels defined in the cache image.
- Output parameters: When get, the cache image parameters.
[copy] { do: copy }.
- Copies all channels of the source image into this image.
  - The source image defined either:
    - Using the set(JSON parameters, const Image& source) 2nd argument.
    - Or defining a { do: copy source: name} parameter, getting the image from the cache by its name.
  - This is the default operation if no parameter is given.
- Input parameter:
  - clear: if not false image channels and parameters are beforehand cleared.
- Input channels: The source channels.
- Output channels: All channels defined in the source image.
- Output parameters: The source image parameters.
[crop] { do: crop, top: ..., right: ..., bottom: ..., left: ...}
- Crops a rectangular part of the source image into this target image.
- Input channel: The source raw input image, in CV_8UC3 format.
  - The source image defined either by the set() 2nd argument or using a source parameter, as for {do: copy ....
- Input parameters:
  - clear: if not false image channels and parameters are beforehand cleared.
  - top: Crop rectangle top vertical position, default is 0.
  - right: Crop rectangle right horizontal position, default is image.width-1.
  - bottom: Crop rectangle bottom vertical position, default is image.height-1.
  - left: Crop rectangle left horizontal position, default is 0.
- Output channel: The raw input image, in CV_8UC3 format.
[rectify] { do: rectify, top_x: ..., top_y: ..., ...}
- Crops a quadrilateral of the source image into this target image, applying a perspective transform.
- Input channel: The source raw input image, in CV_8UC3 format.
  - The source image defined either by the set() 2nd argument or using a source parameter, as for {do: copy ....
- Input parameters:
  - clear: if not false image channels and parameters are beforehand cleared.
  - top_x: The crop top horizontal position, in pixel, default is 0.
  - top_y: The crop top vertical position, in pixel, default is 0.
  - right_x: The crop right horizontal position, in pixel, default is image.width-1.
  - right_y: The crop right vertical position, in pixel, default is 0.
  - bottom_x: The crop top horizontal position, in pixel, default is image.width-1.
  - bottom_y: The crop top vertical position, in pixel, default is image.height-1.
  - left_x: The crop top horizontal position, in pixel, default is 0.
  - left_y: The crop top vertical position, in pixel, default is image.height-1.
  - width: The final image width, default is the image width.
  - height: The final image height, default, default is the image height, or the width if specified.
- Output channel: The raw input image, in CV_8UC3 format.
[intensity]
- Calculates image intensity basic statistics, all blue, green and red values together
- Output parameters: basic intensity statistical values:
  - median (image BGR intensity median intensity)
  - lower-quartile
  - upper-quartile
  - minimum
  - maximum
  - mode
  - mode-count (number of pixels with the mode value)
  - mean
  - stdev (standard-deviation)
  - entropy (intensity histogram entropy, between 0 and 8 bits for the 256 values)
  - bin-count (optimla histogram bin count according to Scott rule.
[histogram]
- Calculates image channel histograms:
- Input parameters:
  - what: a sequence of unordered letter (default is all).
    - B: for the blue channel.
    - G: for the green channel.
    - R: for the red channel.
    - H: for the hue channel.
    - T: for the tint channel histogram, i.e. the hue channel weighted by the saturation.
    - S: for the saturation channel.
    - V: for the value channel.
    - C: for the contrast, i.e., the edge magnitude channel.
    - O: for the orientation, i.e., the edge orientation channel.
  - window: 1D smoothing window to avoid "sparse" histogram, default is none.
  - proba: If true, normalizes in order the sum of the values to be equal to 1.
  - median: If true, calculates the histogram median value in target.get().["histogram"][what]["median"] where what is the choosen channel.
    - The bin of value 0 is not taken into account, to avoid low value masking.
    - If a circular value is considered (i.e., an angle), this value is biased.
  - mode: If true, calculates the histogram mode value in target.get().["histogram"][what]["mode"] where what is the choosen channel.
    - The bin of value 0 is not taken into account, to avoid low value masking.
  - smooth: 1D histogram smoothing window to smooth histograms, default is 0 (no smoothing).
    - The bin of value 0 is not smoothed, to avoid low value masking.
    - For circular value, circular recursive smoothing is applied.
  - draw: either lin or log to draw the histogram with a linear or logarithmic scale (it applies only to the plot, the histogram remains unchanged).
    - blue: The blue channel.
    - green: The green channel.
    - red: The red channel.
    - magenta: The hue channel.
    - pink: The tint channel.
    - yellow: The saturation channel.
    - white: The value channel.
    - gray: The edge amplitude channel.
    - cyan: The edge orientation channel.
- Output channels:
  - The histogram-$letter where $letter stands for the channel letter B, R, G, H, S, V, C, O with the histogram as a, in CV_32FC1 format.
  - The histogram-$letter-view the histogram plots as an image, in CV_8UC3 format, if draw is defined.
[similarity] {do: similarity similarity: correlation ...
- Calculates the similirity with respect to the source image
- Input channels:
  - This image channels, depending on the metric.
  - The source image defined either by the set() 2nd argument or using a source parameter, as for {do: copy ....
  - The alpha channel if present in the source image is used as a weighting.
  - Input image pixel value at 255 are not taken into account (they are either saturated values or border values).
- Input parameters:
  - similarity: the choosen similarity estimation
    - correlation: Uses the normalized correlation between the two images intensities. Returns a value in [0, 4], 0 if entirely correlated, 2 if uncorrelated, 4 if entirely anti-correlated.
    - Other metric can be implemented via the Metric hook.
- Output parameters:
  - value: The similarity value, a non-negative value, equal to 0 if similarity is maximal.
[balance] { do: balance, saturation: ... }
- Balances the image intensity with respect to white.
- Input parameters:
  - balance: Method, either simple (default) or grayworld (or learned), as defined in opencv.
  - saturation:
    - simple case: Percent of top/bottom values to ignore, default is 2.
    - grayworld or learned case: Maximum saturation for a pixel to be included in the gray-world assumption, default is 0.9.
  - equalize: If true performs an BGR histogram equalization after balance.
- Input/Output channel: The input image with white balance performed.
[median] {do: smooth window: ...}
- Computes a smoothed version of this image using a median filter.
- Input parameters:
  - window The smoothing filter window size in pixel, typically 3 (default), 5 or 7.
- Input/Output channel: The input image with median filtered performed.
[fovea] { do: fovea, }
Defines a foveal mask of transparency to limit image border influence.
Implements a fixed quadratic separable profile.
Input/Output channel: The alpha transparency CV_8UC1 channel, modulated in existant, created otherwise.
[resize] { do: resize, width: ..., height: ... }
- Resizes all channel of this image to the given sizes, or to the source image sizes (without copying the source image).
- Input parameters:
  - width: Image width, default is the source image width if any, else unchanged.
  - height: Image height, default is the source image height if any, else unchanged
- Output parameters: The new width and height.
- Input/Output channel: All image channels at the new size.
[bgr] { do: bgr } or bgr.
- Computes the image as a CV_32FC3 3 channels float.
- Input channel: The input raw image in CV_8UC3 format.
- Output channel: A raw bgr blue-green-red image, in CV_32FC3 format, with values in [0, 1].
[hsv] { do: hsv } or hsv.
- Computes the image RGB->HSV color conversion, as a CV_32FC3 3 channels float.
  - The hue angular value stands between 0deg and 360deg
  - The saturation relative value stands between 0 and 1
  - The (maximal intensity) value stands between 0 and 1
- Input channel: The bgr blue-green-red image, in CV_32FC3 format.
- Output channel: A raw hsv hue-saturation-value image, in CV_32FC3 format.
[smooth] {do: smooth window: ...}
- Computes a smoothed version of this image using a 1st order exponential recursive filter, as a CV_32FC3 3 BGR channels float.
- Input channel: The bgr blue-green-red image, in CV_32FC3 format.
- Input parameters:
  - window: The smoothing filter window size in pixel, with 90% of the signal to be in a the pixel window.
- Output channel: A smooth blue-green-red image, in CV_32FC3 format.
[edge] {do: edge window: ...}
- Computes a the local edge characteristics.
  - Magnitude: the edge magnitude, from 0 to 255, in pixel value.
  - Orientation: the edge orientation, from 0 to 360 degree.
- It is based on the local intensity derivative SVD we obtain the color edge eigen elements, using a smoothed image.
- Input channel: The smooth blue-green-red image, in CV_32FC3 format.
- Input parameters:
  - window The smoothing filter window size in pixel, with 90% of the signal to be in a the pixel window.
- Output channel: A edge intensity-orientation image, in CV_32FC2 format, the 3rd channel not being used.
[subtract] { do: subtract, threshold: ..., slope: ...}
- Background thresholds this image, considering the source image as background.
- Input channel:
  - The source raw input image, in CV_8UC3 format.
  - The source image defined either by the set() 2nd argument or using a source parameter, as for {do: copy ....
- Input parameters:
  - threshold: The intensity threshold above which it is not in the background, default is 50.
  - mode: The threshold mechanism:
    - step: To set to zero values below a given BGR threshold (default).
    - weak: To progressively reduce the intensity below a given BGR threshold.
- Input/Output channels:
  - The input image with the multiplicative subtraction done, in CV_8UC3 format.
  - The substract image with a copy of the input image before substraction, in CV_8UC3 format.
[blob] {do: blob blue: ... green: ... red: ... ... }
- Detects color blobs in the image.
- The HSV color conversion is considered:
- The pixel hue, intensity and color saturation are taken into account.
- The method is derived from here and there.
- Input channel: The raw hsv hue-saturation-value image, in CV_32FC3 format.
- Input parameters:
  - name: The channel name for subsequent invocation to this blob.
  - blue: The blob median blue color, between 0 and 255, default is 128.
  - green: The blob median green color, between 0 and 255, default is 128.
  - red: The blob median red color, between 0 and 255, default is 128.
  - hue_threshold: The color hue threshold, in degree, in [0deg, 180deg], values in [hue_blob - hue_threshold, hue_blob + hue_threshold] are considered, default is 10deg.
  - saturation_threshold: The color saturation minimal value, in percentage, values between [saturation_threshold, 100%] are considered, default is 0%.
  - value_threshold: The intensity minimal value, values between [intensity_threshold, 255] are considered, default is 0.
- Output channel: A blob integer mask as a CV_32SC1 image with:
  - 1: for blob pixel value,
  - 0: for non-blob pixel value.
[segment] {do: segment input:... ... }
- Input channel: An integer mask as a CV_32SC1 image.
- Input parameters:
  - input: The input mask channel, segments image blobs according to the blog_threshold or background_threshold input channel CV_32S1 integer channel information.
    - Adjacent pixel of the same region have the same non-negative value in the mask.
    - Negative values corresponds to unlabeled pixels to be included in the closest indexed region.
  - size_threshold: The minimal pixel count of a blob, default is 100.
  - draw: If defined draw the blobs on a output BGR image, specifying what is to be drawn, any bitwise combination of:
  - 0x01: Draws the "name" (or "index" if "name" is undefined) as a text around the blob center ("x", "y").
  - 0x02: Draws a '+' cross on the blob center ("x", "y") with a length related to the "size".
  - 0x04: Draws a rectangle from the blob "top", "right", "bottom", "left", border.
  - 0x08: Draws an ellipse of center ("x", "y"), angle "a", and axes length ("L", "l")
  - 0x10: Draws the pixels corresponding to the blob, using the blob average intensity.
  - 0x20: Draws the pixels corresponding to the blob, using a gray color.
- Output parameters: In segment/blobs, a list of blobs, in size decreasing order, each blob defined by:
  - index: The blob index, form 0 number of pixels.
  - size: The blob number of pixels.
  - x: The blob horizontal median position, in pixel.
  - y: The blob vertical median position, in pixel.
  - a: The blob main orientation, in degree.
  - L: The blob 2nd larger axis length.
  - l: The blob 2nd smaller axis length.
  - e: The blob thinness, from 0% if circular to 100% if filiform.
  - top: The blob top minimal vertical position, in pixel.
  - right: The blob right maximal horizontal position, in pixel.
  - bottom: The blob bottom maximal vertical position, in pixel.
  - left: The blob left minimal horizontal position, in pixel.
  - blue: The average blob intensity blue value.
  - green: The average blob intensity green value.
  - red: The average blob intensity red value.
- Output channels:
  - segment: Generates a CV_32SC1 integer index map with a non-negative index to label each detected region.
  - output: Generates a CV_8UC2 image with the blobs drawn if the input parameter is defined.
- Algorithm details:
  - Segments an image according to a standard colorization algorithm.
  - Adjacent pixels in 8-connectivity (horizontal or vertical, and oblique) belongs to the same region.
[match] {do: match transform: [{ ../..}], source: ..}
- Matches the source image·s with this image optimizing the given transform with respect to normalized correlation.
- Input channels:
  - This image "input" channel.
  - The source image defined either by the set() 2nd argument or using a source parameter, as for {do: copy ....
- Input parameters:
  - parameters: The parameters sequence, a numeric structure of the form:

[
  {
    translation_i: { eps: 1    min: -width  max: width  step: 20 unit: pixel  }
    translation_j: { eps: 1    min: -height max: height step: 20 unit: pixel  }
    rotation:      { eps: 0.01 min: -10     max: 10     unit: radian }
    zoom:          { eps: 0.01 min: 0.1     max: 10 zero: 1 }
    warp:          { eps: 0.01 min: -10     max: 10 }
    twist:         { eps: 0.01 min: -10     max: 10 }
  }
  // Other multi-scale mapping process
]

Output parameters:
- similarity: the best obtained similarity.
- transform: the best transform parameters: translation: [t_x, t_y] in pixel, rotation: in linearized radian, zoom: in image ratio (1 if no zoom), warp and twist.
- results: The input parameters adjusted after matching.
[draw] { do: draw, what: ... }
- Draws 2D elements on a copy of the input image.
- Input channel: The source raw input image, in CV_8UC3 format.
- Input parameters:
  - what: A list of 2D elements of the form:
    - {do: text x:... y:... text:... color:...} for a text text at a given position (x,y).
    - {do: cross x:... y:... l:... color:...} for a + cross at (x,y) and of length l.
    - {do: line x1:... y1:... x2:... y2:... color:...} for a line segment between (x1,y1) and (x2,y2).
    - {do: rectangle left:... top:... right:... bottom:... color:...} for a rectangle.
    - {do: quadrilateral top_x:... top_y:... right_x:... right_y:... bottom_x:... bottom_y:... left_x:... left_y:... color:...} for a rectangle.
    - {do: circle x:... y:... r:... color:...} for a circle of center (x,y) and radius r.
    - {do: ellipse x:... y:... a:... l:... L:... color:...} for an ellipse of center (x,y) angle a in degree and axes length L, l.
  - For compatibility reason crop is a synonym of rectangle and rectify is a synonym of quadrilateral.
  - The color is given as a [w0rgbycm] char for ([w]hite, [0]black, [r]ed, [g]reen, [b]lue, [y]ellow, [c]yan, [m]agenta) color.
- Output channel: The draw image with the input image and the drawings.
[show] { do: show, name: ... channel: ... }
- Displays channel·s in popup window·s.
- Input channel·s: The channel to show.
- Input parameters:
  - name: Optional image name for the window title.
  - channel: A channel name, default is channel: input.
  - channels: A list of channel names, e.g. channels: [input, edge], that must have been precalculated.
- The Image::waitUntilWindowsClosed() usually called at the end of the int main(int argc, char *argv[]) function. wiats utill all display windows are closed.

Caution about bug and caveat

There is a bug using the opencv while forking processes, the program may block.