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
- Create a new settings object starting from an empty configuration (sc_barcode_scanner_settings_new()), or using a combination of presets (sc_barcode_scanner_settings_new_with_preset()).
- Enable decoding of the required 1d and 2d symbologies using sc_barcode_scanner_settings_set_symbology_enabled().
- Optional: Set any additional symbology-specific settings on the symbology settings objects obtained by calling sc_barcode_scanner_settings_get_symbology_settings().
- Optional: If desired, configure the scan location (see below).
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
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
-
preset an 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
| 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_data null-terminated JSON data string. The string is allowed to have comments as well as use single quotes instead of double quotes. error in case the JSON data could not be parsed, error is filled with more details on the failure. In case of error, errormust 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
errorfor 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
-
settings the 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
-
settings the barcode scanner settings object. Must not be null.
- Since
- 4.6.0
| ScBarcodeScannerSettings * sc_barcode_scanner_settings_clone | ( | ScBarcodeScannerSettings * | settings | ) |
Creates and returns a deep copy of the barcode scanner settings object.
- Parameters
-
settings The 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
-
settings the settings object. Must not be null key the 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
-
settings the settings object. Must not be null key the name of the property value the value to be set
- 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.
- Parameters
-
settings the barcode scanner settings object. Must not be null symbology the symbology to be enabled. Must be a valid symbology and equal to SC_SYMBOLOGY_UNKNOWN enabled true when decoding of the symbology should be enabled, false if not.
- Since
- 4.6.0
| ScSymbologySettings * sc_barcode_scanner_settings_get_symbology_settings | ( | ScBarcodeScannerSettings * | settings, |
| ScSymbology | symbology | ||
| ) |
Retrieve symbology-specific settings.
- Parameters
-
settings the barcode scanner settings object. Must not be null symbology the 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
| 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
-
settings the 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
-
settings the barcode scanner settings object. Must not be null max_codes the new maximum number of codes to be decoded every frame. Can not be set to zero.
- Since
- 4.6.0
| 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
-
settings The 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
-
settings The barcode scanner settings object. Must not be null. scan_area The new search 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
| ScRectangleF sc_barcode_scanner_settings_get_code_location_area_1d | ( | ScBarcodeScannerSettings const * | settings | ) |
Get 1d code location area.
- Parameters
-
settings the 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
-
settings the settings object. Must not be null rect 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
- Examples:
- CommandLineBarcodeScannerCameraSample.c.
| ScCodeLocationConstraint sc_barcode_scanner_settings_get_code_location_constraint_1d | ( | ScBarcodeScannerSettings const * | settings | ) |
Get 1d code location constraint.
- Parameters
-
settings the 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
-
settings The settings object. Must not be null. constraint The code location constraint.
- Since
- 4.6.0
| ScRectangleF sc_barcode_scanner_settings_get_code_location_area_2d | ( | ScBarcodeScannerSettings const * | settings | ) |
Get 2d code location area.
- Parameters
-
settings the 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
-
settings the settings object. Must not be null rect 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
| ScCodeLocationConstraint sc_barcode_scanner_settings_get_code_location_constraint_2d | ( | ScBarcodeScannerSettings const * | settings | ) |
Get 2d code location constraint.
- Parameters
-
settings the 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
-
settings The settings object. Must not be null constraint The code location constraint.
- Since
- 4.6.0
| ScCameraFocusMode sc_barcode_scanner_settings_get_focus_mode | ( | ScBarcodeScannerSettings const * | settings | ) |
Get the camera's focus type.
- Parameters
-
settings the 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
-
settings the settings object. Must not be null. focus_mode the focus type of the camera.
- Since
- 4.6.0
| ScCodeDirection sc_barcode_scanner_settings_get_code_direction_hint | ( | ScBarcodeScannerSettings const * | settings | ) |
Get the code direction hint.
- Parameters
-
settings the 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
-
settings The barcode scanner settings object. Must not be null. direction The new code direction hint.
- Since
- 4.6.0
| int32_t sc_barcode_scanner_settings_get_code_duplicate_filter | ( | ScBarcodeScannerSettings const * | settings | ) |
Get the code duplicate filter of the scan session.
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
-
settings the 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
-
settings the settings object. Must no be null filter the new code duplicate filter
The code duplicate filter settings only affect the scan session and do not affect the object tracker.
- Since
- 4.6.0
| 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
-
settings the 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
-
settings the settings object. Must not be null duration the code caching duration
The code caching duration only affects the scan session and does not affect the object tracker.
- Since
- 4.6.0
| char * sc_barcode_scanner_settings_as_json | ( | ScBarcodeScannerSettings const * | settings | ) |
Returns the settings contained in the object as json.
- Parameters
-
settings the 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
-
settings The settings object to modify. Must not be null image the image to optimize parameters for.
- Since
- 4.14.0
The documentation for this struct was generated from the following file: