Object Structure, Lifetime, and Disposal

This topic provides information about the following:

Recognition API Object Structure
The ImGearRecognition Object
The ImGearRecPage Object
Common Reasons to Call the Dispose Method

Recognition API Object Structure

The Recognition API uses a simple object structure with two top-level objects: ImGearRecognition, which represents the recognition engine, and ImGearRecPage, which represents a page with an associated image and recognition data. Visually, the hierarchy looks like the following:

ImGearRecognition
+ - Modules (ImGearRecModuleCollection)
| + - [] (indexer) (ImGearRecModule)
| + - MOR (ImGearRecMORSettings)
+ - Preprocessing (ImGearRecPreprocessingSettings)
+ - Recognition (ImGearRecRecognitionSettings)
| + - UserDictionary (ImGearRecUserDictionary)
+ - OutputManager (ImGearRecOutputManager)
+ - Formats (ImGearRecOutputFormatCollection)
+ - [] (indexer) (ImGearRecOutputFormat)

ImGearRecPage
+ - Image (ImGearRecImage)
+ - Statistics (ImGearRecStatistics)
+ - Zones (ImGearRecZoneCollection)
+ - [] (indexer) (ImGearRecZone)

The ImGearRecognition Object

The ImGearRecognition object represents the recognition engine. When this object is instantiated, the native recognition engine is initialized. For any additional ImGearRecognition objects that are instantiated in the same process, they will not re-initialize the recognition engine, only obtain a reference to it. The recognition engine will remain initialized until:

All references to each ImGearRecognition object instance and any associated objects cease to exist and garbage collection occurs, or
The application calls the Dispose Method for each ImGearRecognition instance.

The Dispose Method lets the application shut down the recognition engine immediately, freeing its resources. The application is responsible for not attempting to use the recognition engine after having called the Dispose Method. It is acceptable to instantiate a new ImGearRecognition object afterwards and use that object.

The ImGearRecPage Object

The ImGearRecPage object represents a page with associated image and recognition data. This object can only be instantiated by the ImportPage Method of ImGearRecognition. Resources associated with an ImGearRecPage object will continue to be in use until:

All references to the ImGearRecPage object and any associated child objects (i.e., not ImGearRecognition) cease to exist and garbage collection occurs, or
The application calls the Dispose Method.

The Dispose Method lets the application free resources associated with the ImGearRecPage object. In order to minimize resource usage, it's recommended to explicitly call this Dispose Method whenever an ImGearRecPage object is no longer needed by the application. The application is responsible for not attempting to use an ImGearRecPage object or its associated child objects after having called its Dispose Method.

Common Reasons to Call the Dispose Method

Note that, under normal circumstances, the application is not required to call a Dispose Method. The most common reasons to call this method are:

To minimize memory usage by disposing of ImGearRecPage objects that are no longer needed,
To be able to shut down and re-initialize the recognition engine.

When the application adds an ImGearRecPage object to an ImGearRecDocument object, the latter takes ownership of the internal data of ImGearRecPage object, which then becomes invalid. If the application needs to re-recognize the image that has been added to a document, it should re-import it from ImGearPage. There’s no need to dispose a page explicitly after it has been added to a document.