Classify Image

Classifies an image by comparing it to a set of sample images, assigning the image to the class with the highest similarity.

Remarks

The Classify Image command enables automated image classification by evaluating the visual similarity between an input image and a collection of user-defined sample images. This is useful for document separation, form recognition, and other scenarios where images must be grouped or routed based on their appearance.

Supported Pixel Formats

Classify Image supports both grayscale and color images. The command automatically converts the input image to the selected color space (e.g., RGB, HSV, LAB) as specified by the 'Color Space' property before extracting features. This ensures consistent feature extraction regardless of the original image format.

How the Command Works

Classify Image operates by extracting a feature vector from the input image and comparing it to feature vectors generated from each sample image in the 'Sample Images' collection. The similarity between the input and each sample is calculated using Euclidean distance or a similar metric. The image is assigned to the class with the highest similarity score, provided that the score meets or exceeds the threshold set by the 'Minimum Similarity' property. If no class meets the threshold, the value of 'Default Image Class' is used.

The feature extraction process considers both color and grayscale statistics, including channel intensities and entropy, to provide robust classification even in the presence of noise or minor variations.

Purpose and Use Cases

This command is primarily used to support conditional branching in IP Profiles, allowing Grooper to automatically execute different logic for images based on their classification. For example, to apply additional cleanup to noisy images. To use Classify Image, add an IP Step to your IP Profile that includes this command, and add a 'Next Step' expression which branches to the appropriate steps based on the detected class name.

Diagnostics Generated

When diagnostic mode is enabled, Classify Image logs the computed similarity scores for each class, the selected class name, and the feature values extracted from the input image. This information is valuable for tuning the sample set, adjusting similarity thresholds, and troubleshooting misclassifications. Diagnostic output may include log entries such as:

Class Name: Invoice (97.5%)

Source Image Features Channel 1: 0.82 Channel 2: 0.79 Channel 3: 0.80 Entropy: 6.12

Results for Trained Image Classes Invoice: 97.5% Statement: 85.2% Letter: 72.1%

Classification Features

Classify Image generates a classification result in the form of a class name, which can be used for document separation, workflow routing, or downstream processing. The classification is based on a combination of color and grayscale features, including channel intensities and entropy, providing resilience to variations in lighting, color, and document quality.

Configuration Guidance

• Add representative sample images to the 'Sample Images' collection for each class you wish to detect.
• Set the 'Minimum Similarity' property to control the strictness of classification. Higher values require a closer match.
• Choose the appropriate 'Color Space' for your documents. For most cases, RGB or LAB provide good results.
• Use the 'Default Image Class' property to specify the class name to assign when no match meets the similarity threshold.
• Enable diagnostic mode to review similarity scores and feature values, helping you refine your sample set and thresholds.

Classify Image is typically used in the early stages of a document processing workflow to automate document type detection, batch separation, or to trigger specialized processing based on image content.

Properties

