MclassControlEntry

• See also
User Guide:
Advanced techniques Datasets Steps to performing classification Training: in general Training: tree ensemble
Reference:
MclassAlloc MclassControl MclassImport MclassInquire MclassInquireEntry MclassSave
Availability
Not available in MIL-Lite
Available in MIL


Available on Windows
Available on Linux


Not supported on:
Not supported on Matrox Indio (Update 53 or Update 68) (w)
Not supported on Matrox Concord PoE with ToE (Update 82) (z)
Fully supported on:
Fully supported on Host system (a)
Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)
Fully supported on Matrox Morphis (g)
Fully supported on Matrox Morphis QxT (h)
Fully supported on Matrox Orion HD (i)
Fully supported on Matrox Radient eCL (j)
Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)
Fully supported on Matrox Solios eA/XA (l)
Fully supported on Matrox Solios ecl/xcl/ev-cl (m)
Fully supported on Matrox USB3 Vision driver (Update 19) (o)
Fully supported on Matrox RadientPro-CL (Update 7) (p)
Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)
Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)
Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)
Fully supported on Matrox GenTL driver (Update 34) (v)
Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)
Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)


* Refer to the MIL system-specific information
   in the MIL Reference for the minimum update required.


For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note


Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP/GPm
Available on Matrox Supersight
Function map
Examples
classcnncompletetrain.cpp
classtreeensembletrain.cpp

MclassControl
MclassCopy

Description

Parameters

DatasetContextClassId

Specifies the dataset on which to control settings. These contexts are allocated using MclassAlloc() with M_DATASET_IMAGES or M_DATASET_FEATURES.

EntryIndex

Specifies the entry to control, using the entry's index. While EntryIndex is not in use, it must be set to M_DEFAULT.

Set this parameter to one of the following values.

Note that both EntryIndex and EntryKey cannot be set to M_DEFAULT simultaneously.

For specifying the index of the entry to control
Value	Description
M_DEFAULT	Specifies that the entry index is not required. In this case, you must set the EntryKey parameter to the key (UUID) of the entry to control. (summarize) Specifies that the entry index is not required. (more details...)
Value >= 0	Specifies the index of the entry to control. In this case, you must set the EntryKey parameter to M_DEFAULT_KEY. (summarize) Specifies the index of the entry to control. (more details...)

EntryKey

Specifies the entry to control, using the entry's unique key (UUID). While EntryKey is not in use, it must be set to M_DEFAULT_KEY.

Set this parameter to one of the following values.

Note that both EntryIndex and EntryKey cannot be set to M_DEFAULT simultaneously.

For specifying the key (UUID) of the entry to control
Value	Description
M_DEFAULT_KEY	Specifies that the entry's key (UUID) is not required. In this case, you must set the EntryKey parameter to the index of the entry to control. (summarize) Specifies that the entry's key (UUID) is not required. (more details...)
MIL_UUID Value	Specifies the key (UUID) of the entry to control. In this case, you must set the EntryIndex parameter to M_DEFAULT. The key is defined as a MIL universal unique identifier (UUID). (summarize) Specifies the key (UUID) of the entry to control. (more details...)

RegionIndex

Specifies to control the entry, or to control the entry's region. Set this parameter to one of the following values.

For specifying whether to control the entry or the entry's region
Value	Description
M_DEFAULT	Specifies to control the entry. You must specify M_DEFAULT if you are using a features dataset context. (summarize) Specifies to control the entry. (more details...)
M_REGION_INDEX( MIL_INT RegionIdx )	Specifies to control the entry's region. This value only applies to an images dataset context. (summarize) Specifies to control the entry's region. (more details...)
		Parameters
		RegionIdx Set this parameter to the following:
			0 <= Value < M_NUMBER_OF_REGIONS Specifies a specific region within the entry. Note that there is always at least one region in an entry.

ControlType

Specifies the type of control to set.

See the Parameter associations section for possible values that can be specified.

ControlValue

Specifies the value for the control. If this information is not required, set this parameter to M_DEFAULT. In this case, you cannot set the ControlValuePtr parameter to M_NULL.

See the Parameter associations section for possible values that can be specified.

ControlValuePtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

• array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ]
• M_NULL
• MIL_CONST_TEXT_PTR [optionally, in C++: a reference to a MIL_STRING]

