ScBarcodeScannerSettings Struct Reference

Public Member Functions

ScBarcodeScannerSettingssc_barcode_scanner_settings_new (void)
 
ScBarcodeScannerSettingssc_barcode_scanner_settings_new_with_preset (ScBarcodeScannerSettingsPresetFlags preset)
 
ScBarcodeScannerSettingssc_barcode_scanner_settings_new_from_json (char const *json_data, ScError *error)
 
void sc_barcode_scanner_settings_retain (ScBarcodeScannerSettings *settings)
 
void sc_barcode_scanner_settings_release (ScBarcodeScannerSettings *settings)
 
ScBarcodeScannerSettingssc_barcode_scanner_settings_clone (ScBarcodeScannerSettings *settings)
 
char * sc_barcode_scanner_settings_as_json (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_setup_for_ui_image (ScBarcodeScannerSettings *settings, UIImage *image)
 
Custom Properties
int32_t sc_barcode_scanner_settings_get_property (ScBarcodeScannerSettings const *settings, char const *key)
 
void sc_barcode_scanner_settings_set_property (ScBarcodeScannerSettings *settings, char const *key, int32_t value)
 
Symbology Settings
void sc_barcode_scanner_settings_set_symbology_enabled (ScBarcodeScannerSettings *settings, ScSymbology symbology, ScBool enabled)
 
ScSymbologySettingssc_barcode_scanner_settings_get_symbology_settings (ScBarcodeScannerSettings *settings, ScSymbology symbology)
 
Code Count
uint32_t sc_barcode_scanner_settings_get_max_number_of_codes_per_frame (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_max_number_of_codes_per_frame (ScBarcodeScannerSettings *settings, uint32_t max_codes)
 
Search Area
ScRectangleF sc_barcode_scanner_settings_get_search_area (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_search_area (ScBarcodeScannerSettings *settings, ScRectangleF scan_area)
 
Code Location
ScRectangleF sc_barcode_scanner_settings_get_code_location_area_1d (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_code_location_area_1d (ScBarcodeScannerSettings *settings, ScRectangleF rect)
 
ScCodeLocationConstraint sc_barcode_scanner_settings_get_code_location_constraint_1d (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_code_location_constraint_1d (ScBarcodeScannerSettings *settings, ScCodeLocationConstraint constraint)
 
ScRectangleF sc_barcode_scanner_settings_get_code_location_area_2d (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_code_location_area_2d (ScBarcodeScannerSettings *settings, ScRectangleF rect)
 
ScCodeLocationConstraint sc_barcode_scanner_settings_get_code_location_constraint_2d (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_code_location_constraint_2d (ScBarcodeScannerSettings *settings, ScCodeLocationConstraint constraint)
 
Camera Focus
ScCameraFocusMode sc_barcode_scanner_settings_get_focus_mode (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_focus_mode (ScBarcodeScannerSettings *settings, ScCameraFocusMode focus_mode)
 
Code Direction
ScCodeDirection sc_barcode_scanner_settings_get_code_direction_hint (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_code_direction_hint (ScBarcodeScannerSettings *settings, ScCodeDirection direction)
 
Session Settings

The session settings do not affect the object tracker (MatrixScan).

int32_t sc_barcode_scanner_settings_get_code_duplicate_filter (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_code_duplicate_filter (ScBarcodeScannerSettings *settings, int32_t filter)
 
int32_t sc_barcode_scanner_settings_get_code_caching_duration (ScBarcodeScannerSettings const *settings)
 
void sc_barcode_scanner_settings_set_code_caching_duration (ScBarcodeScannerSettings *settings, int32_t duration)
 

Detailed Description

An opaque data structure holding configuration options for the barcode scanner.

The barcode scanner settings influence how 1d and 2d codes are decoded by an ScBarcodeScanner instance.

For the settings to take effect they must be applied to the barcode scanner. This can be done when the barcode scanner is created (sc_barcode_scanner_new_with_settings()), or at a later stage with sc_barcode_scanner_apply_settings().

Steps to Configure the Barcode Scanner

Scan Location

By default, 1d and 2d codes are searched in the full image. If it is known that codes only appear in certain areas, or part of the camera feed is hidden below a UI element, the localization can be restricted to certain parts of the image by setting the scan area with sc_barcode_scanner_settings_set_search_area(). This setting affects both 1d and 2d codes.

To control scanning areas of 1d and 2d codes separately, set the 1d/2d code location areas (sc_barcode_scanner_settings_set_code_location_area_1d(), sc_barcode_scanner_settings_set_code_location_area_2d()). By default, these areas serve as hints to the barcode scanner as to where codes are expected in the image (the code location constraints are set to SC_CODE_LOCATION_HINT). The scanner uses these areas to give more weight to codes found in the code location areas. It is also possible to completely turn off barcode localization and only use the 1d/2d code location areas. This is done by setting the code location constraint to SC_CODE_LOCATION_RESTRICT.

Use Cases

To illustrate how the scan area, 1d/2d code location areas and constraints work together, we show configurations for common scanning scenarios.

Full Image Localization with preference to horizontal 1d codes: This is the default setting and not further configuration is required. The 1d code location area is set to a centered strip 1/5 of of the image height running from the left to the right. The code location constraint is set to SC_CODE_LOCATION_HINT, and the code direction hint is SC_CODE_DIRECTION_LEFT_TO_RIGHT.

Laser UI Scanning: To scan barcodes in a narrow band, set the 1d code location area and use a 1d code location constraint of SC_CODE_LOCATION_RESTRICT. You also need to set the code direction hint to match the main direction of the narrow band. If at the same time 2d codes are to be scanned, set the 2d code location area to a larger rectangle.

Code Duplicate Filter

The barcode scanner session offers functionality to temporally filter codes of the same symbology and encoding the same data scanned within a certain time interval. This feature is turned off by default and can be configured through the barcode scanner settings. It is enabled by

  • either setting the code duplicate filter (sc_barcode_scanner_settings_set_code_duplicate_filter()) to -1, in which case the same code is not reported again until the session is cleared.
  • or, setting the code duplicate filter to a value larger than 0, in which case the set values is the number of milliseconds in which the same code is not reported again as a new scan.

Note that the code duplicate filter is further affected by the value of the code caching duration. When the code caching duration is shorter than the code duplicate filter, the duplicate filter is effectively limited to the code caching duration.

Code Caching Duration

By default, all codes that pass the duplicate filter are stored in the all recognized codes list (sc_barcode_scanner_session_get_all_recognized_codes()). Because all of these codes are stored in memory, the all recognized codes list can grow substantially when scanning for a long time without calls to sc_barcode_scanner_session_clear(). Unless you have a specific reason to keep all the codes in the all recognized codes list, it is recommended to set the code caching duration to the same value as the code duplicate filter as this will make sure that the codes get removed once they reach a certain age.

Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.

Member Function Documentation

ScBarcodeScannerSettings * sc_barcode_scanner_settings_new ( void  )

Create a new barcode scanner settings object.

This function is identical to using sc_barcode_scanner_settings_new_with_preset() with SC_PRESET_NONE.

Returns
the newly created barcode scanner settings object. The object must be released after use by calling sc_barcode_scanner_settings_release().
Since
4.6.0
ScBarcodeScannerSettings * sc_barcode_scanner_settings_new_with_preset ( ScBarcodeScannerSettingsPresetFlags  preset)

Create a new barcode scanner settings object.

Parameters
presetan ORed combination of ScBarcodeScannerSettingsPreset
Returns
the newly created barcode scanner settings object. The object must be released after use by calling sc_barcode_scanner_settings_release().
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
ScBarcodeScannerSettings * sc_barcode_scanner_settings_new_from_json ( char const *  json_data,
ScError error 
)

Create a new barcode scanner settings object from a json description.

Parameters
json_datanull-terminated JSON data string. The string is allowed to have comments as well as use single quotes instead of double quotes.
errorin case the JSON data could not be parsed, error is filled with more details on the failure. In case of error, error must be freed after use using sc_error_free(). NULL may be used in case no further information on the error is required.
Returns
the newly created barcode scanner settings object. NULL is returned in case the json data could not be parsed without errors. Check error for details.

For a description of the JSON format undestood by this function, see Barcode Scanner Settings JSON format.

Since
4.11.0
void sc_barcode_scanner_settings_retain ( ScBarcodeScannerSettings settings)

Increase reference count of barcode scanner settings.

Parameters
settingsthe barcode scanner settings object. Must not be null
Since
4.6.0
void sc_barcode_scanner_settings_release ( ScBarcodeScannerSettings settings)

Decrease reference count of barcode scanner settings object by one.

When the reference count of the object drops to zero, it is deallocated.

Parameters
settingsthe barcode scanner settings object. Must not be null.
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
ScBarcodeScannerSettings * sc_barcode_scanner_settings_clone ( ScBarcodeScannerSettings settings)

Creates and returns a deep copy of the barcode scanner settings object.

Parameters
settingsThe settings object to be copied/cloned. Must not be null.
Returns
The cloned barcode scanner settings object with a reference count of one. After use, the barcode scanner settings object must be released with sc_barcode_scanner_settings_release().
Since
4.7.0
int32_t sc_barcode_scanner_settings_get_property ( ScBarcodeScannerSettings const *  settings,
char const *  key 
)

Get custom properties.

Custom properties are used for features of the barcode scanner that are not yet part of the public API. As such they can disappear in one of the next releases or change meaning. Use with caution.

Only properties of previous calls to sc_barcode_scanner_settings_set_property() are returned here. When a property is not set, a default value is assumed.

Parameters
settingsthe settings object. Must not be null
keythe name of the property
Returns
The value of the property, or -1 if the property does not exist.
Since
4.6.0
void sc_barcode_scanner_settings_set_property ( ScBarcodeScannerSettings settings,
char const *  key,
int32_t  value 
)

Set custom properties.

Parameters
settingsthe settings object. Must not be null
keythe name of the property
valuethe value to be set
See also
sc_barcode_scanner_settings_get_property
Since
4.6.0
void sc_barcode_scanner_settings_set_symbology_enabled ( ScBarcodeScannerSettings settings,
ScSymbology  symbology,
ScBool  enabled 
)

Enable/disable decoding of a certain symbology.

This function provides a convenient shortcut to enabling/disabling decoding of a particular symbology without having to go through ScSymbologySettings.

ScBarcodeScannerSettings* settings = ... ;
// the following lines have the same effect:
ScSymbologySettings *sym_settings =
sc_symbology_settings_set_enabled(sym_settings, SC_TRUE);
Parameters
settingsthe barcode scanner settings object. Must not be null
symbologythe symbology to be enabled. Must be a valid symbology and equal to SC_SYMBOLOGY_UNKNOWN
enabledtrue when decoding of the symbology should be enabled, false if not.
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
ScSymbologySettings * sc_barcode_scanner_settings_get_symbology_settings ( ScBarcodeScannerSettings settings,
ScSymbology  symbology 
)

Retrieve symbology-specific settings.

Parameters
settingsthe barcode scanner settings object. Must not be null
symbologythe symbology for which to retrieve the settings. Must be one of the valid symbology enums and not SC_SYMBOLOGY_UNKNOWN.
Returns
the symbology-specific settings object. The object is owned by the barcode scanner settings object and freed automatically when the barcode scanner settings object is freed.
Since
4.6.0
Examples:
CommandLineBarcodeScannerImageProcessingSample.c.
uint32_t sc_barcode_scanner_settings_get_max_number_of_codes_per_frame ( ScBarcodeScannerSettings const *  settings)

Get the maximum number of barcode to be decoded every frame.

Parameters
settingsthe barcode scanner settings object. Must not be null
Returns
the maximum number of codes per frame
Since
4.6.0
void sc_barcode_scanner_settings_set_max_number_of_codes_per_frame ( ScBarcodeScannerSettings settings,
uint32_t  max_codes 
)

Set the maximum number of barcode to be decoded every frame.

Parameters
settingsthe barcode scanner settings object. Must not be null
max_codesthe new maximum number of codes to be decoded every frame. Can not be set to zero.
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
ScRectangleF sc_barcode_scanner_settings_get_search_area ( ScBarcodeScannerSettings const *  settings)

Get the area of the image in which barcodes are searched.

By default, barcodes are searched in the whole image. By restricting the search area to smaller areas the barcode scanner performance can be optimized.

Parameters
settingsThe barcode scanner settings object. Must not be null.
Returns
the barcode scan area in relative image coordinates. The top-left corner of the image is (0, 0), the bottom right corner is (1, 1).
Since
4.6.0
void sc_barcode_scanner_settings_set_search_area ( ScBarcodeScannerSettings settings,
ScRectangleF  scan_area 
)

Set the area of the image in which barcodes are searched.

Parameters
settingsThe barcode scanner settings object. Must not be null.
scan_areaThe new search area in relative image coordinates. The top-left corner of the image is (0, 0), the bottom right corner is (1, 1).
See also
sc_barcode_scanner_settings_get_search_area
Since
4.6.0
ScRectangleF sc_barcode_scanner_settings_get_code_location_area_1d ( ScBarcodeScannerSettings const *  settings)

Get 1d code location area.

Parameters
settingsthe settings object. Must not be null
Returns
the code location rectangle in relative image coordinates. The top-left corner of the image is (0, 0), the bottom right corner is (1, 1).
Since
4.6.0
void sc_barcode_scanner_settings_set_code_location_area_1d ( ScBarcodeScannerSettings settings,
ScRectangleF  rect 
)

Set code location area for 1d codes.

Parameters
settingsthe settings object. Must not be null
rectthe code location rectangle in relative image coordinates. The top-left corner of the image is (0, 0), the bottom right corner is (1, 1).
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c.
ScCodeLocationConstraint sc_barcode_scanner_settings_get_code_location_constraint_1d ( ScBarcodeScannerSettings const *  settings)

Get 1d code location constraint.

Parameters
settingsthe settings object. Must not be null.
Returns
The code location constraint currently configured
Since
4.6.0
void sc_barcode_scanner_settings_set_code_location_constraint_1d ( ScBarcodeScannerSettings settings,
ScCodeLocationConstraint  constraint 
)

Set the 1d code location constraint.

Parameters
settingsThe settings object. Must not be null.
constraintThe code location constraint.
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
ScRectangleF sc_barcode_scanner_settings_get_code_location_area_2d ( ScBarcodeScannerSettings const *  settings)

Get 2d code location area.

Parameters
settingsthe settings object. Must not be null
Returns
the code location rectangle in relative image coordinates. The top-left corner of the image is (0, 0), the bottom right corner is (1, 1).
Since
4.6.0
void sc_barcode_scanner_settings_set_code_location_area_2d ( ScBarcodeScannerSettings settings,
ScRectangleF  rect 
)

Set code location area for 2d codes.

Parameters
settingsthe settings object. Must not be null
rectthe code location rectangle in relative image coordinates. The top-left corner of the image is (0, 0), the bottom right corner is (1, 1).
Since
4.6.0
ScCodeLocationConstraint sc_barcode_scanner_settings_get_code_location_constraint_2d ( ScBarcodeScannerSettings const *  settings)

Get 2d code location constraint.

Parameters
settingsthe settings object. Must not be null
Returns
the code location constraint currently configured
Since
4.6.0
void sc_barcode_scanner_settings_set_code_location_constraint_2d ( ScBarcodeScannerSettings settings,
ScCodeLocationConstraint  constraint 
)

Set the 2d code location constraint.

Parameters
settingsThe settings object. Must not be null
constraintThe code location constraint.
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
ScCameraFocusMode sc_barcode_scanner_settings_get_focus_mode ( ScBarcodeScannerSettings const *  settings)

Get the camera's focus type.

Parameters
settingsthe settings object. Must not be null
Returns
the current focus type of the camera
Since
4.6.0
void sc_barcode_scanner_settings_set_focus_mode ( ScBarcodeScannerSettings settings,
ScCameraFocusMode  focus_mode 
)

Set the camera's focus type.

Parameters
settingsthe settings object. Must not be null.
focus_modethe focus type of the camera.
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, and CommandLineMatrixScanCameraSample.c.
ScCodeDirection sc_barcode_scanner_settings_get_code_direction_hint ( ScBarcodeScannerSettings const *  settings)

Get the code direction hint.

Parameters
settingsthe barcode scanner settings object. Must not be null.
Returns
The current code direction hint. The default is SC_CODE_DIRECTION_LEFT_TO_RIGHT.
Since
4.6.0
void sc_barcode_scanner_settings_set_code_direction_hint ( ScBarcodeScannerSettings settings,
ScCodeDirection  direction 
)

Set the code direction hint.

The code direction hint tells the barcode scanner in what direction 1-dimensional codes are most likely oriented. This hint is only useful for 1d (barcodes), and ignored for 2d codes.

The hint is in image coordinates. If you are scanning barcodes on a mobile device that supports multiple device orientations, you will have to rotate the hint accordingly. For example if you want to scan horizontal codes when the phone/device is in portrait mode, you will have to set the code direction hint to SC_CODE_DIRECTION_BOTTOM_TO_TOP.

Parameters
settingsThe barcode scanner settings object. Must not be null.
directionThe new code direction hint.
See also
sc_barcode_scanner_settings_get_code_direction_hint
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
int32_t sc_barcode_scanner_settings_get_code_duplicate_filter ( ScBarcodeScannerSettings const *  settings)

Get the code duplicate filter of the scan session.

See also
sc_barcode_scanner_settings_set_code_duplicate_filter

Duplicate filtering affects the handling of codes with the same data and symbology scanned within a certain, typically short, time interval. When the filter is set to -1, each unique code is only added once to the session, when set to 0, duplicate filtering is disabled. Otherwise the duplicate filter specifies an interval in milliseconds. When the same code (data/symbology) is scanned within the specified interval is it filtered out as a duplicate.

By default, the code duplicate filter is disabled (set to 0). The code duplicate filter is also affected by the code caching duration (see code caching duration section above).

Parameters
settingsthe settings object. Must no be null
Returns
The current code duplicate filter.
Since
4.6.0
void sc_barcode_scanner_settings_set_code_duplicate_filter ( ScBarcodeScannerSettings settings,
int32_t  filter 
)

Specifies the duplicate filter to use for the session.

Parameters
settingsthe settings object. Must no be null
filterthe new code duplicate filter

The code duplicate filter settings only affect the scan session and do not affect the object tracker.

See also
sc_barcode_scanner_settings_get_code_duplicate_filter
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, and CommandLineMatrixScanCameraSample.c.
int32_t sc_barcode_scanner_settings_get_code_caching_duration ( ScBarcodeScannerSettings const *  settings)

Get the code caching duration of the scan session.

When set to -1, codes are kept until the next call to sc_barcode_scanner_session_clear(). When set to 0, codes are kept until the next frame processing call finishes. For all other values, code_caching_duration specifies a duration in milliseconds for how long the codes are kept.

The default value is -1.

Parameters
settingsthe settings object. Must not be null
Returns
The code caching duration.
Since
4.6.0
void sc_barcode_scanner_settings_set_code_caching_duration ( ScBarcodeScannerSettings settings,
int32_t  duration 
)

Determines how long codes are kept in the session.

Parameters
settingsthe settings object. Must not be null
durationthe code caching duration

The code caching duration only affects the scan session and does not affect the object tracker.

See also
sc_barcode_scanner_settings_get_code_caching_duration
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, and CommandLineMatrixScanCameraSample.c.
char * sc_barcode_scanner_settings_as_json ( ScBarcodeScannerSettings const *  settings)

Returns the settings contained in the object as json.

Parameters
settingsthe settings object. Must not be null
Returns
The settings serialized as JSON. After use the string must be freed by the caller using sc_free().
Since
4.6.0
void sc_barcode_scanner_settings_setup_for_ui_image ( ScBarcodeScannerSettings settings,
UIImage *  image 
)

Configure barcode scanner settings for recognizing barcodes in the provided UIImage.

Use this function for optimizing the barcode scanner settings for scanning barcodes with ScRecognitionContext::sc_recognition_context_process_frame. The settings, e.g. recognition areas, code direction hint etc. are modified in-place. This function does not enable any of the symbologies. You need to explicitly enable the barcode symbologies that you would like to scan.

Parameters
settingsThe settings object to modify. Must not be null
imagethe image to optimize parameters for.
Since
4.14.0

The documentation for this struct was generated from the following file: