MclassAlloc

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Allocate a classifier context, a dataset context, a data preparation context, a statistics classification context, or a training context.

Syntax

AIL_ID MclassAlloc(
    AIL_ID    SysId,             //in
    AIL_INT64 ContextType,       //in
    AIL_INT64 ControlFlag,       //in
    AIL_ID *  ContextClassIdPtr  //out
)

Description

This function allocates a classifier context, a dataset context, a data preparation context, a statistics classification context, or a training context on the specified system. These contexts are for anomaly detection, feature classification, image classification, object detection, or segmentation.

In general, classifier contexts and dataset contexts are for training (MclassTrain) and prediction (MclassPredict), while training contexts, dataset contexts, and data preparation contexts are for training. You can import data to, and export data from, a dataset context by calling MclassImport and MclassExport. Datasets are typically exported after they are created and imported the next time they are needed.

When a context is no longer required, release it usingMclassFree unless M_UNIQUE_ID was specified during allocation; if M_UNIQUE_ID was specified, the smart identifier manages the context's lifetime and you must not manually free it.

Parameters

SysId (in, AIL_ID)

Specifies the identifier of the system on which to allocate the context. Set this parameter to one of the following values.

For specifying the system

Value	Description
M_DEFAULT_HOST	Specifies the default Host system of the current Aurora Imaging Library application.
System identifier	Specifies a valid system identifier, previously allocated using MsysAlloc.

ContextType (in, AIL_INT64)

Specifies the type of context to allocate. Set this parameter to one of the following values.

For specifying the type of context to allocate

Value	Description
M_CLASSIFIER_ANO_PREDEFINED	Specifies a predefined anomaly detection classifier context. This is for anomaly detection. For this context, you should set the ControlFlag parameter to M_ADNET).
M_CLASSIFIER_CNN_PREDEFINED	Specifies a predefined CNN classifier context. This is for image classification. For this context, you should typically specify a specific CNN classifier that Aurora Imaging has built (that is, set the ControlFlag parameter to M_ICNET_...).

CNN and image classification are used interchangeably unless otherwise specified. | | M_CLASSIFIER_DET_PREDEFINED | Specifies a predefined object detection classifier context. This is for object detection. For this context, you should set the ControlFlag parameter to M_ODNET). | | M_CLASSIFIER_ONNX | Specifies an ONNX classifier context. For this context, do not specify a specific classifier that Aurora Imaging has built (that is, set the ControlFlag parameter to M_DEFAULT).

ONNX is an open-source machine learning format that you can use to create a classifier model. When you allocate an ONNX classifier context, you typically import a trained ONNX classifier model into it, and then predict with it MclassPredict. The type of classification that is performed depends on the ONNX classifier that you created and trained prior to importing it. | | M_CLASSIFIER_SEG_PREDEFINED | Specifies a predefined segmentation classifier context. This is for segmentation. For this context, you should typically specify a specific segmentation classifier that Aurora Imaging has built (that is, set the ControlFlag parameter to M_CSNET_...). | | M_CLASSIFIER_TREE_ENSEMBLE | Specifies a tree ensemble classifier context. This is for feature classification. For this context, do not specify a specific classifier that Aurora Imaging has built (that is, set the ControlFlag parameter to M_DEFAULT).

Tree ensemble and feature classification are used interchangeably unless otherwise specified. | | M_DATASET_FEATURES | Specifies a features dataset context.

This context is for feature classification; it holds the feature data with which to train a tree ensemble classifier (M_CLASSIFIER_TREE_ENSEMBLE). | | M_DATASET_IMAGES | Specifies an images dataset context.

This context (dataset) is for image classification, segmentation, object detection, or anomaly detection; it holds the image data with which to train a CNN classifier (M_CLASSIFIER_CNN_PREDEFINED), a segmentation classifier (M_CLASSIFIER_SEG_PREDEFINED), an object detection classifier (M_CLASSIFIER_DET_PREDEFINED), or an anomaly detection classifier (M_CLASSIFIER_ANO_PREDEFINED). Image classification and segmentation support buffers with up to 1024 bands.

You can also use an images dataset context with MclassPredict to label images in an existing dataset (assisted labeling). | | M_PREPARE_IMAGES_CNN | Specifies a CNN data preparation context.

This context is for image classification; it holds the settings with which to prepare images for CNN training or prediction (for example, cropping, resizing, or augmenting), using MclassPrepareData. | | M_PREPARE_IMAGES_DET | Specifies an object detection data preparation context.

This context is for object detection; it holds the settings with which to prepare images for object detection training or prediction (for example, cropping, resizing, or augmenting), using MclassPrepareData. | | M_PREPARE_IMAGES_SEG | Specifies a segmentation data preparation context.