Specifies the address of the variable which contains information for the type of control to set. If this information is not required, set this parameter to M_NULL. In this case, you cannot set the ControlValue parameter to M_DEFAULT.

See the Parameter associations section for possible values that can be specified.

ControlValuePtrSize

Specifies the number of elements in ControlValuePtr. If this information is not needed, set this parameter to M_DEFAULT.

Parameter associations

The tables below list possible values for the ControlType, ControlValue, and ControlValuePtr parameters.

• For an entry in a dataset context (images or features)
• For an entry or a region of an entry in a dataset context (images or features)

To control an entry in a dataset, the ControlType and corresponding ControlValue and ControlValuePtr parameter settings can be set to the following values. In this case, set the DatasetContextClassId parameter to the identifier of either an images dataset context or a features dataset context, unless otherwise specified, and set the RegionIndex parameter to M_DEFAULT.

For an entry in a dataset context (images or features)
ControlType			Description
	ControlValue
	ControlValuePtr
M_AUGMENTATION_SOURCE			Sets whether an entry is an augmented entry, according to its index. INQ (summarize) Sets whether an entry is an augmented entry, according to its index. INQ (more details...)
	ControlValue		Specifies one of the following. (summarize) Specifies one of the following. (more details...)
		M_NOT_AUGMENTED	Specifies that the entry is not an augmented entry.
		M_UNKNOWN	Specifies that the entry is augmented, however, the original data is not known.
		Value >= 0	Specifies that the entry is augmented, and that it originates from (was performed with) the specified entry index. The entry from which the augmentation originates is considered a source or parent entry. (summarize) Specifies that the entry is augmented, and that it originates from (was performed with) the specified entry index. (more details...)
	ControlValuePtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_AUGMENTATION_SOURCE_KEY			Sets whether an entry is an augmented entry, according to its key (UUID). (summarize) Sets whether an entry is an augmented entry, according to its key (UUID). (more details...)
	ControlValue		Specifies one of the following.INQ (summarize) Specifies one of the following. INQ (more details...)
		M_NULL_KEY	Specifies that the entry is not an augmented entry.
		M_UNKNOWN_KEY	Specifies that the entry is augmented, and that the entry key (UUID) from which it was augmented is not known.
		MIL_UUID Value	Specifies that the entry is augmented, and that it originates from (was performed with) the specified key. The entry from which the augmentation originates is considered a source or parent entry. The key is defined as a MIL universal unique identifier (UUID). To specify a MIL_UUID value when using a C compiler, you must call the MIL_UUID version of this function (MclassControlEntryMilUuid). When using a C++ or other compiler, MclassControlEntry() internally calls the MIL_UUID version of this function. MIL_UUID version of MclassControlEntry void MclassControlEntryMilUuid (MIL_ID DatasetContextClassId, MIL_INT64 EntryIndex, MIL_UUID EntryKey, MIL_INT64 RegionIndex, MIL_INT64 ControlType, MIL_UUID ControlValue, const void *ControlValuePtr, MIL_INT ControlValuePtrSize) (summarize) Specifies that the entry is augmented, and that it originates from (was performed with) the specified key. (more details...)
	ControlValuePtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_ENTRY_USER_STRING			Sets a user string to store meta information. INQ (summarize) Sets a user string to store meta information. INQ (more details...)
	ControlValue		This parameter must be set to M_DEFAULT.
	ControlValuePtr		Data type info: Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Note: When using C++, you can pass a reference to a MIL_STRING instead. Specifies the following. (summarize) Data type info: Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Note: When using C++, you can pass a reference to a MIL_STRING instead. Specifies the following. (more details...)
		MIL_TEXT("String") 1	Specifies a string containing meta information. This string must not contain commas. (summarize) Specifies a string containing meta information. (more details...)
