ScRecognitionContext Struct Reference

Public Member Functions

ScRecognitionContextsc_recognition_context_new (const char *license_key, const char *writable_data_path, JNIEnv *env, jobject activity, const char *device_name)
 
ScRecognitionContextsc_recognition_context_new (const char *license_key, const char *device_name)
 
ScRecognitionContextsc_recognition_context_new (const char *license_key, const char *writable_data_path, const char *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, const ScImageDescription *image_description, const uint8_t *image_data)
 
void sc_recognition_context_end_frame_sequence (ScRecognitionContext *context)
 
void sc_recognition_context_set_geographical_location (ScRecognitionContext *context, float latitude, float longitude)
 
ScContextStatusFlag sc_recognition_context_process_image (ScRecognitionContext *context, UIImage *image)
 

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 ( const char *  license_key,
const char *  writable_data_path,
JNIEnv *  env,
jobject  activity,
const char *  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 ( const char *  license_key,
const char *  device_name 
)

Create a new recognition context (iOS only).

Parameters
license_keyYour license key, can't be NULL.
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
ScRecognitionContext * sc_recognition_context_new ( const char *  license_key,
const char *  writable_data_path,
const char *  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,
const ScImageDescription image_description,
const uint8_t *  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.

Set the location at which the device currently is according to its location services. This is optional information, which, when provided, is transmitted to Scanalytics.

Parameters
contextA valid context. Must not be null
latitudethe latitude (north) in WGS84 coordinates.
longitudethe longitude (east) in WGS84 coordinates.

The coordinate for Zurich, Switzerland would be 47.366667, 8.55.

Since
4.6.0
ScContextStatusFlag sc_recognition_context_process_image ( ScRecognitionContext context,
UIImage *  image 
)

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.

Make sure to use sc_barcode_scanner_session_get_all_recognized_codes() when scanning barcodes, since the image may be processed multiple times and only the results of the last are available in sc_barcode_scanner_session_get_newly_recognized_codes().

Parameters
contextA valid context. Must not be null.
imageInput image. Must not be null.
Returns
the status of the recognition context.
See also
sc_barcode_scanner_get_session
Since
4.14.0

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