Parameters for saving images, converting images to bi-level images, and rendering biometric signatures as images.
More...
#include <SignDocSDK-cpp.h>
Parameters for saving images, converting images to bi-level images, and rendering biometric signatures as images.
In the descriptions of a parameter, the functions that make use of that parameter are indicated by these letters in square brackets:
- M (match)
- R (render)
- S (save)
- T (threshold)
Parameters for selecting the image format:
- BitsPerComponent (integer)
- BlackIsZero (boolean)
- BottomUp (boolean)
- Components (integer)
- Compression (string)
- Format (string)
- OverrideResolution (integer)
- Padding (integer)
- PixelFormat (string)
- WhiteIsZero (boolean)
Parameters for conversion to bi-level black and white:
Parameters for configuring the size of the image:
- ExactHeight (integer)
- ExactWidth (integer)
- LimitResolution (integer)
- LimitResolutionRelative (floating-point number)
- Resolution (integer)
- ResolutionRatio (floating-point number)
- Scale (floating-point number)
Parameters for tuning the rendering of signatures:
- BackgroundColor (color)
- ColorMode (string)
- Engine (string)
- PenWidth (floating-point number)
- PenWidthPixels (floating-point number)
- PenWidthSource (floating-point number)
- SignatureColor (color)
Parameters for adding a cross:
- AddCross (boolean)
- CrossColor (color)
- CrossWidth (floating-point number)
- CrossWidthPixels (floating-point number)
- CrossWidthSource (floating-point number)
The "raw" format stores the pixels only, without any header or other information. Therefore, the aOutput parameter (of type SignDocRenderOutput) of SignDocSignatureData::renderAsImage() is mandatory. The following paragraphs describe the available raw formats.
If integer parameter "BitsPerComponent" is 1, integer parameter "Components" must be 1 and 8 pixels will be stored per byte. The left-most pixel is stored in the most significant bit (0x80). Padding bits are added such that each row occupies an integral number of bytes. The interpretation of the values of the bits depends on boolean parameters "BlackIsZero" and "WhiteIsZero".
If integer parameter "BitsPerComponent" is 8 and integer parameter "Components" is 1, one byte per pixel (usually the palette index) will be stored.
If integer parameter "BitsPerComponent" is 8 and integer parameter "Components" is 3, three bytes per pixel will be stored: red, green, and blue. The value 0 is used for off, the value 0xff is used for on. The pixel format can be changed by setting string parameter "PixelFormat".
Depending on boolean parameter "BottomUp", the raw image begins with the left-most pixel of the top row (false) or with the left-most pixel of the bottom row (true).
Constructor.
No parameters will be set.
Copy constructor.
- Parameters
-
| [in] | aSource | The object to be copied. |
| const int * getBoolean |
( |
const std::string & |
aName | ) |
const |
|
inline |
Get the value of a boolean parameter.
This function does not set an error message.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
- Returns
- A pointer to the value of the specified parameter or nullptr if the parameter is not set or is not a boolean parameter.
- See also
- setBoolean()
Get the value of a color parameter.
This function does not set an error message.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
- Returns
- A pointer to the value of the specified parameter or nullptr if the parameter is not set. The caller is responsible for destroying the object.
- See also
- setColor()
| const char * getErrorMessage |
( |
Encoding |
aEncoding | ) |
const |
|
inline |
Get an error message for the last function call.
- Parameters
-
| [in] | aEncoding | The encoding to be used for the error message. |
- Returns
- A pointer to a string describing the reason for the failure of the last function call. The string is empty if the last call succeeded. The pointer is valid until this object is destroyed or a member function of this object is called.
- See also
- getErrorMessageW()
| const wchar_t * getErrorMessageW |
( |
| ) |
const |
|
inline |
Get an error message for the last function call.
- Returns
- A pointer to a string describing the reason for the failure of the last function call. The string is empty if the last call succeeded. The pointer is valid until this object is destroyed or a member function of this object is called.
- See also
- getErrorMessage()
| SIGNDOC_ImageParameters* getImpl |
( |
| ) |
|
|
inline |
| const SIGNDOC_ImageParameters* getImpl |
( |
| ) |
const |
|
inline |
| const int * getInteger |
( |
const std::string & |
aName | ) |
const |
|
inline |
Get the value of an integer parameter.
This function does not set an error message.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
- Returns
- A pointer to the value of the specified parameter or nullptr if the parameter is not set or is not an integer parameter.
- See also
- setInteger()
| const double * getNumber |
( |
const std::string & |
aName | ) |
const |
|
inline |
Get the value of a floating-point number parameter.
This function does not set an error message.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
- Returns
- A pointer to the value of the specified parameter or nullptr if the parameter is not set or is not a floating-point number parameter.
- See also
- setNumber()
| const char * getString |
( |
const std::string & |
aName | ) |
const |
|
inline |
Get the value of a string parameter.
This function does not set an error message.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
- Returns
- A pointer to the value of the specified parameter or nullptr if the parameter is not set.
- See also
- getErrorMessage(), setString()
Get the type of a parameter.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
- Returns
- The type of the parameter, see enum Type.
Assignment operator.
- Parameters
-
| [in] | aSource | The source object. |
- Returns
- This object.
| ReturnCode setBoolean |
( |
const std::string & |
aName, |
|
|
bool |
aValue |
|
) |
| |
|
inline |
Set a boolean parameter.
The following boolean parameters are available:
- AddCross [R]: true to draw a cross over the signature. The default value is false. See also color parameter "CrossColor" and floating-point number parameters "CrossWidth", "CrossWidthPixels", and "CrossWidthSource". If this parameter is true and the value of color parameter "CrossColor" equals neither the value of color parameter "BackgroundColor" nor the value of color parameter "SignatureColor", then integer parameter "Components" must be 3.
- BlackIsZero [RS]: true to save black pixels as bits with value 0. This parameter is used for format "raw" with 1 bit per pixel only and must not be set for other formats. If neither "BlackIsZero" nor "WhiteIsZero" is true, the bits will be saved unchanged and their interpretation will depend on the palette. "Black" means the darker one of the two colors. If both colors have the same intensity or both "BlackIsZero" and "WhiteIsZero" are true, an error will be reported.
- BottomUp [RS]: true to store the image bottom-up, false to store the image top-down. This parameter is used for format "raw" only and is ignored for other formats. The default value is false.
- WhiteIsZero [RS]: true to save white pixels as bits with value 0. This parameter is used for format "raw" with 1 bit per pixel only and must not be set for other formats. If neither "BlackIsZero" nor "WhiteIsZero" is true, the bits will be saved unchanged and their interpretation will depend on the palette. "White" means the brighter one of the two colors. If both colors have the same intensity or both "BlackIsZero" and "WhiteIsZero" are true, an error will be reported.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
| [in] | aValue | The value of the parameter. |
- Returns
- ReturnCode::rc_ok iff successful.
- See also
- getBoolean(), setColor(), setInteger(), setNumber(), setString()
Set a color parameter.
The following color parameters are available:
- BackgroundColor [R]: the background color. Default value: white.
- CrossColor [R]: the color of the cross (see boolean parameter "AddCross"). Default value: black.
- SignatureColor [R]: the signature color. Default value: black. If the darkness of the signature is configured to vary (see string parameter "ColorMode"), the signature color actually being used will vary between the background color configured by color parameter "BackgroundColor" and the signature color configured by color parameter "SignatureColor".
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
| [in] | aValue | The value of the parameter. |
- Returns
- ReturnCode::rc_ok iff successful.
- See also
- getColor(), setBoolean(), setInteger(), setNumber(), setString()
| void setImpl |
( |
SIGNDOC_ImageParameters * |
aP | ) |
|
|
inline |
| ReturnCode setInteger |
( |
const std::string & |
aName, |
|
|
int |
aValue |
|
) |
| |
|
inline |
Set an integer parameter.
The following integer parameters are available:
- BitsPerComponent [RS] (1 or 8): number of bits per color component. The default value for rendering signatures is 8, the default value for saving images is taken from the image. See also integer parameter "Components".
- Components [RS] (1 or 3): number of color components:
- 1: indexed with either 2 or 256 palette entries
- 3: RGB (integer parameter "BitsPerComponent" must be set to 8)
The default value for rendering signatures is 1, the default value for saving images is taken from the image. See also integer parameter "BitsPerComponent".
- ExactHeight [R] (15 or greater): the desired height of the resulting image. The size of the signature will be reduced to make it fit the specified size and margins will be added as needed. If this parameter is set, all other parameters (except for integer parameter "ExactWidth") controlling image size will be ignored. Settings this parameter will slow down rendering considerably.
- ExactWidth [R] (15 or greater): the desired width of the resulting image. The size of the signature will be reduced to make it fit the specified size and margins will be added as needed. If this parameter is set, all other parameters (except for integer parameter "ExactHeight") controlling image size will be ignored. Settings this parameter will slow down rendering considerably.
- LimitResolution [MR]: Limit the horizontal resolution of the image to the value of this parameter. The limit for the vertical resolution is computed from the value of this parameter by dividing by the value of floating-point number parameter "ResolutionRatio". The default value is zero. See also floating-point number parameter "LimitResolutionRelative".
- OverrideResolution [RS]: set the horizontal resolution of the resulting image. The vertical resolution is computed from the horizontal resolution by dividing by the value of floating-point number parameter "ResolutionRatio". The value of this parameter does not affect the computation of the scaling factor. This parameter is ignored if string parameter "Format" has value "raw".
- Padding [RS] (0, 1, 2, or 4): row padding in bytes for raw format. No padding will be added if this parameter is 0. Otherwise, each row will be padded at the end with bits or bytes having value 0 such that the length of the row is an integer multiple of the value of this parameter. The default value is 0 (no padding). This parameter affects format "raw" only and is ignored for other formats.
- Resolution [R]: Scale the coordinates such that the image will have the horizontal resolution (in DPI) set by this parameter. The vertical resolution is computed from the horizontal resolution by dividing by the value of floating-point number parameter "ResolutionRatio".
- Threshold [T]: (1 through 255): Threshold for conversion to bi-level black and white. The default value is 128. Pixels with an intensity (0 through 255) of this value or above will be mapped to white, other pixels will be mapped to black.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
| [in] | aValue | The value of the parameter. |
- Returns
- ReturnCode::rc_ok iff successful.
- See also
- getInteger(), setBoolean(), setColor(), setNumber(), setString()
| ReturnCode setNumber |
( |
const std::string & |
aName, |
|
|
double |
aValue |
|
) |
| |
|
inline |
Set a floating-point number parameter.
The following floating-point number parameters are available:
- CrossWidth [R]: Horizontal pen width for the cross enabled by boolean parameter "AddCross" in millimeters. The pen width set by this parameter depends on the horizontal resolution of the image. The vertical pen width is computed from the horizontal pen width by dividing by the value of floating-point number parameter "ResolutionRatio". "CrossWidth", "CrossWidthPixels", and "CrossWidthSource" are mutually exclusive. If none of these is set, a default value of 0.5 will be used for "CrossWidth".
- CrossWidthPixels [R]: Horizontal pen width for the cross enabled by boolean parameter "AddCross" in pixels (that is, in image coordinates). The pen width set by this parameter is not affected by scaling. The vertical pen width is computed from the horizontal pen width by dividing by the value of floating-point number parameter "ResolutionRatio". "CrossWidth", "CrossWidthPixels", and "CrossWidthSource" are mutually exclusive. If none of these is set, a default value of 0.5 will be used for "CrossWidth".
- CrossWidthSource [R]: Horizontal pen width for the cross enabled by boolean parameter "AddCross" in capture device units. The pen width set by this parameter will be scaled along with the samples of the signature. The vertical pen width is computed from the horizontal pen width by dividing by the value of floating-point number parameter "ResolutionRatio". "CrossWidth", "CrossWidthPixels", and "CrossWidthSource" are mutually exclusive. If none of these is set, a default value of 0.5 will be used for "CrossWidth".
- LimitResolutionRelative [MR]: If positive, limit the horizontal resolution of the image to the resolution of the capture device multiplied by the value of this parameter. The limit for the vertical resolution is computed from the value of this parameter by dividing by the value of floating-point number parameter "ResolutionRatio". If zero, do not limit the resolution. The default value is 1.0, that is, the size of the signature in the rendered image won't exceed the size of the captured signature. See also integer parameter "LimitResolution". Example: If the resolution is not limited (by setting this parameter to zero) and integer parameter "ExactWidth" is 500 and the signature contains a single sample, you will get a filled circle the diameter of which is 500 pixels.
- PenWidth [MR]: Horizontal pen width for the signature in millimeters. The pen width set by this parameter depends on the horizontal resolution of the image. The vertical pen width is computed from the horizontal pen width by dividing by the value of floating-point number parameter "ResolutionRatio". "PenWidth", "PenWidthPixels", and "PenWidthSource" are mutually exclusive. If none of these is set, a default value of 0.5 will be used for "PenWidth".
- PenWidthPixels [MR]: Horizontal pen width for the signature in pixels (that is, in image coordinates). The pen width set by this parameter is not affected by scaling. The vertical pen width is computed from the horizontal pen width by dividing by the value of floating-point number parameter "ResolutionRatio". "PenWidth", "PenWidthPixels", and "PenWidthSource" are mutually exclusive. If none of these is set, a default value of 0.5 will be used for "PenWidth".
- PenWidthSource [MR]: Horizontal pen width for the signature in capture device units. The pen width set by this parameter will be scaled along with the samples of the signature. The vertical pen width is computed from the horizontal pen width by dividing by the value of floating-point number parameter "ResolutionRatio". "PenWidth", "PenWidthPixels", and "PenWidthSource" are mutually exclusive. If none of these is set, a default value of 0.5 will be used for "PenWidth".
- ResolutionRatio [R]: Vertical measurements (such as image resolution) are computed from horizontal measurements by dividing the horizontal value by the value of this parameter. The default value is 1.0. The following integer parameters are affected by this parameter: "LimitResolution", "OverrideResolution" and "Resolution". The following floating-point number parameters are affected by this parameter: "CrossWidth", "CrossWidthPixels", "CrossWidthSource", "LimitResolutionRelative", "PenWidth", "PenWidthPixels", "PenWidthSource", and "Scale".
- Scale [MR]: Convert from capture device coordinates to image coordinates by multiplying with this value. This parameter specifies the horizontal conversion factor, the vertical conversion factor is computed by dividing the value of this parameter by the value of floating-point number parameter "ResolutionRatio". This parameter is ignored if integer parameter "ExactWidth" or "ExactHeight" is set; otherwise, the default value is 1.0.
- Parameters
-
| [in] | aName | The name of the parameter (case-sensitive). |
| [in] | aValue | The value of the parameter. |
- Returns
- ReturnCode::rc_ok iff successful.
- See also
- getNumber(), setBoolean(), setColor(), setInteger(), setString()
| ReturnCode setString |
( |
Encoding |
aEncoding, |
|
|
const std::string & |
aName, |
|
|
const std::string & |
aValue |
|
) |
| |
|
inline |
Set a string parameter.
The following string parameters are available:
- ColorMode [R]: how to compute the actual color of the signature:
- "anti-aliasing": Color will be used for anti-aliasing. This also affects drawing of the cross enabled by boolean parameter "AddCross".
- "constant": always use the color configured by color parameter "SignatureColor".
- "pressure": vary the color according to the pressure (force) of the samples.
The default value is "constant".
- Compression for TIFF format [RS]:
- "none": not compressed
- "ccitt4": CCITT Group 4
- "lzw": LZW
- "rle": RLE
- "zip": ZIP
The default value is "none". This parameter is used only if string parameter "Format" has value "tiff".
- Engine [MR]: rendering engine to be used:
- "cubic": a rendering engine using cubic splines; swapped samples (and other variants of out-of-order samples) can cause funny results
- "linear": a rendering engine that connects samples with straight lines
The default value is "cubic".
- Format [RS]: the image format to be used for the image blob:
- "auto": derive the format from the suffix of the pathname (not possible when saving to a blob)
- "bmp": Windows bitmap
- "gif": GIF
- "png": PNG
- "raw: raw pixels, see introduction for details
- "tiff": TIFF
This parameter is mandatory for SignDocImage::saveToFile(), SignDocImage::saveToMemory(), and SignDocSignatureData::renderAsImage(). It is ignored for other functions.
- PixelFormat [RS]: The pixel format for writing raw pixels. For each character in the string, one byte per pixel will be written, in the order given. The image is created with the number of components specified by integer parameter "Components" (when rendering a signature) or converted to the number of components specified by that parameter (when saving an image). Then, each pixel is written according to the value of string parameter "PixelFormat". That is, the number of characters in that value need not match the value of integer parameter "Components". For instance, you can pad RGB pixels to 4 bytes by using pixel format "RGBP". The following characters are available:
- B blue
- G green
- I intensity (all channels have equal weight)
- P padding (always 0)
- R red
- X palette index
The default value is "X" for 1 component and "RGB" for 3 components. This parameter must not be set to a non-empty string if the value of integer parameter "BitsPerComponent" is 1.
- Parameters
-
| [in] | aEncoding | The encoding used for aValue. |
| [in] | aName | The name of the parameter (case-sensitive). |
| [in] | aValue | The value of the parameter. The encoding is specified by aEncoding. |
- Returns
- ReturnCode::rc_ok iff successful.
- See also
- getString(), setBoolean(), setColor(), setInteger(), setNumber()
Efficiently swap this object with another one.
- Parameters
-
| [in] | aOther | The other object. |
The documentation for this class was generated from the following file:
1.8.9.1 