M_ENTRY_WEIGHT			Sets a weight that indicates the importance of the feature entry. This value only applies to a features dataset context. INQ (summarize) Sets a weight that indicates the importance of the feature entry. INQ (more details...)
	ControlValue		Specifies one of the following. (summarize) Specifies one of the following. (more details...)
		M_DEFAULT	Specifies the default value; the default value is 1.0.
		Value >= 0.0	Specifies the weight, as a double.
	ControlValuePtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_PATH			Sets the location from which to get the entry's image, such that M_ROOT_PATH + M_FILE_PATH gives a valid path. If M_ROOT_PATH is empty, M_FILE_PATH should be an absolute path, otherwise it should be a relative path to M_ROOT_PATH. The maximum size of the entire file path (M_ROOT_PATH + M_FILE_PATH) is 259 characters. In this case, set the DatasetContextClassId parameter to the identifier of an images dataset context. This value only applies to an images dataset context. INQ (summarize) Sets the location from which to get the entry's image, such that M_ROOT_PATH + M_FILE_PATH gives a valid path. INQ (more details...)
	ControlValue		This parameter must be set to M_DEFAULT.
	ControlValuePtr		Data type info: Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Note: When using C++, you can pass a reference to a MIL_STRING instead. Specifies one of the following. (summarize) Data type info: Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Note: When using C++, you can pass a reference to a MIL_STRING instead. Specifies one of the following. (more details...)
		MIL_TEXT("///DATASET///") 1	Specifies the path where the dataset is saved after calling MclassSave(). If this path does not exist, MIL uses the path in which your application's executable file is located. (summarize) Specifies the path where the dataset is saved after calling MclassSave(). (more details...)
		MIL_TEXT("FilePath") 1	Specifies the file path.
M_RAW_DATA			Sets an array of values (a set of features). In this case, set the DatasetContextClassId parameter to the identifier of a features dataset context. This value only applies to a features dataset context. INQ (summarize) Sets an array of values (a set of features). INQ (more details...)
	ControlValue		Specifies the following. (summarize) Specifies the following. (more details...)
		M_DEFAULT	Specifies that this parameter is not required.
	ControlValuePtr		Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] MORE Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] Required array size:(ControlValuePtrSize) Specifies the feature values. Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] MORE Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ] Required array size:(ControlValuePtrSize) Specifies the feature values.
M_USER_CONFIDENCE			Sets how confident you are in the entry's ground truth (M_CLASS_INDEX_GROUND_TRUTH). The confidence is not used in any calculations; it is for information purposes only. For example, when sharing datasets among multiple users, it can be useful to know how confident you should be of an entry's ground truth. You must decide the confidence scale to use; all confidence values should follow the chosen convention. This value only applies to an images dataset context. INQ (summarize) Sets how confident you are in the entry's ground truth (M_CLASS_INDEX_GROUND_TRUTH). INQ (more details...)
	ControlValue		Specifies one of the following. (summarize) Specifies one of the following. (more details...)
		M_DEFAULT	Specifies the default value; the default value is 0.0.
		Value	Specifies the user confidence.
	ControlValuePtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().

To control an entry or to control a region of an entry, the ControlType and corresponding ControlValue and ControlValuePtr parameter settings can be set to the following values. In this case, set the DatasetContextClassId parameter to the identifier of a dataset context and, for an images dataset context, set the RegionIndex parameter to M_REGION_INDEX() with an index of 0, and for a features dataset context, set the RegionIndex parameter to M_DEFAULT.

For an entry or a region of an entry in a dataset context (images or features)
ControlType			Description
	ControlValue
	ControlValuePtr
M_AUTHOR_NAME			Sets the author's name. INQ (summarize) Sets the author's name. INQ (more details...)
	ControlValue		This parameter must be set to M_DEFAULT.
	ControlValuePtr		Data type info: Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Note: When using C++, you can pass a reference to a MIL_STRING instead. Specifies the following. (summarize) Data type info: Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Data type: address of a MIL_CONST_TEXT_PTR [optionally, in C++: MIL_STRING ] Note: When using C++, you can pass a reference to a MIL_STRING instead. Specifies the following. (more details...)
		MIL_TEXT("Name") 1	Specifies the author's name.
M_CLASS_INDEX_GROUND_TRUTH			Sets the index of the class definition that represents the entry's ground truth. INQ (summarize) Sets the index of the class definition that represents the entry's ground truth. INQ (more details...)
	ControlValue		Specifies the following. (summarize) Specifies the following. (more details...)
		Value >= 0	Specifies the class definition index (ground truth), as an integer. Note, the index value must be less than the number of class definitions (M_NUMBER_OF_CLASSES), or you will get an error. (summarize) Specifies the class definition index (ground truth), as an integer. (more details...)
	ControlValuePtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().