This context is for segmentation; it holds the settings with which to prepare images for segmentation training or prediction (for example, cropping, resizing, or augmenting), using MclassPrepareData. | | M_STAT_ANO | Specifies a statistics classification context for anomaly detection. This context holds the settings for which to calculate statistics on a dataset using MclassStatCalculate. | | M_STAT_CNN | Specifies a statistics classification context for image classification. This context holds the settings for which to calculate statistics on a dataset using MclassStatCalculate. | | M_STAT_DET | Specifies a statistics classification context for object detection. This context holds the settings for which to calculate statistics on a dataset using MclassStatCalculate. | | M_STAT_SEG | Specifies a statistics classification context for segmentation. This context holds the settings for which to calculate statistics on a dataset using MclassStatCalculate. | | M_STAT_TREE_ENSEMBLE | Specifies a statistics classification context for feature classification. This context holds the settings for which to calculate statistics on a dataset using MclassStatCalculate. | | M_TRAIN_ANO | Specifies an anomaly detection training context.

This context is for anomaly detection; it holds the training settings with which to train an anomaly detection classifier context, using MclassTrain. | | M_TRAIN_CNN | Specifies a CNN training context.

This context is for image classification; it holds the training settings with which to train a CNN classifier context, using MclassTrain. | | M_TRAIN_DET | Specifies an object detection training context.

This context is for object detection; it holds the training settings with which to train an object detection classifier context, using MclassTrain. | | M_TRAIN_SEG | Specifies a segmentation training context.

This context is for segmentation; it holds the training settings with which to train a segmentation classifier context, using MclassTrain. | | M_TRAIN_TREE_ENSEMBLE | Specifies a tree ensemble training context.

This context is for feature classification; it holds the training settings with which to train a tree ensemble classifier context, using MclassTrain. |

ControlFlag (in, AIL_INT64)

Specifies the predefined classifier to use. These classifiers are built by Aurora Imaging; you cannot modify their underlying architecture. If you are not allocating a predefined classifier context, set this parameter to M_DEFAULT.

For specifying no predefined classifier

Value	Description
M_DEFAULT	Specifies no predefined classifier context.

Note: M_DEFAULT is the only possible setting if you are not allocating a predefined classifier context.

If you specify M_DEFAULT when allocating a predefined classifier context (M_CLASSIFIER_CNN_PREDEFINED, M_CLASSIFIER_DET_PREDEFINED, M_CLASSIFIER_ANO_PREDEFINED, or M_CLASSIFIER_SEG_PREDEFINED), you cannot directly train that classifier. In this case, you would typically copy a resulting trained classifier into that context (MclassCopyResult). |

For specifying a predefined CNN classifier

Value	Description
M_ICNET_COLOR_XL	Specifies an extra large ICNet classifier context that is for color images. This corresponds to the ICNET_COLOR_XL.mclass context file that Aurora Imaging Library installed.

This classifier is intended for transfer learning. It has a recommended minimum receptive field of 195 pixels. You must use color (3-band) images with this classifier. | | M_ICNET_M | Specifies a medium ICNet classifier context. This corresponds to the ICNET_M.mclass context file that Aurora Imaging Library installed.

This classifier is for a complete training. It has a recommended minimum receptive field of 83 pixels. You can use images with up to 1024 bands (N-band) with this classifier. | | M_ICNET_MONO_XL | Specifies an extra large ICNet classifier context that is for monochrome images. This corresponds to the _ ICNET_MONO_XL.mclass_ context file that Aurora Imaging Library installed.

This classifier is intended for transfer learning. It has a recommended minimum receptive field of 195 pixels. You must use grayscale (1-band) images with this classifier. | | M_ICNET_S | Specifies a small ICNet classifier context. This corresponds to the ICNET_S.mclass context file that Aurora Imaging Library installed.

This classifier is for a complete training. It has a recommended minimum receptive field of 43 pixels. You can use images with up to 1024 bands (N-band) with this classifier. | | M_ICNET_XL | Specifies an extra large ICNet classifier context. This corresponds to the ICNET_XL.mclass context file that Aurora Imaging Library installed.

This classifier is for a complete training. It has a recommended minimum receptive field of 195 pixels. You can use images with up to 1024 bands (N-band) with this classifier. |

For specifying a predefined anomaly detection classifier

Value	Description
M_ADNET	Specifies an ADNet classifier context. This corresponds to the ADNET.mclass context file that Aurora Imaging Library installed.

This classifier is for a complete training. |

For specifying a predefined object detection classifier

