ScRecognitionContext Struct Reference

Public Member Functions

ScRecognitionContextsc_recognition_context_new (char const *license_key, char const *writable_data_path, JNIEnv *env, jobject activity, char const *device_name)
 
ScRecognitionContextsc_recognition_context_new (char const *license_key, char const *writable_data_path, char const *device_name)
 
void sc_recognition_context_retain (ScRecognitionContext *context)
 
void sc_recognition_context_release (ScRecognitionContext *context)
 
void sc_recognition_context_start_new_frame_sequence (ScRecognitionContext *context)
 
ScProcessFrameResult sc_recognition_context_process_frame (ScRecognitionContext *context, ScImageDescription const *image_description, uint8_t const *image_data)
 
void sc_recognition_context_end_frame_sequence (ScRecognitionContext *context)
 
void sc_recognition_context_set_geographical_location (ScRecognitionContext *context, float latitude, float longitude)
 
void sc_recognition_context_set_camera_properties (ScRecognitionContext *context, ScCameraProperties camera_properties)
 

Detailed Description

Opaque recognition context data structure.

The recognition context manages scanner objects of different types and takes care of scheduling the recognition process. By default, the recognition context does not have any scanners. To recognize a particular set of objects, the scanner object must be created. At the moment, the only available scanner is the ScBarcodeScanner which recognizes 1d and 2d codes in images.

To create a new recognition context a platform-specific function must be used. These functions take care of license-management read the appropriate system properties to optimize the recognition process for the device.

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

Member Function Documentation

ScRecognitionContext * sc_recognition_context_new ( char const *  license_key,
char const *  writable_data_path,
JNIEnv *  env,
jobject  activity,
char const *  device_name 
)

Create a new recognition context (Android only).

Parameters
license_keyYour license key, can't be NULL.
writable_data_pathPath to a writable folder, can't be NULL.
envPointer to the JNIEnv* object instance, can't be NULL.
activityPointer to the activity object the recognition context is created in.
device_nameOptional descriptive device name. Can be any string to track individual physical devices in Scanalytics. This parameter can be NULL to disable tracking.

For performance reasons it is recommended that only one context per application is used. If multiple contexts are created, make sure that context with different device_model_name do not share the same writable_data_path.

Returns
The newly created recognition context. After use, the context must be released by calling sc_recognition_context_release().
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
ScRecognitionContext * sc_recognition_context_new ( char const *  license_key,
char const *  writable_data_path,
char const *  device_name 
)

Recognition context constructor.

Parameters
license_keyyour license key, can't be NULL
writable_data_pathpath to a writable folder, can't be NULL
device_namea descriptive name or NULL

Note: This constructor is not available on Android.

The device_model_name parameter is used to optimize the algorithms for a certain hardware. On iOS and Windows the official device ids should be used. E.g. 'iPhone5,1'.

The device_name can be any string to track individual physical devices in Scanalytics. This parameter can be NULL to disable tracking.

For performance reasons it is recommended that only one context per application is used. If multiple contexts are created, make sure that context with different device_model_name do not share the same writable_data_path. Contexts with the same device_model_name can share a writable_data_path.

Returns
The newly created recognition context. After use, the context must be released by calling sc_recognition_context_release().
Since
4.6.0
void sc_recognition_context_retain ( ScRecognitionContext context)

Increase reference count of recognition context by one.

Parameters
contextA valid context. Must not be null
Since
4.6.0
void sc_recognition_context_release ( ScRecognitionContext context)

Decrease reference count of recognition context by one.

When the reference count drops to zero, the recognition context is deallocated.

Parameters
contextA valid context. May be null
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
void sc_recognition_context_start_new_frame_sequence ( ScRecognitionContext context)

Start processing a new batch of continuous frames.

Call this function to inform the recognition context that a new sequence of frames starts. The recognition context can assume that frames passed to sc_recognition_context_process_frame() have temporal consistency and can use it to optimize the recognition processs. To indicate discontinuities between frames, e.g. when resuming the camera after a pause, use sc_recognition_context_end_frame_sequence() followed by sc_recognition_context_start_new_frame_sequence().

This function must be called once before sc_recognition_context_process_frame().

The following example shows how to process an individual image:

ScRecognitionContext *context = ...;
ScImageDescription *image_description = ...;
uint8_t* image_data = ...;
sc_recognition_context_process_frame(context, image_description, image_data);
Parameters
contextA valid context. Must not be null.
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
ScProcessFrameResult sc_recognition_context_process_frame ( ScRecognitionContext context,
ScImageDescription const *  image_description,
uint8_t const *  image_data 
)

Process image frame with this recognition context.

The image is processed by the scanners associated with this context. The results, for example the recognized barcodes, can be accessed directly on the scanner objects.

Although you can pass in images of any size, and use any of the image layouts defined in ScImageLayout, the recognition context and the associated scanners have been optimized for images that are approximately 1280x720 pixels in size and have a continuous gray-channel. These pixel formats include SC_IMAGE_LAYOUT_GRAY_8U, SC_IMAGE_LAYOUT_YPCBCR_8U, and SC_IMAGE_LAYOUT_YPCRCB_8U.

Parameters
contextA valid context. Must not be null.
image_descriptionInput image description pointer. Must not be null.
image_dataInput image data pointer. Must not be null.
Returns
A structure holding a unique identifier for the processed frame and a process frame status code. The value of status code is:
See also
sc_barcode_scanner_get_session
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
void sc_recognition_context_end_frame_sequence ( ScRecognitionContext context)

Signal that a batch of continuous frames ended.

Use this function to indicate the end of a group of continuous frames. This function will automatically be called when the recognition context is deallocated.

Parameters
contextA valid context. Must not be null.
Since
4.6.0
Examples:
CommandLineBarcodeScannerCameraSample.c, CommandLineBarcodeScannerImageProcessingSample.c, and CommandLineMatrixScanCameraSample.c.
void sc_recognition_context_set_geographical_location ( ScRecognitionContext context,
float  latitude,
float  longitude 
)

Set the geographical location as coordinates.

This funtionality was removed in SDK 5.30. Calling this funtion does nothing.

Parameters
contextA valid context. Must not be null.
latitudedo not use
longitudedo not use
Since
4.6.0
Deprecated:
in SDK 5.30, there is no replacement.
void sc_recognition_context_set_camera_properties ( ScRecognitionContext context,
ScCameraProperties  camera_properties 
)

set the properties that define the camera that is to be used

Parameters
contextThe Recognition context. Must not be null.
camera_propertiesthe definition of the camera by default this will be SC_CAMERA_FACING_DIRECTION_UNKNOWN and and an empty string for the identifier if the identifier provided via camera_properties is not null then it must be null terminated.
Since
5.26.0

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