Name	Type		Description
General
Sample Images	Sample Image Collection	►	The set of sample images representing each class to be detected. EditorEditor Add one or more sample images for each class you want to recognize. Each sample should be a clear, representative example of the document type, form, or object you wish to classify. The name of each sample image becomes the class label assigned to matching images. You can add, remove, or update samples using the property grid editor. For best results, use high-quality, noise-free images that capture the typical appearance of each class. Example: Add samples named Invoice, Check, and PurchaseOrder to classify incoming documents into these categories.
Minimum Similarity	Double	►	The minimum percentage of similarity required for successful image classification. ConverterPercent Converter Default85% Min0% Max100% Sets the threshold for how closely an input image must match a sample to be assigned its class label. Expressed as a decimal between 0.0 (no similarity required) and 1.0 (perfect match). If no sample meets or exceeds this threshold, the 'Default Image Class' value is used. Typical values range from 0.80 to 0.95. Configuration Tip: Lower the threshold to allow more flexible matching (risking false positives). Raise it to require stricter matches (risking more "unclassified" results). Example: Set to 0.90 to require a very strong match for classification.
Color Space	ColorSpaceType	►	The color space to use for feature extraction and comparison. DefaultRGB Can be one of the following values: Name Value Description RGB 0 RGB Color Space - Channels: Red, Green, Blue. The RGB color space represents images using three channels: Channel1: Red – Intensity of the red component. Channel2: Green – Intensity of the green component. Channel3: Blue – Intensity of the blue component. Use RGB when you want to work directly with the original color components of the image. ► HSV 1 HSV Color Space - Channels: Hue, Saturation, Value (Intensity). The HSV color space separates color information into: Channel1: Hue – The dominant color type (measured as an angle on the color wheel). Channel2: Saturation – The intensity or purity of the color. Channel3: Value – The brightness or intensity of the color. HSV is useful for isolating color features or separating color from intensity. ► LAB 2 LAB Color Space - Channels: Luminosity, A Value, B Value. The LAB color space consists of: Channel1: L (Luminosity) – Lightness, ranging from black to white. Channel2: A – Green to magenta color component. Channel3: B – Blue to yellow color component. LAB is ideal for separating lightness from color, making it useful for thresholding and feature extraction. ► YCbCr 3 YCbCr Color Space - Channels: Luma, Chroma Blue, Chroma Red. The YCbCr color space includes: Channel1: Y – Luma (brightness). Channel2: Cb – Chroma blue-difference (blue color information). Channel3: Cr – Chroma red-difference (red color information). YCbCr is commonly used in video and image compression, and is useful for separating brightness from color. ► YUV 4 YUV Color Space - Channels: Y (luma), U (chroma red), V (chroma blue). The YUV color space provides: Channel1: Y – Luma (brightness). Channel2: U – Chroma blue-difference (color information). Channel3: V – Chroma red-difference (color information). YUV is often used in television and video systems, and is effective for separating intensity from color. ► XYZ 5 XYZ Color Space - Channels: X, Y, Z. The XYZ color space consists of: Channel1: X – A mix of cone response curves (not directly visible). Channel2: Y – Luminance (perceived brightness). Channel3: Z – A mix of cone response curves (not directly visible). XYZ is a device-independent color space used as a basis for other color models. ► HLS 6 HLS Color Space - Channels: Hue, Lightness, Saturation. The HLS color space includes: Channel1: Hue – The dominant color type. Channel2: Lightness – The brightness or intensity of the color. Channel3: Saturation – The intensity or purity of the color. HLS is similar to HSV but uses lightness instead of value, and is useful for color-based feature extraction. ► Determines how color information is represented when extracting features from images. Choose a color space that best distinguishes your document types. RGB is suitable for most cases, but HSV, LAB, or others may improve accuracy for certain documents. The input image is converted to the selected color space before feature extraction. Example: Use LAB for documents where color differences are subtle but important.
Default Image Class	String	►	The value to use for the class label when no sample image meets the minimum similarity threshold. DefaultNone Specifies the class name to assign when the input image does not match any sample image closely enough. This value is returned as the classification result if no sample exceeds the 'Minimum Similarity' threshold. Use a value such as None, Unknown, or a custom label to indicate unclassified images. Example: Set to Unclassified to clearly identify images that do not match any known class.
Command Info
Command Type	String	►	The display name of this image processing command. The 'Command Type Name' property shows the user-friendly name of the IP Command as it appears in the Grooper UI. This helps users identify which command is being configured or executed, especially when working with IP Profiles containing multiple commands. This property is read-only and is automatically set based on the command's type.
Supported Pixel Formats	String	►	The pixel formats supported by this command. The 'Supported Pixel Formats' property lists the image pixel formats that the IP Command can process. If an image does not match one of these formats, the command will be skipped for that image. By default, all pixel formats are supported unless a derived command restricts this list. Example formats include Pixel8bppGrayscale, Pixel24bppBgr, and Pixel1bppIndexed. Use this property to verify compatibility when building IP Profiles or troubleshooting why a command did not execute.

See Also

Sample Image Collection

Used By

IP Step