Value	Description
M_ODNET	Specifies an ODNet classifier context. This corresponds to the ODNET.mclass context file that Aurora Imaging Library installed.

This classifier is for a complete training. You cannot use float images with this classifier. Note, the receptive field concept does not apply to object detection. |

For specifying a predefined segmentation classifier

Value	Description
M_CSNET_COLOR_XL	Specifies an extra large CSNet classifier context that is for color images. This corresponds to the CSNET_COLOR_XL.mclass context file that Aurora Imaging Library installed.

This classifier is intended for transfer learning. It has a minimum receptive field of 195 pixels that increases in step sizes of 32 pixels. You must use color (3-band) images with this classifier. | | M_CSNET_M | Specifies a medium CSNet classifier context. This corresponds to the CSNET_M.mclass context file that Aurora Imaging Library installed.

This classifier is for a complete training. It has a minimum receptive field of 83 pixels that increases in step sizes of 8 pixels. You can use images with up to 1024 bands (N-band) with this classifier. | | M_CSNET_MONO_XL | Specifies an extra large CSNet classifier context that is for monochrome images. This corresponds to the CSNET_MONO_XL.mclass context file that Aurora Imaging Library installed.

This classifier is intended for transfer learning. It has a minimum receptive field of 195 pixels that increases in step sizes of 32 pixels. You must use grayscale (1-band) images with this classifier. | | M_CSNET_S | Specifies a small CSNet classifier context. This corresponds to the _ CSNET_S.mclass_ context file that Aurora Imaging Library installed.

This classifier is for a complete training. It has a minimum receptive field of 43 pixels that increases in step sizes of 4 pixels. You can use images with up to 1024 bands (N-band) with this classifier. | | M_CSNET_XL | Specifies an extra large CSNet classifier context. This corresponds to the CSNET_XL.mclass context file that Aurora Imaging Library installed.

This classifier is for a complete training. It has a minimum receptive field of 195 pixels that increases in step sizes of 32 pixels. You can use images with up to 1024 bands (N-band) with this classifier. |

ContextClassIdPtr *(out, AIL_ID)

Specifies the address of the variable in which to write the classifier, dataset, data preparation, or training context identifier or specifies the data type that the function should use to return the context identifier.

For retrieving the identifier or specifying how to return it

Value	Description
M_NULL	Specifies that you will use this function's return value to obtain the identifier of the allocated classifier, dataset, data preparation,

                          statistics classification, or training context ; in this case, a standard Aurora Imaging Library identifier of type _AIL_ID_ is returned. |

| M_UNIQUE_ID | Specifies that you will use this function's return value to obtain the identifier of the allocated classifier, dataset, data preparation, statistics classification, or training context ; in this case, an Aurora Imaging Library smart identifier of type _AIL_UNIQUE_CLASS_ID_is returned instead of a standard Aurora Imaging Library identifier.This setting is only available when using C++11 (or later).An Aurora Imaging Library smart identifier manages the lifespan of the Aurora Imaging Library object it owns (similar to a std::unique_ptr). Note, you can use an Aurora Imaging Library smart identifier as though it were a standard Aurora Imaging Library identifier, except that you cannot use it to manually free the classifier, dataset, data preparation, statistics classification, or training context (it is freed automatically). For more information, see Aurora Imaging Library smart identifiers. | | Address in which to write the classifier context identifier | Specifies the address of an AIL_ID in which to write the identifier of the allocated classifier context.

If allocation fails, M_NULL is written as the identifier. | | Address in which to write the data preparation context identifier | Specifies the address of an AIL_ID in which to write the identifier of the allocated data preparation context.

If allocation fails, M_NULL is written as the identifier. | | Address in which to write the dataset context identifier | Specifies the address of an AIL_ID in which to write the identifier of the allocated dataset context.

If allocation fails, M_NULL is written as the identifier. | | Address in which to write the statistics classification context identifier | Specifies the address of an AIL_ID in which to write the identifier of the allocated statistics classification context.

If allocation fails, M_NULL is written as the identifier. | | Address in which to write the training context identifier | Specifies the address of an AIL_ID in which to write the identifier of the allocated training context.

If allocation fails, M_NULL is written as the identifier. |

Return Value

Type: AIL_ID

The returned value is the classifier context identifier either as a standard identifier (AIL_ID) or a smart identifier (AIL_UNIQUE_CLASS_ID). If allocation fails, M_NULL is returned (or nullptr ifM_UNIQUE_ID was specified).

When you allocate a classifier context, you must usually train it (MclassTrain) before predicting with it (MclassPredict).

For this context, do not specify a specific classifier that Aurora Imaging has built (that is, set the ControlFlag parameter to M_DEFAULT).