Welcome

Welcome to the mViz Machine Vision Library. mViz is a comprehensive set of image processing and analysis tools tailored for use in machine vision applications. It was designed to reduce the learning curve and development time of your cases.

You will find functions for image enhancement, parts location, features detection and description and classification, gauging, and many more. Emphasis has been put on ease of use and speed of computation.

You will also find complete tools for mark reading and inspection.

After installation, all the mViz files are found in the subfolder mViz Files of your Documents Folder.


What mViz does for you

mViz supports various image transformations such as enhancement, object segmentation, feature extraction, pattern recognition and location, which are done in real-time. These operations perform a strong reduction in the amount of information contained in the image and are used to make decisions, drive actuators and raise alarms.

This allows automating the manufacturing process and implementing statistical process control. Typical applications include inspection, robot guidance and part identification.

mViz focuses on the image processing steps. It uses a small number of data containers to store 2D images, 1D signals and the like.


Main Features

Here is an overview of the functionalities of mViz, encapsulated in rich and powerful classes.

Containers

Containers are simple entities that hold image and shape related data.

Image: image container, 2D data

Profile: signal container, 1D data

Path: polyline or polygon, outline of a shape

Poly: polyline or polygon, outline of a shape, with real coordinates

Region: shape area or region descriptor

Pyramid: multi-resolution processing

Image processing

Image processing designates functions that transform images into other images by eliminating unwanted features such as noise or enhancing features such as contrast.

Operator: arithmetic with images and other point-to-point operations, including conversions and shading correction

Kernel: convolutions, linear filtering

Morpho: mathematical morphology, non-linear filtering, image segmentation

Geometry: geometric transformations and calibration

Image analysis

Image analysis extracts condensed information from an image by characterizing regions of the image and computing their properties.

Histogram: pixel statistics

Blobs: blob analysis

FeatureTable: by-range feature classification

Classifier: distance-based classifier

EdgeMap: edge detection and vectorization

Alignment

Alignment is helpful to locate known objects as accurately as possible and define regions of interest where inspection is relevant.

EdgePoint, EdgeLine, EdgeArc, EdgeEllipse, EdgeRectangle: gauging

Locator: template matching

ShapeMatcher: outline-based template matching

Identification

Part identification for tracking and traceability can be based on human readable text, barcodes or 2-dimensional code such as Data Matrix.

CharReader: optical character recognition.

Code1DReader: linear code decoding (barcode).

Code2DReader: bidimensional code decoding (Data Matrix).

Inspection

Geometric control of parts or assemblies.

SnakeGauge: measurement device for complex outlines or tapes.

3D Inspection

Geometric control of parts or assemblies from 3D data capture, point clouds or point meshes.

PointCloud: representation and storage of clouds and meshes.

CloudInspector: comparison of 3D shapes after realignment for pose control and defect detection.

Miscellaneous

Quad: flexible geometric shape to define regions.

Graph: graphics drawing utilities.

Status: error processing and others.


Object-oriented Design

mViz is built from a small number of C++ classes that each relate to an application area of machine vision. Those classes have a number of methods to implement the operations of image processing and analysis.

Many of the methods are static, they don't require a class instance. When classes are instantiated, they have properties that can be read-write (user-adjustable) or read-only (processing results).

Example:

C++ Native

       // Class: declare a void image object

       Image MyImage;

       // Method: read from a file

       MyImage.Read("Source.bmp");

       // Properties: retrieve the size

       int Area= MyImage.Width * MyImage.Height;

       // Static method: invert in-place

       Operator::Invert(MyImage, MyImage);

C++.NET using namespace mVizNET;

       // Class: declare a void image object

       Image^ MyImage= gcnew Image;

       // Method: read from a file

       MyImage->Read("Source->bmp", PixelTypes::Gray);

       // Properties: retrieve the size

       int Area= MyImage->Width * MyImage->Height;

       // Static method: invert in-place

       Operator::Invert(MyImage, MyImage);

C# using mVizNET;

       // Class: declare a void image object

       Image MyImage = new Image();

       // Method: read from a file

       MyImage.Read("Source.bmp", PixelTypes.Gray);

       // Properties: retrieve the size

       int Area = MyImage.Width * MyImage.Height;

       // Static method: invert in-place

       Operator.Invert(MyImage, MyImage);

Visual Basic

       ' Class: declare a void image object

       Dim MyImage As mVizNET.Image = New mVizNET.Image

       ' Method: read from a file

       MyImage.Read("Source.bmp", mVizNET.PixelTypes.Gray)

       ' Properties: retrieve the size

       Dim Area As Integer = MyImage.Width * MyImage.Height

       ' Static method: invert in-place

       mVizNET.Operator.Invert(MyImage, MyImage)

Optimization Hint

The mViz objects require dynamically allocated memory for data storage purposes. When processing has been made, the objects retain this memory so that it doesn’t need to be reallocated the next time. For this reason, the next executions can be faster.

So it is advisable to keep the objects throughout program life span, instead of creating/destroying instances each time. It is even beneficial to pre-initialize these objects by doing a blank run before starting real-time operation.

Caution

The mViz objects have no copy constructors nor assignment operators. You may not copy the objects, or heap allocation errors can arise.

- Do not assign,

- Do not pass as argument by value, pass by reference instead.


Licensing

The mViz modules are licensed for a given machine, separately by modules, with the following correspondence:

Module | Classes
Image Processing | Profile, Operator , Kernel, Morpho, Geometry (transforms) , Pyramid
Image Analysis | Histogram , Path, Blobs, EdgeMap, Classifier
Pattern Matching | Locator (standard)
Geometric Matching | Locator (edges), ShapeMatcher (outlines), Comparator (defect detection)
Image Calibration | Geometry (fitting)
Edge Gauging | EdgePoint, EdgeLine, EdgeArc, EdgeEllipse, EdgeRectangle
Inspection | SnakeGauge
Character Reading | CharReader
Bar Code Reading | Code1DReader
Dot Code Reading | Code2DReader
Print Verification | CharReader, Code1DReader and Code2DReader
3D Inspection | PointCloud, CloudInspector


Dongle-less protection (hardware-based)

The licenses can be assigned to a specific computer. No additional hardware key is required, as the software will recognize that particular machine.

The license granting procedure requires three steps:

1. The user runs the utility program "mViz Access" on the targeted machine, saves a Signature file (.csv) file using FilesàLicensesàSave Signature and sends it to his reseller;

2. The reseller sends back a License file (.reg) for this machine and the requested modules;

3. The user registers the license file on the targeted machine by double-clicking the file.

PC + mViz Access à Signature File (.csv)

License File (.reg) ß Signature File

PC + License File à PC is enabled

If the user wishes to upgrade to a new version of the library, he simply has to install the new files.

Major mViz versions require a new license, not minor ones.


Dongle-based protection

As an alternative to the machine Signature procedure, the licenses can also be recorded on a hardware key (dongle). By plugging the key to a USB port of any machine, licenses are instantly granted. The dongle uses a DLL that must be installed. This is performed by the mViz .msi installer. Manual copying is also possible.

Both dongle-less and on-dongle license sets can be upgraded at any time and remotely.

On Linux machines, the applications must be run with root privilege for the dongle to be detected.


Utility Programs

mViz features an important prototyping workbench called mViz+. It will let you try the mViz functions in real-time (showing the immediate effect of the parameter changes, create complete processing chains and see the changes across the chain. In addition, mViz+ handles program variables for you and will generate source code automatically, ready for use. See the section “What mViz+ does for you”.

mViz OCR is a training utility useful for OCR applications. It helps you create custom Font files and adjust text detection and recognition in a convenient way.

mViz Code2D is an optimization utility for 2D code reading. It helps you handle difficult codes by tuning the processing parameters for your set of images.

mViz Snake is a workbench letting you interactively draw a snake object and set its characteristics. After saving the snake description, you can reload it in other applications and use it straight away.

mViz 3D is a test bench for 3D applications. It lets you load 3D points clouds and meshes from external files, an perform registration then comparison. You can save a reference 3D model for later reuse.

mViz Access is used to seize the signature of the targeted machine or dongle, before a license is granted for it. The signature file it generates is intended for VISION fOr VISION’s Technical Support.


Sample Programs

A number of ready-made example programs can be found in the Documents\mViz Files\Samples … folders, together with the compiled libraries and sample images.

  • GettingStarted: this is a very simple example of using mViz under Windows Forms.
  • Console: a very simple example showing mViz in a console application.
  • Binarize: simple image binarization by thresholding
  • BlobAnalysis: basic blob analysis, blob detection
  • BlobSelect: blob selection and feature computation
  • Classify: using the classifier to sort objects by comparison to references
  • ColorBinarize: binarization of a color image using two reference colors
  • ColorSegment: segmentation of an image based on color differences
  • DataMatrix: reading a 2D code independently of size and orientation.
  • FreehandROI: defining a hand-drawn region of interest for blob detection
  • ImageAnalysis: computation of a few histogram-based features
  • ImageCalibration: fine geometric calibration with distortion removal
  • ImageProcessing: implementation of a few processing filters
  • InspectCompare: defect detection using the Comparator tool
  • LineGauging: precise dimensional measurement using a line gauge
  • Locate: basic pattern matching: pattern training and searching
  • MatchShape: perform pattern matching based on a simple outline
  • PatternMatching: perform pattern matching based on area or edges
  • PolygonalROI: defining and editing a polygon for ROI definition
  • PrintInspection: reading different markings: barcode, 2D code, ORC.
  • 3DCompare: comparison of a 3D mesh to a reference model, with registration

All projects were built for Visual Studio 2008, 2010, 2012, 2013, 2015, 2017, 2019 and 2022.

These samples are available for the Native C++ platform. Most of them also for C++/CLI (.NET), C# and Visual Basic.


Compiling and Linking

mViz is interfaced to the .NET Framework (as a managed class library) and can also be used as a native (Unmanaged) C++ library.


64 or 32 bits

mViz comes in two precompiled versions, targeting the 64 and 32 bits processors (x86 and x64 architectures), available for all supported Microsoft compilers. A 32/64 suffix appended to the filenames distinguishes between them.

To avoid incompatibilities, all Sample applications are set by default for the 64 bits (x64) Platform, using the mViz64.lib Library or the mVizNET64.dll Assembly. For 32 bits builds under .NET, the mVizNET32.dll Assembly must be manually unzipped. The sample programs may have to be retargeted.

For users willing to stay in the 32 bits model, the rules below apply. Note that applications built for 32 bits will also run under 64 bits Windows, using the WOW64 subsystem.

For native C++ development, the project files include x86/Win32 Configurations. Just select them in the Configuration Manager of Visual Studio.

For .NET applications, the “AnyCPU” model cannot be supported as there needs to be distinct Assemblies for different Platforms. The project files include x64 Configurations only. To target the x86 Platform, after creating the corresponding Configuration in the Configuration Manager, the Reference to the mViz Assembly has to be changed from mVizNET64.dll to mVizNET32.dll in the project properties. The assembly mVizNET32.dll is found in the zip archive NETnn\x32.zip.

Here is a summary of the options on a 64 bits version of Windows:

Application | Visual Studio Configuration | Static library | .NET assembly | Predefined Sample projects
32 bits | x86 | mViz32.lib | mVizNET32.dll | Native
64 bits | x64 | mViz64.lib | mVizNET64.dll | Native, .NET
32/64 bits [1] | AnyCPU | mViz32/64.lib | mVizNET32/64.dll | -

[1] .NET applications built for the AnyCPU platform will only operate if the appropriate .NET Assembly has been selected as a project Reference.


.NET languages

For the Visual Basic, C# or C++.NET applications, add the mVizNET Reference by browsing to the file mVizNET64.dll in the folder My Documents\mViz Files\NET35.

This DLL was built to target the .NET Framework 3.5. This should not bring about compatibility issues with applications targeting later frameworks. Anyway, versions built for the Frameworks 4.0 and 4.6 are also available.

All mViz identifiers belong to the mVizNET namespace.

C++ Native

       No prefix

C++.NET using namespace mVizNET;

       using namespace mVizNET;

C# using mVizNET;

       using mVizNET;

Visual Basic

       Prefix all identifiers with mVizNET

If this solution is unsuitable for you, please contact the technical support.

Caution: when upgrading from one version of mViz to another, make sure to overwrite any copy of mVizNETnn.dll that might have been saved by the Visual Studio IDE or re-register the reference.


Native C++

The header file is found in My Documents\mViz Files\Include. The precompiled libraries are respectively found in My Documents\mViz Files\VC2008 (2010, 2012, 2013, 2015, 2017, 2019 or 2022).

The compilation/linking settings in use are the same as for a standard Windows Forms Application project created from scratch, with the following two exceptions.

When creating a project with the Visual Studio wizard, you will have to allow linking to the Win32 libraries. This is done by removing the $(NoInherit) default setting from Configuration Properties/Linker à Input à Additional Dependencies.

Also verify that the Configuration Properties/General à Common Language Runtime Support is set to /clr (neither pure nor safe) as the library is compiled as native.

The header file "mViz.h" must be included and its containing folder will be found in the search path to include files. To perform that :

· choose an explicit path in the #include directive,

· or set the Additional Include Directories (/I) in the C/C++ Configuration Properties,

· or add an Include Directory in the Projet/VC++ Directories of the Tools/Options….

The library file “mViz64.lib” or “Viz64D.lib” must be added and its containing folder can be found in the search path for library files. To do that :

· modify the #pragma comment(lib) declaration,

· or add the files as Additional Dependencies in the Linker/Input Configuration Properties;

and :

· specify an explicit path,

· or set the Additional Include Directories (/I) in the Linker/General Configuration Properties,

· or add a Library Directory in the Projet/VC++ Directories of the Tools/Options….

The Run-Time Library model in use as C/C++/Code Generation in the Configuration Properties is Multi-threaded DLL (/MD) or Multi-threaded Debug DLL (/MDd).


With other compilers or with other settings


Visual C++ 6.0

The Visual C++ 6.0 compiler is no more supported as a standard. If you need it contact the technical support.


Visual C++ 2003 and 2005

The Visual Studio 2003 and 2005 compilers are no more supported as a standard. If you need one of them contact the technical support.


Linux and gcc

Linux/gcc compatible versions are available. Ports to other environments are possible on request.

In addition to the standard header mViz.h, the delivery includes the static library files libmViz.a (Relese build) and libmVizd.a (Debug build) and libSecureDongle.a. (The usual place to copy them is /usr/lib/x86_64-linux-gnu.) Link with the options -lmViz and -lmVizd respectively, plus -lSecureDongle. Make sure that the linker can find these files where you copied them, possibly using a -L option.

The library can be delivered in different versions:

- with or without graphics support; the graphics support is based on Xlib, and the application is responsible to pass a handle to the desired drawable entity. (Install libX11-dev, for example using apt install; link with -lX11.)

- with or without support for the "heavy" file formats (PNG, TIFF and JPEG). If support is wanted, you will have to install the corresponding libraries separately (libpng-dev, libtiff-dev and libjpeg-dev, for example using apt install; link with -lpng -ltiff -ljpeg).

Please contact the technical support using techsupport@visionforvision.eu for details.

In order to use the USB dongles on a Linux PC, you will have to copy the dongle driver libSecureDongle.so to /usr/lib/x86_64-linux-gnu.

IMPORTANT: for the dongles to be detected, an application must run with the root privilege.


How We Can Improve this Manual

Please tell us about any errors you find, problems you meet using the manual, or other comments that can help us improve future versions. Send us an e-mail at techsupport@visionforvision.eu.


What mViz+ does for you

mViz+ is a powerful prototyping workbench that exposes most of the features in mViz and lets you play with the functions. It is menu-driven and highly interactive. You will notice that it allows you to adjust the parameters and see the changes in real-time.

mViz+ builds a processing chain, using mViz objects that are passed from one function to the next. It intelligently creates the required variables and parameters.

The example below shows how to load a color image, convert it to hue information, binarize it and obtain the convex hull of some blob.

A source image

A chain of operations with timing

The resulting image and the convex hull of a blob (in red)

Simultaneously, the operations are performed, they are timed, giving you an overview of the processing performance.

In addition, mViz+ builds the corresponding source code, in your preferred .NET programming language.

    '
Declarations
Dim Image0 As
mVizNET.Image
Dim Converted0 As
mVizNET.Image
Dim Blobs0 As
mVizNET.Blobs
Dim ConvexHulled1 As
mVizNET.Path

' Constructions
Image0 = New mVizNET.Image
Converted0 = New mVizNET.Image
Blobs0 = New mVizNET.Blobs
ConvexHulled1 = New mVizNET.Path

' Read from File (Image)
Image0.Read("C:\\Users\\User\\Documents\\mViz
Files\\Images\\ColorTarget.bmp", mVizNET.PixelTypes.Rgb)

' Convert Image (Operator)
mVizNET.Operator.Convert(Image0, Converted0, mVizNET.ColorComponents.Blue_RGB)

' Threshold (Blobs)
int(Segment0 = Blobs0.Segment(121, Converted0, False, True, 256))

' Convex Hull (Blobs)
Blobs0.ConvexHull(6, Converted0, ConvexHulled1)


Images

In mViz, image bitmaps are stored and manipulated by instances of the Image class.

A grayscale image

Images are the first class objects in mViz. In most machine vision applications, they are grayscale with 8 bits depth (256 gray-levels). Less often they are color RGB (3x8 bits depth) or binary (a single bit per pixel). A few other types are supported, including 16 bits grayscale, for specific applications.

Remember that the main emphasis is on 8 bits grayscale. The fact is that color information is often irrelevant in industrial vision, except for very specific reasons, and high accuracy isn't required/available.

A color image conveying color information

Example:

C++ Native

       // Declare a void image object

       Image Src;

C++.NET using namespace mVizNET;

       // Declare a void image object

       Image^ Src= gcnew Image;

C# using mVizNET;

       // Declare a void image object

       Image Src = new Image();

Visual Basic

       ' Declare a void image object

       Dim Src As mVizNET.Image

An image is a rectangle having Width pixels horizontally and Height pixels vertically (collectively, Size). By default, the pixels are encoded as unsigned 8 bits integers, i.e. in the range 0 to 255 inclusive (black to white). This type of pixel is known as Gray. The size of the image can be specified using the method Set.

Example:

C++ Native

       // Size the whole image as 640 x 480

       Src.Set(640, 480);

C++.NET using namespace mVizNET;

       // Size the whole image as 640 x 480

       Src->Set(640, 480, PixelTypes::Gray, (IntPtr)0, 0, 0);

C# using mVizNET;

       // Size the whole image as 640 x 480

       Src.Set(640, 480, PixelTypes.Gray, (IntPtr)0, 0, 0);

Visual Basic

       ' Size the whole image as 640 x 480

       Src.Set(640, 480, mVizNET.PixelTypes.Gray, 0, 0, 0)

Individual image pixels can be accessed for reading or changing the value by means of the PixelGray method to which pixel coordinates are passed.

Example:

C++ Native

       // Set to white

       Src.PixelGray(10, 10)= 255;

C++.NET using namespace mVizNET;

       // Set to white

       Src->PixelGray(10, 10, 255);

C# using mVizNET;

       // Set to white

       Src.PixelGray(10, 10, 255);

Visual Basic

       ' Set to white

       Src.PixelGray(10, 10, 255)

In various circumstances, it makes sense to limit processing to a rectangular region of interest, by specifying the coordinates of its top left corner and its size. This is done via the method Window.

Image window

Example:

C++ Native

       // Use a centered 128 x 128 region of interest

       Src.Window(256, 176, 128, 128);

       // More code...

       // Revert to the full image

       Src.Window();

C++.NET using namespace mVizNET;

       // Use a centered 128 x 128 region of interest

       Src->Window(256, 176, 128, 128);

       // More code...

       // Revert to the full image

       Src->Window();

C# using mVizNET;

       // Use a centered 128 x 128 region of interest

       Src.Window(256, 176, 128, 128);

       // More code...

       // Revert to the full image

       Src.Window();

Visual Basic

       ' Use a centered 128 x 128 region of interest

       Src.Window(256, 176, 128, 128)

       ' More code...

       ' Revert to the full image

       Src.Window()

An image can be loaded from or saved to an external disk file. The Windows Bitmap file format (*.bmp) is used for this purpose. The corresponding methods are Read and Write respectively. They allow specifying the file path and name using either the Ascii or Unicode character sets.

Additionally, formats known as JPEG - Joint Photographic Experts Group (*.jpg), PNG - Portable Network Graphics (*.png), TIFF – Tagged Image File Format (*.tif), or PGM/PPM - Portable GrayMap / Portable PixMap (*.pgm/*.ppm) can also be loaded.

Example:

C++ Native

       // Load the Bitmap image

       Src.Read(L"C:\\イメージズ\\テスト.bmp");

C++.NET using namespace mVizNET;

       // Load the Bitmap image

       Src->Read(L"C:\\イメージズ\\テスト.bmp", PixelTypes::Undefined);

C# using mVizNET;

       // Load the Bitmap image

       Src.Read("C:\\イメージズ\\テスト. bmp", PixelTypes.Undefined);

Visual Basic

       ' Load the Bitmap image

       Src.Read("C:\\イメージズ\\テスト. bmp", mVizNET.PixelTypes.Undefined)

An image is displayed on the application window with method Draw. Zooming is supported via the global property Graph::Zoom. If required, another drawing window (under MS Windows, a GDI Device Context) can be chosen by means of Graph::DrawTo.

Example:

C++ Native

       // Display with a twofold magnification

       Graph::Zoom= 2;

       Src.Draw();

C++.NET using namespace mVizNET;

       // Display with a twofold magnification

       Graph::Zoom= 2;

       Src->Draw(false);

C# using mVizNET;

       // Display with a twofold magnification

       Graph.Zoom = 2;

       Src.Draw(false);

Visual Basic

       ' Display with a twofold magnification

       mVizNET.Graph.Zoom = 2

       Src.Draw(False)

Reference:

Image::Set, Image::Size,
Image::PixelGray, Image::Window, Image::Read,
Image::Write, Image::Draw,
Graph::Zoom,
Graph::DrawTo.


Accessing the image buffer

Usually, the image pixels are stored in an area of memory which is transparently allocated/deallocated by the Image object. The user can directly access this data from the property named Buffer. Pixels are stored contiguously, row by row, top to bottom. Every image row has exactly Pitch bytes of data. Padding bytes are used if needed.

Example:

C++ Native

       // Output the buffer parameters

       printf("Address: 0x%08x - Pitch: %d\n", Src.Buffer, Src.Pitch);

C++.NET using namespace mVizNET;

       // Output the buffer parameters

       Console::WriteLine(String::Format("Address: {0:x8}x - Pitch: {1}", int(Src->Buffer), Src->Pitch));

C# using mVizNET;

       // Output the buffer parameters

       Console.WriteLine(String.Format("Address: {0:x8}x - Pitch: {1}", (int)Src.Buffer, Src.Pitch));

Visual Basic

       ' Output the buffer parameters

       Console.WriteLine(String.Format("Address: {0:x8}x - Pitch: {1}", Src.Buffer, Src.Pitch))

The user doesn’t need to care about internal storage. Anyway, in case he wants to, access to the pixel data is direct.

The general formula to compute the starting address of the pixel at coordinates (X, Y) is Buffer + Y Pitch + X PixelSize, in bytes. PixelSize is 1 for Gray, 2 for Gray16, 3 for Rgb and 4 for Rgba; Gray1 is a bit-packed format.


Advanced: Using an external image buffer

If wished, the user can provide an external buffer that keeps the image data and specify the appropriate pitch value. This is a common requirement when dealing with image acquisition devices.

Example:

C++ Native

       // Use an external data buffer

       byte BitmapData[640 * 480];

       Src.Set(640, 480, Gray, BitmapData, 640);

C++.NET using namespace mVizNET;

       // Use an external data buffer

       unsigned char BitmapData[640 * 480];

       Src->Set(640, 480, PixelTypes::Gray, (IntPtr)BitmapData, 640, 0);

C# using mVizNET;

       // Use an external data buffer (unsafe code)

       byte[] BitmapData = new byte[640 * 480];

       fixed (byte* Data = &BitmapData[0])

       {

           Src.Set(640, 480, PixelTypes.Gray, (IntPtr)Data, 640, 0);

       }

Visual Basic

       ' Use an external data buffer

       Dim BitmapData(640 * 480) As Byte

       Src.Set(640, 480, mVizNET.PixelTypes.Gray, BitmapData(0), 640, 0)

Important: mViz complies with the bitmap format used in the Windows operating system. That means that grayscale images are stored as contiguous bytes (or little endian words), and color images are stored as byte triple in the order Blue, Green, Red. In all cases, the rows must start on a doubleword boundary.

Example: 5x3 grayscale (Gray), 16 bits grayscale (Gray16) and color images (Rgb) are stored as follows:

GGGGG---GGGGG---GGGGG---

1 byte per pixel, 8 bytes per row

GgGgGgGgGg--GgGgGgGgGg--GgGgGgGgGg--

2 bytes per pixel, 12 bytes per row

BGRBGRBGRBGRBGR-BGRBGRBGRBGRBGR-BGRBGRBGRBGRBGR-

3 bytes per pixel, 16 bytes per row


Advanced: Drawing with a display lookup-table

When you draw a grayscale image, pixels appear as shades of gray on a linear scale from black to white. You can change this behavior by assigning a different scale of grays, or even a scale of colors, for pseudo-coloring. This is done by setting-up a grayscale or color lookup-table as a Profile object, and pass it to the Draw method.

Example:

C++ Native

       // Setup a pseudo-coloring lookup-table

       Profile Lut;

       Lut.Set(0, Rgb);

       for (int i= 0; i < 256; i++)

       {

              // Increasing red, decreasing blue

              Lut.Append(i, 0, 255 - i);

       }

       // Display the image using the lookup-table

       Src.Draw(Lut);

C++.NET using namespace mVizNET;

       // Setup a pseudo-coloring lookup-table

       Profile^ Lut= gcnew Profile;

       Lut->Set(0, PixelTypes::Rgb, (IntPtr)0, 0);

       for (int i= 0; i < 256; i++)

       {

              // Increasing red, decreasing blue

              Lut->Append(i, 0, 255 - i);

       }

       // Display the image using the lookup-table

       Src->Draw(Lut, false);

C# using mVizNET;

       // Setup a pseudo-coloring lookup-table

       Profile Lut = new Profile();

       Lut.Set(0, PixelTypes.Rgb, (IntPtr)0, 0);

       for (int i = 0; i < 256; i++)

       {

           // Increasing red, decreasing blue

           Lut.Append(i, 0, 255 - i);

       }

       // Display the image using the lookup-table

       Src.Draw(Lut, false);

Visual Basic

       ' Setup a pseudo-coloring lookup-table

       Dim Lut As mVizNET.Profile = New mVizNET.Profile()

       Lut.Set(0, mVizNET.PixelTypes.Rgb, 0, 0)

       For i As Integer = 0 To 255

       ' Increasing red, decreasing blue

       Lut.Append(i, 0, 255 - i)

       Next i

       ' Display the image using the lookup-table

       Src.Draw(Lut, False)

The pixel values in the image remain unchanged.


Advanced: Drawing into an image

Rather than drawing over an image (nondestructive overlay), you can draw inside an image for inlaying (destructive overlay). This is achieved by the method DrawToImage, which assigns the DrawTo property a valid Windows Device Context Handle that directs drawing to the image. Any Windows GDI function can be used for drawing, as well as any mViz drawing method. (This includes the methods supported by the Graph class, as well as the Draw methods of the classes having one.)

Caution: after drawing into the image, the method ReleaseImage must be called.

Note that the target image keeps its original type, so that if you draw into a grayscale image, the result will be grayscale. To get a colorful drawing, you need to convert the original grayscale image to an auxiliary Rgb target. You can use the method Copy for this purpose.

Example:

C++ Native

       // Draw into the image

       Graph::DrawToImage(Target);

       // Draw an embedded line

       Graph::Line(0, 0, 100, 100);

       // Draw a Window frame with handles

       Src.DrawWindow(true);

       // Finish drawing

       Graph::ReleaseImage(Target);

C++.NET using namespace mVizNET;

       // Draw into the image

       Graph::DrawToImage(Target);

       // Draw an embedded line

       Graph::Line(0, 0, 100, 100);

       // Draw a Window frame with handles

       Src.DrawWindow(true);

       // Finish drawing

       Graph::ReleaseImage(Target);

C# using mVizNET;

       // Draw into the image

       Graph.DrawToImage(Target);

       // Draw an embedded line

       Graph.Line(0, 0, 100, 100);

       // Draw a Window frame with handles

       Src.DrawWindow(true);

       // Finish drawing

       Graph.ReleaseImage(Target);

Visual Basic

       ' Draw into the image

       mVizNET.Graph.DrawToImage(Target)

       ' Draw an embedded line

       mVizNET.Graph.Line(0, 0, 100, 100);

       ' Draw a Window frame with handles

       Src.DrawWindow(True);

       ' Finish drawing

       mVizNET.Graph.ReleaseImage(Target)

Reference:

Image::Set,
Image::Buffer, Image::Pitch,
Image::Type,
Profile::Set, Profile::Append ,  Graph::ReleaseImage.


Pixel Arithmetic

The usual arithmetic operations such as addition or division can be generalized to whole images instead of numbers. In this case, the same operation is repeated over the whole image, pixel by pixel, yielding new values that are stored in corresponding pixels of a destination image.

For instance, adding images A and B means that every pixel in A is added to the corresponding pixel in B, yielding a sum value put in the matching pixel of a destination image. This feature is handled by the class Operator.

mViz supports different operators that fill out a destination image from a single source or from two sources. The first or second source image can also be replaced by a constant value. The image arguments don’t need to be different.

Example:

C++ Native

       // Add two images, giving a third one: A + B -> C

       Operator::Add(A, B, C);

       // Add a constant to an image, giving a second image: 24 + A -> D

       Operator::Add(24, A, D);

       // Add a constant to an image, in-place: 24 + A -> A

       Operator::Add(24, A, A);

C++.NET using namespace mVizNET;

       // Add two images, giving a third one: A + B -> C

       Operator::Add(A, B, C, GrayClipping::Saturate);

       // Add a constant to an image, giving a second image: 24 + A -> D

       Operator::Add(24, A, D, GrayClipping::Saturate);

       // Add a constant to an image, in-place: 24 + A -> A

       Operator::Add(24, A, A, GrayClipping::Saturate);

C# using mVizNET;

       // Add two images, giving a third one: A + B . C

       Operator.Add(A, B, C, GrayClipping.Saturate);

       // Add a constant to an image, giving a second image: 24 + A . D

       Operator.Add(24, A, D, GrayClipping.Saturate);

       // Add a constant to an image, in-place: 24 + A . A

       Operator.Add(24, A, A, GrayClipping.Saturate);

Visual Basic

       ' Add two images, giving a third one: A + B . C

       mVizNET.Operator.Add(A, B, C, mVizNET.GrayClipping.Saturate)

       ' Add a constant to an image, giving a second image: 24 + A . D

       mVizNET.Operator.Add(24, A, D, mVizNET.GrayClipping.Saturate)

       ' Add a constant to an image, in-place: 24 + A . A

       mVizNET.Operator.Add(24, A, A, mVizNET.GrayClipping.Saturate)

Obviously, images must be compatible, i.e. with the same pixel types and same size. The type and size of the destination image is automatically adapted.


One source, one destination

The Copy operator transfers all source pixels to the destination image. By default, the source image type is safeguarded. When otherwise specified, a conversion takes place. If a constant is used instead of a source image, the constant value is copied throughout the image.

The following type conversions are available:

From/To | Gray1 | Gray | Gray16 | Rgb | Rgba
Gray1 | ü | ü | - | - | -
Gray | ü | ü | ü | ü | ü
Gray16 | - | ü | ü | - | -
Rgb | - | ü | - | ü | ü
Argb | - | ü | - | ü | ü

Example:

C++ Native

       // Fill with medium gray

       Operator::Copy(128, FlatImage);

       // Convert to color

       Operator::Copy(GrayImage, ColorImage, Rgb);

C++.NET using namespace mVizNET;

       // Fill with medium gray

       Operator::Copy(128, FlatImage);

       // Convert to color

       Operator::Copy(GrayImage, ColorImage, PixelTypes::Rgb);

C# using mVizNET;

       // Fill with medium gray

       Operator.Copy(128, FlatImage);

       // Convert to color

       Operator.Copy(GrayImage, ColorImage, PixelTypes.Rgb);

Visual Basic

       ' Fill with medium gray

       mVizNET.Operator.Copy(128, FlatImage)

       ' Convert to color

       mVizNET.Operator.Copy(GrayImage, ColorImage, mVizNET.PixelTypes.Rgb)

The Invert operator inverts every pixel, i.e. takes the complement to the White value (white pixels turn black, and conversely).

Operator | Output | Purpose
Copy | Copy, without or with type conversion | Duplication, conversion
Negative | White – A | Contrast reversal

Reference:

Operator::Copy, Operator::Invert.


Two sources, one destination

The basic arithmetic operations are addition, subtraction, multiplication and division. When applied to values in the grayscale range, they can generate results beyond the grayscale range. For instance, subtracting the gray values 115 and 203 yields a negative result -88, which cannot be represented as a gray value.

Clipping

To handle this issue, mViz supports different behavior rules:

  • Saturate: when a value is out of range, it is clamped to the nearest range bound; negative values are clamped to black and large positive values are clamped to the white value;

  • Absolute: the sign of the result is ignored and saturation is applied if needed;

  • Negative: negative values are turned to positive and positive values are clamped to the black value;

· Rescale: the input arguments are rescaled by a linear transformation so that underflow or overflow are minimized; the transformation in use depends on the operator.

Example:

C++ Native

       // Add two images with saturation (by default)

       Operator::Add(A, B, C);

       // Add two images with rescaling

       Operator::Add(A, B, C, Rescale);

C++.NET using namespace mVizNET;

       // Add two images with saturation (by default)

       Operator::Add(A, B, C, GrayClipping::Saturate);

       // Add two images with rescaling

       Operator::Add(A, B, C, GrayClipping::Rescale);

C# using mVizNET;

       // Add two images with saturation (by default)

       Operator.Add(A, B, C, GrayClipping.Saturate);

       // Add two images with rescaling

       Operator.Add(A, B, C, GrayClipping.Rescale);

Visual Basic

       ' Add two images with saturation (by default)

       mVizNET.Operator.Add(A, B, C, mVizNET.GrayClipping.Saturate)

       ' Add two images with rescaling

       mVizNET.Operator.Add(A, B, C, mVizNET.GrayClipping.Rescale)


Arithmetic

The arithmetic operators are the four usual operations Add, Subtract, Multiply and Divide.

Operator | Clipping Rule | Output | Purpose
Sum | Saturate | A + B | Blending
 | Absolute[1] | |A + B| | Comparison
 | Rescale | (A + B) / 2 | Averaging
Difference | Saturate | A – B | Background removal
 | Absolute | |A – B| | Image comparison
 | Rescale | (A + White – B) / 2 | Signed image comparison
Product | Saturate | A * B | Ad-hoc
 | Rescale | (A * B) / White | Shading simulation
Quotient | Saturate | A / B | Ad-hoc
 | Rescale | (A * White) / B | Shading correction

X Ramp  + Y Ramp  à  Sum S Saturate, Absolute

X Ramp  + Y Ramp  à  Sum R Rescale

X Ramp  - Y Ramp  à  Difference S Saturate

X Ramp  - Y Ramp  à  Difference A Absolute

X Ramp  - Y Ramp  à  Difference R Rescale

X Ramp  * Y Ramp  à  Product S Saturate [2]

X Ramp  * Y Ramp  à  Product R Rescale

X Ramp  / Y Ramp  à  Quotient S Saturate [3]

X Ramp  / Y Ramp  à  Quotient R Rescale

[1] Makes sense with a negative constant

[2] Values are too large to be seen

[3] Values are too small to be seen


Bitwise

The other operators are not subjected to underflow/overflow and require no clipping rule. The logical operators (And, Or, Xor) are applied bitwise, i.e. corresponding bits in the operands are combined in pairs.

Operator | Output | Purpose
And | Bitwise and | Masking (intersection)
Or | Bitwise or | Masking (union)
Xor | Bitwise exclusive or | Masking (symmetric difference)

X Ramp  Or  Y Ramp  à  Or

X Ramp  And Y Ramp  à  And

X Ramp  Xor Y Ramp  à  Xor


Comparison

The comparison operators are the following: Minimize, Maximize, EqualTest, GreaterTest and GreaterEqualTest.

The comparison operators (=, >, ³) define a logical predicate. A constant gray value is associated to the false value, another to true. By default, black and white gray levels are used.

Operator | Output | Purpose
Maximum | Largest of A and B | Keeping brightest features
Minimum | Smallest of A and B | Keeping darkest features
Equal | Identical pixels | Comparison
Greater | A larger than B | Thresholding
GreaterEqual | A not smaller than B | Thresholding

X Ramp  Max Y Ramp  à  Maximum

X Ramp  Min Y Ramp  à  Minimum

X Ramp    =  Y Ramp  à

X Ramp    >  Y Ramp  à  Greater

X Ramp    ³  Y Ramp  à  GreaterEqual

Reference:

Operator::Add, Operator::Subtract, Operator::Multiply, Operator::Divide, Operator::Maximize, Operator::Minimize, Operator::Or, Operator::And, Operator::Xor, Operator::EqualTest, Operator::GreaterTest, Operator::GreaterEqualTest.


Image Mixing

Image mixture, also known as blending, is the process of appending images with complementary mixture weights. This results in a fade in/fade out effect.

Example:

C++ Native

       // Mix 25% of A with 75% of B, yielding C

       Operator::Blend(0.25, A, B, C);

C++.NET using namespace mVizNET;

       // Mix 25% of A with 75% of B, yielding C

       Operator::Blend(0.25, A, B, C);

C# using mVizNET;

       // Mix 25% of A with 75% of B, yielding C

       Operator.Blend(0.25, A, B, C);

Visual Basic

       ' Mix 25% of A with 75% of B, yielding C

       mVizNET.Operator.Blend(0.25, A, B, C)

Operator | Output | Purpose
Blend | a . A + (1 - a) . B | Interpolation

X Ramp  Blend Y Ramp  à  Blend 0  a=¼

Reference:

Operator::Blend.


Point-to-point Operations

Apart from arithmetic operations, other transformations are applied pixel by pixel between several images. They are also handled by the Operator class.


Binarization, Soft Binarization, Adaptive Binarization

Binarization is an extremely useful way to decompose an image by classifying the pixels as background (black) or foreground (white). The classification rule is a mere comparison to a threshold.

You can specify the threshold level directly, or as the average of a background and a foreground value. You can also let the function find an appropriate threshold value for you. There are five overloads of the Binarize method.

Example:

C++ Native

       // Binarize the source image using 78 as a threshold value

       // using inverse contrast: white background and black foreground

       Operator::Binarize(78, Src, Dst, false);

C++.NET using namespace mVizNET;

       // Binarize the source image using 78 as a threshold value

       // using inverse contrast: white background and black foreground

       Operator::Binarize(Src, Dst, 78, 255, 0);

C# using mVizNET;

       // Binarize the source image using 78 as a threshold value

       // using inverse contrast: white background and black foreground

       Operator.Binarize(Src, Dst, 78, 255, false);

Visual Basic

       ' Binarize the source image using 78 as a threshold value

       ' using inverse contrast: white background and black foreground

       mVizNET.Operator.Binarize(Src, Dst, 78, 255, False)

When the image has two dominant shades of gray, i.e. when the image histogram is bimodal, an appropriate threshold value can be chosen automatically.

Example:

C++ Native

       // Binarize the source image

       Operator::Binarize(Src, Dst);

C++.NET using namespace mVizNET;

       // Binarize the source image (black to white, hard thresholding)

       Operator::Binarize(Src, Dst, 0, 255, false);

C# using mVizNET;

       // Binarize the source image (black to white, hard thresholding)

       Operator.Binarize(Src, Dst, 0, 255, false);

Visual Basic

       ' Binarize the source image (black to white, hard thresholding)

       mVizNET.Operator.Binarize(Src, Dst, 0, 255, False)

Ordinary binarization sets the pixels to constant black or white values. Soft binarization ensures a smooth transition between black and white, applying two reference levels.

Standard vs. soft transfer function

Set the Soft argument to true. In the example below, the difference is noticeable along edges.

Standard vs. soft binarization

Last but not least, you can perform adaptive thresholding, i.e. let the function choose a different threshold on each pixel, depending on the gray values in a window of fixed size around it. This is quite useful in case of uneven background illumination.

Example:

C++ Native

       // Binarize the source image adaptatively, using a 64x64 sliding window

       // and assuming noise amplitude 5

       Operator::Binarize(64, 5, Src, Dst);

C++.NET using namespace mVizNET;

       // Binarize the source image adaptatively, using a 64x64 sliding window

       // and assuming noise amplitude 5

       Operator::Binarize(64, 5, Src, Dst, 0, 255);

C# using mVizNET;

       // Binarize the source image adaptatively, using a 64x64 sliding window

       // and assuming noise amplitude 5

       Operator.Binarize(64, 5, Src, Dst, 0, 255);

Visual Basic

       ' Binarize the source image adaptatively, using a 64x64 sliding window

       ' and assuming noise amplitude 5

       mVizNET.Operator.Binarize(64, 5, Src, Dst, 0, 255)

Global vs. adaptive binarization

Reference:

Operator::Binarize.


Shading Correction

Due to uneven illumination, vignetting or non-uniform response of the camera sensor, gray values may scale differently at different image places. Shading correction aims to restore a uniform scale of grays across the whole image.

Original, reference and corrected images

This is made by providing one or two images of a perfectly uniform surface, associated to one or two constant gray-levels. After correction using an addition, a multiplication or a linear transform, the reference image turns to the given constant; the source image turns to a flat-shaded image, better suited for binarization.

Additive, multiplicative and linear correction

Use the methods CorrectAdditive, CorrectMultiplicative and Correct.

Reference:

Operator::CorrectAdditive, Operator::CorrectMultiplicative and Operator::Correct.


Grayscale vs Color Shading Correction

When the source image is of the Gray/Gray16 type (shades of gray), the reference must be of the same type.

But when the source image is Rgb (color), there are two options:

· The reference is Gray and used for the three color planes, as a lightness reference;

· The reference is Rgb as well, and shading correction is applied separately to the respective color planes.

In the first case, the black/white constants are scalars; in the second they are RGB values. For both conventions, the methods share the same name.


Type Conversions

Images support pixels of different types, such as Gray, Rgb or Rgba. mViz enables to convert images of a given type to another type, by means of the method Copy. You specify a source, a destination, and the desired destination type.

Conversions from Gray to color are straightforward: the grayscal content is copied to all three Red, Green and Blue planes.

Conversions from color to Gray are more interesting as they correspond to numerous possible transforms (see the next section). The Copy method simply turns the colors to a lightness value.

Example:

C++ Native

       // Convert Gray to Rgb

       Operator::Copy(GrayImage, ColorImage, Rgb);

C++.NET using namespace mVizNET;

       // Convert Gray to Rgb

       Operator::Copy(GrayImage, ColorImage, Rgb);

C# using mVizNET;

       // Convert Gray to Rgb

       Operator.Copy(GrayImage, ColorImage, PixelTypes.Rgb);

Visual Basic

       ' Convert Gray to Rgb

       mVizNET.Operator.Copy(GrayImage, ColorImage, mVizNET.PixelTypes.Rgb)

Reference:

Operator::Copy.


Color Conversions

mViz accepts 24 bits RGB color images as input. It can turn them to grayscale images by extracting some color component. This is done by means of the method Convert, specifying one of the available color component ColorComponents.

Different colorimetric systems are supported:

· RGB is the native format provided by industrial cameras; it is device dependent by nature.

· HLS and HSV were introduced by the computer graphics community to support the intuitive notions of tint, clarity and saturation.

· YUV is the native format used in digital video broadcast equipment. It decouples intensity from chromaticity.

· XYZ is a device-independent universal representation defined by the Commission Internationale de l’Éclairage.

Every color system is defined as a vector of three components:

RGB | Red | Green | Blue
HLS | Hue | Lightness | Saturation
HSV | Hue | Saturation | Value
YUV | Luma | ChromaU | ChromaV
XYZ | X | Y | Z

Color & Lightness component

Saturation & Chroma V components

Example:

     // Get the Hue from the image Color (Rgb -> Gray)

     Operator::Convert(Hue_HLS, Color, Hue);

Convert also enables you to get or set the three individual color planes of an Rgb image.

Example:

C++ Native

       // Combine red, green and blue color planes (Gray -> Rgb)

       Operator::Convert(RedImage, ColorImage, Red_RGB);

       Operator::Convert(GreenImage, ColorImage, Green_RGB);

       Operator::Convert(BlueImage, ColorImage, Blue_RGB);

C++.NET using namespace mVizNET;

       // Combine red, green and blue color planes (Gray -> Rgb)

       Operator::Convert(RedImage, ColorImage, ColorComponents::Red_RGB);

       Operator::Convert(GreenImage, ColorImage, ColorComponents::Green_RGB);

       Operator::Convert(BlueImage, ColorImage, ColorComponents::Blue_RGB);

C# using mVizNET;

       // Combine red, green and blue color planes (Gray . Rgb)

       Operator.Convert(RedImage, ColorImage, ColorComponents.Red_RGB);

       Operator.Convert(GreenImage, ColorImage, ColorComponents.Green_RGB);

       Operator.Convert(BlueImage, ColorImage, ColorComponents.Blue_RGB);

Visual Basic

       ' Combine red, green and blue color planes (Gray . Rgb)

       mVizNET.Operator.Convert(RedImage, ColorImage, mVizNET.ColorComponents.Red_RGB)

       mVizNET.Operator.Convert(GreenImage, ColorImage, mVizNET.ColorComponents.Green_RGB)

       mVizNET.Operator.Convert(BlueImage, ColorImage, mVizNET.ColorComponents.Blue_RGB)

Reference:

Operator::Convert and ColorComponents.


Bayer demosaicing

Numerous digital cameras deliver color images as grayscale, using the so-called Bayer-pattern filtering, rather than as plain true color Rgb. The Bayer pattern is a repetition of a Red-Green-Green-Blue pixel quad.

Bayer pattern filters

Original, Bayer encoded image

The method DeBayer will convert a Bayer encoded image to plain Rgb, using an interpolation process. It is necessary to specify how the pattern is aligned, by telling the colors of the two leftmost pixels in the first row. The default alignment is Red- Green, like on the picture.

Another argument, Quality, controls how a tradeoff between speed and image quality is achieved. In addition, it is also possible to directly convert to grayscale instead of color, in case grayscale processing would be required.

Fast, Smooth and Sharp demosaicing

Smooth and Sharp demosaicing to grayscale

Example:

C++ Native

       // Demosaicize, using the default alignment and quality

       Operator::DeBayer(BayerImage, ColorImage);

C++.NET using namespace mVizNET;

       // Demosaicize

       Operator::DeBayer(BayerImage, ColorImage, BayerAlignments::RedGreen, BayerQualities::FastRgb);

C# using mVizNET;

       // Demosaicize

       Operator.DeBayer(BayerImage, ColorImage, BayerAlignments.RedGreen, BayerQualities.FastRgb);

Visual Basic

       ' Demosaicize

       mVizNET.Operator.DeBayer(BayerImage, ColorImage, mViz.BayerAlignments.RedGreen, mViz. BayerQualities. FastRgb)

Reference:

Operator::DeBayer, BayerAlignments, Baye Qualities.


Color Normalization

Color images have pixels whose RGB components vary freely in the [0..255] range. Depending on the lighting conditions or sensor response, the appearance of colors can change either globally or locally. Color fidelity is often difficult to achieve.

One way to deal with that is to somehow normalize the RGB components to lessen the allowed variations.

The method ColorsLighten ensures that the lightness of every pixel is maximum (255) so that any shading effect is canceled. The method ColorsSaturate ensures that the saturation of every pixel is maximum so that all colors appear vivid. Combining the two operations generates an image where only the Hue information is preserved.

Lightness normalization

Saturation normalization

Lightness + Saturation normalization

Example:

C++ Native

       // Flatten the lightness, in-place

       Operator::ColorsLighten(ColorImage, ColorImage);

C++.NET using namespace mVizNET;

       // Flatten the lightness, in-place

       Operator::ColorsLighten(ColorImage, ColorImage);

C# using mVizNET;

       // Flatten the lightness, in-place

       Operator.ColorsLighten(ColorImage, ColorImage);

Visual Basic

       ' Flatten the lightness, in-place

       mVizNET.Operator.ColorsLighten(ColorImage, ColorImage)

Reference:

Operator::ColorsLighten and Operator::ColorsSaturate.


Linear Filtering

As established by the theory of signal and image processing, spatial filtering is made to enhance or remove certain frequencies, i.e. slow or fast variations across the image. It is implemented by the so-called convolution operation. A convolution is the result of a linear combination of the pixel values in a sliding window swept over the image. The coefficients of the linear combination can be arranged as an array called the convolution Kernel.

Convolutions can produce such effects as smoothing and noise removal (low-pass filtering), sharpening and deblurring (high-pass), and edge detection (derivative). You need to pass a source and a destination image. In-place convolution is also made possible by passing the same source and destination.

Example:

C++ Native

       // Smooth the source to the destination

       Kernel::Smooth(Src, Dst);

       // Sharpen in-place

       Kernel::Sharpen8(Src, Src);

C++.NET using namespace mVizNET;

       // Smooth the source to the destination

       Kernel::Smooth(Src, Dst);

       // Sharpen in-place

       Kernel::Sharpen8(Src, Src, GrayClipping::Saturate);

C# using mVizNET;

       // Smooth the source to the destination

       Kernel.Smooth(Src, Dst);

       // Sharpen in-place

       Kernel.Sharpen8(Src, Src, GrayClipping.Saturate);

Visual Basic

       ' Smooth the source to the destination

       mVizNET.Kernel.Smooth(Src, Dst)

       ' Sharpen in-place

       mVizNET.Kernel.Sharpen8(Src, Src, mVizNET.GrayClipping.Saturate)


Smoothing

A convolution kernel with most coefficients being positive behaves like a weighted average of the pixel values. It has a smoothing effect that lessens the edge strength and reduces noise amplitude.

Convolution | Kernel | Purpose
Uniform |  | Strong smoothing
Uniform8 |  | Strong smoothing
Binomial |  | Weak smoothing

Chip  à  Uniform Uniform

Chip  à  Uniform8 Uniform8

Chip  à  Binomial Binomial

Reference:

Kernel::Smooth, Kernel::Smooth8, Kernel::Binomial.


Sharpening

Sharpening, also called deblurring, is the converse of smoothing. It enhances edges and restores the image sharpness. Unfortunately, it also enhances noise. Sharpening is achieved by deducting a smoothed version of the image from the original image.

Convolution | Kernel | Purpose
Sharpen4 |  | Medium sharpening
Sharpen8 |  | Stronger sharpening

Chip  à  Sharpen4 Sharpen4

Chip  à  Sharpen8 Sharpen8

Reference:

Kernel::Sharpen4, Kernel::Sharpen8.


Edge Detection

Edges are steep transitions of the pixel gray levels in a given direction. They can be isolated by applying a derivative filter such as the gradient. The gradient is the vector formed by the horizontal and the vertical first derivatives. The magnitude of this vector gives a good indication of the edge strength. Its direction is perpendicular to the edge direction.

Convolution | Kernel | Purpose
GradientX |  | Vertical edges
GradientY |  | Horizontal edges
Gradient |  | All edges
PrewittX |  | Vertical edges with noise reduction
PrewittY |  | Horizontal edges with noise reduction
Prewitt |  | All edges, with noise reduction
SobelX |  | Vertical edges with weak noise reduction
SobelY |  | Horizontal edges with weak noise reduction
Sobel |  | All edges, with weak noise reduction

Chip  à  GradientX GradientX

Chip  à  GradientY GradientY

Chip  à  Gradient Gradient

Chip  à  PrewittX PrewittX

Chip  à  PrewittY PrewittY

Chip  à  Prewitt S Prewitt, Saturate

Chip  à  Prewitt R Prewitt, Rescale

Chip  à  SobelX SobelX

Chip  à  SobelY SobelY

Chip  à  Sobel S Sobel, Saturate

Chip  à  Sobel R Sobel, Rescale

Reference:

Kernel::GradientX, Kernel::GradientY, Kernel::Gradient, Kernel::SobelX, Kernel::SobelY, Kernel::Sobel, Kernel::Prewitt.


Box, Gaussian and bilateral filters

Strong low-pass filtering is useful to wipe out all image details under a certain scale, and is used in the so-called scale-space techniques.

A box filter BoxLowPass has a rectangular (often square) support and computes an unweighted average of all pixels in a sliding window.

A complementary box filter is also available as BoxHighPass: it very efficiently removes the DC component of the image and flattens illumination.

A Gaussian filter GaussLowPass computes a weighted average, using the Gauss bell curve. It has a better anisotropy than the box filter and enjoys nice theoretical properties. (For efficiency reasons, the Gaussian filter in mViz is a reasonable approximation.)

Ultimately, the bilateral filter is a lowpass filter that smooths strongly in the uniform areas, and weakly on the edges, to preserve them. This makes it a very efficient denoising filter, probably better than the median morphological filter. Use Bilateral.

Chip  à  [image]    Box low 31x31

Chip  à  [image]    Box high 31x31

Chip  à  [image]   Gauss 31x31

Chip  à  [image]   Bilateral 31x31

Example:

C++ Native

       // Bilateral filter, 31x31 pixels, 25 gray-levels, in-place

       Kernel::Bilateral(31, 25, Src, Src);

C++.NET using namespace mVizNET;

       // Bilateral filter, 31x31 pixels, 25 gray-levels, in-place

       Kernel::Bilateral(31, 25, Src, Src);

C# using mVizNET;

       // Bilateral filter, 31x31 pixels, 25 gray-levels, in-place

       Kernel.Bilateral(31, 25, Src, Src);

Visual Basic

       ' Bilateral filter, 31x31 pixels, 25 gray-levels, in-place

       Kernel.Bilateral(31, 25, Src, Src)

Reference:

Kernel::BoxLowPass, Kernel::BoxHighPass, Kernel::GaussLowPass, Kernel::Bilateral.


User-defined Convolution Kernels

Additional effects and larger filter sizes can also be applied. If the user is skilled in filter design or wants to implement other filters available in the literature, he can do so by defining a custom convolution kernel.

First create a Kernel object, define the kernel array size and assign individual coefficients. See the Set method and the Coefficient accessor.

If needed, the coefficients can be normalized, i.e. rescaled in such a way that their sum equals a desired value, the global gain of the filter. A global offset value can also be added to the convolution result. Check the NormalizeCoefficients method and the Offset property.

Example:

C++ Native

       // Define a 2x2 filter

       Kernel Convol;

       Convol.Set(2, 2);

       // Use uniform, normalized coefficients

       Convol.Coefficient(0, 0)= 1.;

       Convol.Coefficient(1, 0)= 1.;

       Convol.Coefficient(0, 1)= 1.;

       Convol.Coefficient(1, 1)= 1.;

       Convol.Normalize();

       // Apply convolution

       Convol.Convolve(A, B);

C++.NET using namespace mVizNET;

       // Define a 2x2 filter

       Kernel^ Convol= gcnew Kernel;

       Convol->Set(2, 2);

       // Use uniform, normalized coefficients

       Convol->Coefficient(0, 0, 1.);

       Convol->Coefficient(1, 0, 1.);

       Convol->Coefficient(0, 1, 1.);

       Convol->Coefficient(1, 1, 1.);

       Convol->Normalize(1);

       // Apply convolution

       Convol->Convolve(A, B);

C# using mVizNET;

       // Define a 2x2 filter

       Kernel Convol = new Kernel();

       Convol.Set(2, 2);

       // Use uniform, normalized coefficients

       Convol.Coefficient(0, 0, 1.0);

       Convol.Coefficient(1, 0, 1.0);

       Convol.Coefficient(0, 1, 1.0);

       Convol.Coefficient(1, 1, 1.0);

       Convol.Normalize(1);

       // Apply convolution

       Convol.Convolve(A, B);

Visual Basic

       ' Define a 2x2 filter

       Dim Convol As mVizNET.Kernel = New mVizNET.Kernel()

       Convol.Set(2, 2)

       ' Use uniform, normalized coefficients

       Convol.Coefficient(0, 0, 1.0)

       Convol.Coefficient(1, 0, 1.0)

       Convol.Coefficient(0, 1, 1.0)

       Convol.Coefficient(1, 1, 1.0)

       Convol.Normalize(1)

       ' Apply convolution

       Convol.Convolve(A, B)

Chip  à  Kernel User-defined

Reference:

Kernel::Set, Kernel::Coefficient, Kernel::Offset, Kernel::Normalize, Kernel::Convolve.


Morphological Filtering

By contrast with linear filtering, the morphological operations are non-linear and are responsive to the shape and size of features instead of spatial frequencies. These operations, originating from the field of mathematical morphology, are based on a reference shape described by a binary array of pixels known as a structuring element.

In mViz, the morphological filters are supported by the class Morpho and the structuring elements belong to one of the following families:

Vertical, horizontal, box, square, octagon and diamond shapes

The structuring elements width and height must be odd numbers. The morphological filters are implemented by sweeping the structuring element over the source image and considering the pixels it covers. Then the center pixel value is replaced by some pixel among the covered ones.

First define the structuring element shape and size by means of one of the following methods: Vertical, Horizontal, Box, Square, Octagon, Diamond.

Example:

C++ Native

       // Use a 5x5 square

       Morpho Structel;

       Structel.Square(5);

C++.NET using namespace mVizNET;

       // Use a 5x5 square

       Morpho^ Structel= gcnew Morpho;

       Structel->Square(5);

C# using mVizNET;

       ' Use a 5x5 square

       Dim Structel As mVizNET.Morpho = New mVizNET.Morpho()

       Structel.Square(5)

Visual Basic

       // Use a 5x5 square

       Morpho Structel;

       Structel.SetSquare(5);

Reference:

Morpho::Vertical, Morpho::Horizontal, Morpho::Box, Morpho::Square, Morpho::Octagon, Morpho::Diamond.


Dilation and Erosion

Dilation selects the pixel with the largest value, i.e. the closest to white, and copies it to the center pixel. Following this rule, light features tend to grow thicker by the size of the structuring element, possibly connecting them, and the dark features tend to be erased.

Erosion is said to be dual of the dilation, it works with inverted contrast: the pixel with the smallest value, i.e. the closest to black is copied to the center. This enlarges the black features possibly connecting them, and erases the white features.

Let P a pixel in the image with value VP and NP the neighborhood of this pixel having the shape of the structuring element:

Use one of the Dilate and Erode methods.

Example:

C++ Native

       // Erode in-place

       Structel.Erode(Src, Src);

C++.NET using namespace mVizNET;

       // Erode in-place

       Structel->Erode(Src, Src);

C# using mVizNET;

       // Erode in-place

       Structel.Erode(Src, Src);

Visual Basic

       ' Erode in-place

       Structel.Erode(Src, Src)

Chip2  à  Dilate Dilate (Vertical 9)

Chip2  à  Erode Erode (Vertical 9)

Reference:

Morpho::Dilate, Morpho::Erode.


Closing and Opening

Closing is defined as a dilation followed by an erosion using the same structuring element. The dilation grows the light features and erases the dark ones; then the erosion brings the light features back to their original size, but the dark features remain erased. Light features that were connected also remain connected.

Opening is the dual of closing, i.e. erosion followed by dilation. It reverts to the original feature size while keeping connections between dark features and erasing light ones.

Using the same notation:

Use one of the Close and Open methods.

Example:

C++ Native

       // Open source to destination

       Structel.Open(Src, Dst);

C++.NET using namespace mVizNET;

       // Open source to destination

       Structel->Open(Src, Dst);

C# using mVizNET;

       // Open source to destination

       Structel.Open(Src, Dst);

Visual Basic

       ' Open source to destination

       Structel.Open(Src, Dst)

Chip2  à  Close Close (Vertical 9)

Chip2  à  Open Open (Vertical 9)

Reference:

Morpho::Close, Morpho::Open.


Top-hat Transforms

The white top-hat transform reveals the places where a closing operation did change the original image, by subtraction. This shows where connections appeared between light features and where darks features were removed. It is an excellent filter to enhance small features and “flatten” the background.

By duality, the black top-hat transform keeps the black connections and light erasures.

Both top-hat transforms output a grayscale image. If desired, the latter can be automatically binarized for segmentation and blob analysis.

We have:

Use one of the WhiteHat and BlackHat methods.

Example:

C++ Native

       // Binarized white top-hat in-place

       Structel.WhiteHat(Src, Dst, true);

C++.NET using namespace mVizNET;

       // Binarized white top-hat in-place

       Structel->WhiteHat(Src, Dst, true);

C# using mVizNET;

       // Binarized white top-hat in-place

       Structel.WhiteHat(Src, Dst, true);

Visual Basic

       ' Binarized white top-hat in-place

       Structel.WhiteHat(Src, Dst, True)

Chip2  à  WhiteHat WhiteHat (Vertical 9)

Chip2  à  WhiteHat Bin WhiteHat, binary (Vertical 9)

Chip2  à  BlackHat BlackHat (Vertical 9)

Chip2  à  BlackHat Bin BlackHat, binary (Vertical 9)

Reference:

Morpho::WhiteHat, Morpho::BlackHat.


Rank and Median filters

The rank filter performs an intermediate operation between dilation and erosion, by replacing the center pixel with a value between the darkest and lightest, having a desired rank. The resulting effect is a smoothing.

The most common use-case is that of the median, i.e the value having the middle rank. This filter is well known for performing noise reduction while preserving the edges (by contrast with the mean filters – uniform or Gaussian).

Contrary to custom, the desired rank is specified as a percentage value, Percent (between 0 and 1) rather than an integer rank (between 0 and the area of the structuring element).

Use one of the Rank and Median methods.

Example:

C++ Native

       // First quartile rank filter, in-place

       Structel.Rank(0.25, Src, Src);

C++.NET using namespace mVizNET;

       // First quartile rank filter, in-place

       Structel-> Rank(0.25, Src, Src);

C# using mVizNET;

       // First quartile rank filter, in-place

       Structel.Rank(0.25, Src, Src);

Visual Basic

       ' First quartile rank filter, in-place

       Structel.Rank(0.25, Src, Src)

Chip2  à  [image] Rank 25% (Vertical 9)

Chip2  à  [image] Rank 25% (Square 9)

Chip2  à  [image] Median (Vertical 9)

Chip2  à  [image] Median (Square 9)

Technical note: the rank filter is a robust alternative to dilation and erosion in the presence of noise, as it is less sensitive to outliers.

Reference:

Morpho::Rank and Morpho::Median.


Image segmentation

The decomposition of an image into homogeneous connected regions is a difficult task. Its purpose is to find objects or areas of a distinct lightness. Binarization is the most elementary segmentation techniques, allowing to just separate background from foreground.

mViz supports two more advanced segmentation technique: edge-watershed and clustering. The edge-watershed consists in taking the gradient magnitude of the image and seeing this map as walls separating different basins. Hence zones with a constant color have low gradients and will form single basins. Separations between two regions, known as edges, will yield high gradient and form "dams" between the basins. Beware that the watershed often creates oversegmentation (many tiny regions).

The clustering method will group contiguous pixels as long as their gray-level values are similar enough. Here again, areas of similar value will turn to regions, and high variations will separate them.

To use the watershed method, first select some gradient computation function (such as Gradient , Sobel, Canny or Gradient to name a few). Then you pass the gradient image to the method Watershed, which will return a binary image with black regions separated by white dams. You can post-process this image with blob analysis, for instance. An overload of the method lets you pass the source image as well and will fill the region image with the average value of the basins instead.

Dams only or basin averages

The clustering method is implemented by GraphSegment. It does not require precomputation of a gradient but often produces more fragmentation. It assigns the segments arbitrary gray levels.

Clusters

Reference:

Morpho::Watershed and Morpho::GraphSegment.


Regional extrema

Local minima and maxima are interesting keypoints in an image. They are characterized as values surrounded by higher or lower values (4 or 8 depending on connexity). They can be easily detected by comparing the image to its dilation or erosion.

In some cases, the extrema form "plateaus", which are areas of equal values. The above method is no more appropriate. The RegionalMinima and RegionalMaxima functions ensure that every extremum is detected, whether it forms a plateau or not. A starting pixel is reported.

Reference:

Morpho::RegionalMinima and Morpho::Maxima.


Geometric Transformations

Geometric transforms do not explicitly modify the pixel values. Instead they move the location of the pixels, usually to compensate a deformation or displacement of some kind. These transformations are handled by the class Geometry.

In the simplest case, pixels are moved to new location with integer coordinates. But most often, the new locations do not fall exactly on integer coordinates so that resampling needs to take place: gray-level values must be estimated at the intermediate locations.

Two well known policies can be used for this purpose:

  • Nearest neighbor resampling: the value of the closest pixel center is used;
  • Bilinear interpolation: the four neighboring pixels are utilized to compute a piecewise bilinear interpolant at the given point.

Nearest neighbor vs. bilinear resampling

In addition to the resampling issue, aliasing problems may arise when the image size is strongly reduced. In this case, it needs to be low-pass filtered before resampling.

The Geometry class holds the methods that implement geometric transformations. They take a source image and turn it to another, possibly of a different size.


Linear and Affine Transformations

A very important class of geometric transformations is obtained when the equations are of the affine type. These transforms include

· translations,

· scalings,

· rotations & mirrorings (= rotation with reversal),

· similarities & reflections (= similarity with reversal),

· axial and central symmetries,

· parallel projections and

· shears.

The general affine transform is obtained by means of the method Affine, passing it the six transform coefficients.

Five specific cases of the affine transform are available: Flip (horizontal symmetry), Mirror (vertical symmetry), Turn (rotation in multiples of 90°), Rotate (similarity, a combination of translation, rotation and possibly scaling) and Skew. In addition, the DownSample method allows shrinking the image by a large factor without aliasing effects, and the UpSample method allows enlarging the image smoothly.

Example:

C++ Native

       // Rotate by 10 degrees about the fixed image center

       Geometry::Rotate(XY(320, 240), XY(320, 240), 10, 1, Src, Dst, true);

       // Then shrink in-place to a thumbnail

       Geometry::DownSample(64, 48, Dst, Dst);

C++.NET using namespace mVizNET;

       // Rotate by 10 degrees about the fixed image center

       Geometry::Rotate(XY(320, 240), XY(320, 240), 10, 1, Src, Dst, true);

       // Then shrink in-place to a thumbnail

       Geometry::DownSample(64, 48, Dst, Dst);

C# using mVizNET;

       // Rotate by 10 degrees about the fixed image center

       Geometry.Rotate(new XY(320, 240), new XY(320, 240), 10, 1, Src, Dst, true);

       // Then shrink in-place to a thumbnail

       Geometry.DownSample(64, 48, Dst, Dst);

Visual Basic

       ' Rotate by 10 degrees about the fixed image center

       mVizNET.Geometry.Rotate(New mVizNET.XY(320, 240), New mVizNET.XY(320, 240), 10, 1, Src, Dst, True)

       ' Then shrink in-place to a thumbnail

       mVizNET.Geometry.DownSample(64, 48, Dst, Dst)

Chip2  à  Flip Flip

Chip2  à  Mirror Mirror

Chip2  à  [image]    Turn (+1)

Chip2  à   DownSample DownSample (32 x32)

Chip2  à  Rotate Inter Rotate, interpolate (30°)

Chip2  à  Rotate Rotate, (30°)

Chip2  à  scale Inter Rotate, interpolate (0°, x1.5)

Chip2  à  Scale Rotate (0°, x1.5)

Chip2  à  Skew Inter Skew, interpolate

Chip2  à  Skew Skew


Anchor Points

To completely define the rotation and skewing transforms, so-called anchor points are utilized. An anchor point is a location on the source image, such as a feature point, that will map to a corresponding location on the destination, transformed image.

The more anchor points are used, the more degrees of freedom are modelled. In the case of a single anchor, a rotation angle and a scale factor can also be specified. In the case of two anchors, scaling can be disabled.

Transform | Method | Anchors | Parameters
Translation | Rotate | 1 | Angle = 0, Scale = 1
Translation+rotation (Isometry) | Rotate | 1 | Angle ¹ 0, Scale = 1
 | Rotate | 2 | Scaling = false
Translation+rotation+scaling (Similarity) | Rotate | 1 | Angle ¹ 0, Scale ¹ 1
 | Rotate | 2 | Scaling = true
Translation+rotation+scaling+skewing (Affinity) | Skew | 3 |

Single anchor, translation

Double anchor, translation, rotation & scaling

Triple anchor, general affine transform

Reference:

Geometry::Affine, Geometry::Mirror, Geometry::Flip, Geometry::Turn, Geometry::Rotate, Geometry::Skew, Geometry::DownSample, Geometry::UpSample.


Non-linear Transformations

Besides the affine transforms, the polar unwarping transform is important too. It unwinds a ring or annular sector to a rectangle shape and is handy to inspect circular objects. In mathematical terms, it moves the points from polar coordinates (Angle, Distance) to equivalent Cartesian coordinates (X, Y).

Check the method Unwind.

Example:

C++ Native

       // Unwarp the ring centered on the image

       // Full turn, extreme radii are 180 and 220 pixels

       // The destination size is (180 + 220) * Pi by 220 - 180

       Dst.Set(int((180 + 220) * 3.1416), 220 - 180);

       Geometry::Unwind(XY(320, 240), 0, 360, 180, 220, Src, Dst, true);

C++.NET using namespace mVizNET;

       // Unwarp the ring centered on the image

       // Full turn, extreme radii are 180 and 220 pixels

       // The destination size is (180 + 220) * Pi by 220 - 180

       Dst->Set(int((180 + 220) * 3.1416), 220 - 180, PixelTypes::Gray, (IntPtr)0, 0, 0);

       Geometry::Unwind(XY(320, 240), 0, 360, 180, 220, Src, Dst, true);

C# using mVizNET;

       // Unwarp the ring centered on the image

       // Full turn, extreme radii are 180 and 220 pixels

       // The destination size is (180 + 220) * Pi by 220 - 180

       Dst.Set((int)((180 + 220) * 3.1416), 220 - 180, PixelTypes.Gray, (IntPtr)0, 0, 0);

       Geometry.Unwind(new XY(320, 240), 0, 360, 180, 220, Src, Dst, true);

Visual Basic

       ' Unwarp the ring centered on the image

       ' Full turn, extreme radii are 180 and 220 pixels

       ' The destination size is (180 + 220) * Pi by 220 - 180

       Dst.Set(Int((180 + 220) * 3.1416), 220 - 180, mVizNET.PixelTypes.Gray, 0, 0, 0)

       mVizNET.Geometry.Unwind(New mVizNET.XY(320, 240), 0, 360, 180, 220, Src, Dst, True)

Reference:

Geometry::Unwind.


Acceleration

Some of the geometric transformations can be costly in terms of processor time. When the same transformation is used repetitively, you can compute and store it once for all in a so-called map image. This speeds-up subsequent uses of the transform.

To initialize a map, it suffices to use one of the above transformation methods and pass a destination image of type GeoMap instead of the targeted image type. When the map is built, the image is transformed by means of the Transform method.

Example:

C++ Native

       // Rotate by 10 degrees about the fixed image center, using a map

       // Compute the map

       Map.Set(Dst, GeoMap);

       Geometry::Rotate(XY(320, 240), XY(320, 240), 10, 1, Src, Map);

       // Apply the map

       Geometry::Transform(Map, Src, Dst);

       // Again...

       Geometry::Transform(Map, SrcA, DstA);

C++.NET using namespace mVizNET;

       // Rotate by 10 degrees about the fixed image center, using a map

       // Compute the map

       Map->Set(Dst, PixelTypes::GeoMap);

       Geometry::Rotate(XY(320, 240), XY(320, 240), 10, 1, Src, Map, true);

       // Apply the map

       Geometry::Transform(Map, Src, Dst, true);

       // Again...

       Geometry::Transform(Map, SrcA, DstA, true);

C# using mVizNET;

       // Rotate by 10 degrees about the fixed image center, using a map

       // Compute the map

       Map.Set(Dst, PixelTypes.GeoMap);

       Geometry.Rotate(new XY(320, 240), new XY(320, 240), 10, 1, Src, Map, true);

       // Apply the map

       Geometry.Transform(Map, Src, Dst, true);

       // Again...

       Geometry.Transform(Map, SrcA, DstA, true);

Visual Basic

       ' Rotate by 10 degrees about the fixed image center, using a map

       ' Compute the map

       Map.Set(Dst, mVizNET.PixelTypes.GeoMap)

       mVizNET.Geometry.Rotate(New mVizNET.XY(320, 240), New mVizNET.XY(320, 240), 10, 1, Src, Map, True)

       ' Apply the map

       mVizNET.Geometry.Transform(Map, Src, Dst, True)

       ' Again...

       mVizNET.Geometry.Transform(Map, SrcA, DstA, True)

Reference:

Geometry::Transform.


Coordinates calibration

In simple applications, the image coordinates are counted starting from the top-left pixel, with the X axis extending to the right and the Y axis to the bottom. These are the natural pixel coordinates.

In more advanced applications, world coordinates are required. This means that a coordinate system is attached to the observed scene or object, using arbitrary units of measurement, such as millimeters or microns, instead of pixels.

The Geometry object establishes the correspondence between the pixels and the world coordinate systems. There are two ways to do this, it is important to distinguish between them.


Simple vs. advanced calibration

Simple calibration just converts between pixels and world units using a proportionality rule. The reference frame remains orthogonal, with the origin at the top-left.

Simple calibration applies to all geometric measurements, including those obtained from

· blob analysis,

· gauging and

· template matching.

Advanced calibration allows more sophistication and flexibility:

- The reference frame can be defined arbitrarily and rotated.

- Imaging effects such as perspective and/or optical distortion can be corrected.

The coordinate transform is computed from a number of point coordinates given both in the image and world spaces.

Advanced calibration can be used in two ways:

1. Directly: point coordinates are converted from pixels to user units and vice-versa, with implicit distortion removal.

2. Indirecty: instead of correcting individual points, a complete image can be handled to remove distortion and generate a rectified image, which can be further processed.

Notes:

- The gauging functions are interfaced to direct calibration so that object can be measured even in the distorted space.

- The blob analysis and template matching functions do not work with direct calibration, as this would heavily impair the running time performance. Instead, you should operate on a corrected image and use simple calibration.


Simple Calibration

The class Geometry provides a SimpleCalibration method, taking two arguments: LengthInPixels (image coordinates) and TrueLength (world coordinates). You use them to evaluate the calibration factor, i.e. how many pixels in the image correspond to a given physical size.

Beware that when you have set the calibration factor, it remains in effect for all subsequent blob analysis, gauging or matching operation. To cancel its effect, call the function taking no argument or pass two equal values.

Example:

C++ Native

       // 45 pixels correspond to 10 microns

       Geometry::SimpleCalibration(45, 10);

C++.NET using namespace mVizNET;

       // 45 pixels correspond to 10 microns

       Geometry::SimpleCalibration(45, 10);

C# using mVizNET;

       // 45 pixels correspond to 10 microns

       Geometry.SimpleCalibration(45, 10);

Visual Basic

       ' 45 pixels correspond to 10 microns

       mVizNET.Geometry.SimpleCalibration(45, 10)

Reference:

Geometry::SimpleCalibration.


Advanced calibration

Advanced calibration does not assume that the world coordinates are proportional to the pixel indexes. The reference frame (coordinate origin) can be located arbitrarily, rotated, and scaled, and possible distortion corrected.

Different transforms are supported, with an increasing level of sophistication. These include rigid 2D motion, rigid planar 3D motion as well as optical distortion. The available modes are specified by the RegistrationModels enumeration.

Note that Mirroring is a Rotation such that the scene is viewed “from the other side” and the orientation of the coordinate axis is inverted. The same applied to Reflection vs. Similarity.


Degrees of freedom

In the figures below, you will see on the left the picture of a green square, as taken by a camera. The camera introduces different types of deformations. These are the image coordinates. On the right pictures, you see the ideal square obtained after correction has been performed, as the square is in reality. These are the world coordinates.

In the figures below, the coordinates on the left are uncalibrated (pixels) and calibrated (physical measurement) on the right.

  • Translation: simple change of the coordinates origin (2 DOF)

  • Scaling: change of the coordinates origin and axis scales (4 DOF)

  • Rotation/Mirroring: change of the coordinates origin and axis direction (3 DOF)

  • Similarity/Relection: change of coordinates origin, axis direction and isotropic scale (4 DOF)

  • Affinity: general linear transform including translation, rotation, scaling and shear (6 DOF)

  • Perspective: same as Affine plus 3D to 2D pinhole camera projection (8 DOF)

  • Quadratic: same as affine plus optical distortion (12 DOF)

  • General: all above effects (14 DOF)


Choosing the degrees of freedom

When selecting the degrees of freedom to use, it is wise to limit yourself to a minimum.

In many cases, it is just enough to specify the true size of the pixels and choose a convenient origin for the coordinates, so that the Scaling model is fine.

If in addition you want to compensate some rotation because if was impractical to align the camera, use the Similarity or Affinity model.

When you suspect significant perspective, i.e. when the viewing direction is not perfectly perpendicular, think of the Perspective model. And finally when there is visible optical distortion, choose one of the Quadratic or General model.


Computing the calibration transform

A transform is computed by supplying the coordinates of a number of corresponding points in the image and world coordinates. First the points are specified using the Append method. They are called anchor points. Then the ModelFit function is called, with the desired calibration model.

The Geometry object allows specifying more point pairs than required. A best fit procedure is applied to find good estimates of the parameters. More points will increase the accuracy. Anyway, outliers (i.e. invalid point pairs) can degrade the accuracy.

Mode | Anchors
Translation | 1
Rotation/Mirroring | 2
Scaling | 2
Similarity/Reflection | 2
Affinity | 3
Perspective | 4
Quadratic | 6
General | 7

Minimum number of anchor points

Unless not enough points are provided and unless they form a degenerate configuration, the transform is now ready for use.

Example:

C++ Native

       // Perspective calibration using a square

       Geometry World;

       // Add four anchor pairs (corners)

       World.Append(XY( 20,  32), XY(0, 0));

       World.Append(XY(217,  51), XY(1, 0));

       World.Append(XY(250, 234), XY(1, 1));

       World.Append(XY( 32, 243), XY(0, 1));

       // Fit

       World.ModelFit(Perspective);

C++.NET using namespace mVizNET;

       // Perspective calibration using a square

       Geometry^ World= gcnew Geometry;

       // Add four anchor pairs (corners)

       World->Append(XY( 20,  32), XY(0, 0));

       World->Append(XY(217,  51), XY(1, 0));

       World->Append(XY(250, 234), XY(1, 1));

       World->Append(XY( 32, 243), XY(0, 1));

       // Fit

       World->ModelFit(RegistrationModels::Perspective);

C# using mVizNET;

       // Perspective calibration using a square

       Geometry World = new Geometry();

       // Add four anchor pairs (corners)

       World.Append(new XY(20, 32), new XY(0, 0));

       World.Append(new XY(217, 51), new XY(1, 0));

       World.Append(new XY(250, 234), new XY(1, 1));

       World.Append(new XY(32, 243), new XY(0, 1));

       // Fit

       World.ModelFit(RegistrationModels.Perspective);

Visual Basic

       ' Perspective calibration using a square

       Dim World As mVizNET.Geometry = New mVizNET.Geometry

       ' Add four anchor pairs (corners)

       World.Append(New mVizNET.XY(20, 32), New mVizNET.XY(0, 0))

       World.Append(New mVizNET.XY(217, 51), New mVizNET.XY(1, 0))

       World.Append(New mVizNET.XY(250, 234), New mVizNET.XY(1, 1))

       World.Append(New mVizNET.XY(32, 243), New mVizNET.XY(0, 1))

       ' Fit

       World.ModelFit(mVizNET.RegistrationModels.Perspective)


Converting to calibrated or uncalibrated values

A point of arbitrary coordinates is transformed from the source space (image) to the destination space (world) by means of the Calibrate method.

Example:

C++ Native

       // Transform the image center

       XY DstPoint= World.Calibrate(XY(160, 120));

C++.NET using namespace mVizNET;

       // Transform the image center

       XY DstPoint= World->Calibrate (XY(160, 120));

C# using mVizNET;

       // Transform the image center

       XY DstPoint = World.Calibrate (new XY(160, 120));

Visual Basic

       ' Transform the image center

       Dim DstPoint As mVizNET.XY = World.Calibrate(New mVizNET.XY(160, 120))

Sometimes it is useful to perform the converse operation, i.e. retrieving the pixel that corresponds to given world values. This is made via the Decalibrate method.

Example:

C++ Native

       // Transform back

       XY SrcPoint= World.Decalibrate(DstPoint);

C++.NET using namespace mVizNET;

       // Transform back

       XY SrcPoint= World->Decalibrate(DstPoint);

C# using mVizNET;

       // Transform back

       XY SrcPoint = World.Decalibrate(DstPoint);

Visual Basic

       ' Transform back

       Dim SrcPoint As mVizNET.XY = World.Decalibrate(DstPoint)

Reference:

Geometry::Calibrate, Geometry::Decalibrate.


Correcting an image

As mentioned, the calibration transform can be used to convert the image coordinates to world coordinates and back for isolated points known by their coordinates.

The same process can be applied to a whole image, with the effect of canceling the distortion. Indeed, when taking all source pixels and moving them to undistorted positions will create an ideal image with distortion removed.

Rectification is achieved with the method Undistort, taking a source and a destination image. Two interpolation modes are available: nearest neighbor, fast but less accurate, or bilinear interpolation.

Important note: for this operation, the output is an image, which must have a consistent size in pixels. For this reason, the undistort function uses the simple calibration coefficient and you must assign it a suitable value.

For instance, if your image is 640 x 480, with a field of view roughly 4 x 3 mm, the calibrated abscissas along the top edge will range, say, from 0.5 to +4.5 mm. Setting the simple calibration coefficients to 160 pixel/mm will make these values correspond to 80 and 720 pixels respectively in the undistorted image.

(If you don’t set this scale, the coordinate values will remain 0.5 and 4.5 pixels, most probably far too small.)

Example:

       C++ Native

       // 640 pixels correspond to 4 mm

       Geometry::SimpleCalibration(640, 4);

       // Rectify the image

       World.Undistort(Src, Dst);

C++.NET using namespace mVizNET;

       // 640 pixels correspond to 4 mm

       Geometry::SimpleCalibration(640, 4);

       // Rectify the image

       World->Undistort(Src, Dst);

C# using mVizNET;

       // 640 pixels correspond to 4 mm

       Geometry.SimpleCalibration(640, 4);

       // Rectify the image

       World.Undistort(Src, Dst);

Visual Basic

       ' 640 pixels correspond to 4 mm

       mVizNET.Geometry. SimpleCalibration(45, 10)

       ' Rectify the image

       World.Undistort(Src, Dst)

Remember: when you have obtained an undistorted image, applying the simple calibration to it gives exact world coordinates. This is the way to work, for instance, if you want to perform blob analysis on a distorted image and get true measurements.

Reference:

Geometry::SimpleCalibration, Geometry::Undistort.


Calibration with a Target

Finding the anchor points in an image requires to set-up appropriate feature detection, which can be an ad hoc task.

In the art of practioners, calibration targets are convenient tools that can be manufactured with good accuracy and come in two standard patterns: dot grid or chessboard.

The Geometry class supplies a method CalibrateTarget to automatically analyze an image of such a target, find the dots or squares and assign them coordinates.

Chessbord target with the origin on the top-left corner

The same, undistorted

The GridStep parameter allows to specify the grid spacing in world units. The contrast is given as the BlackOnWhite argument, and the pattern type as the Boolean Chessboard.

Lastly, the argument OriginColumn/OriginRow allows to choose where the world coordinate origin must be placed, indexing the dots/squares of the target; integer values correspond to the centers of the dots/squares, while half-integer values are midway between centers (on the edge of squares). It is important to understand that the origin point is not positioned in image nor world coordinates, but in the natural system formed by the pattern of columns and rows.

Reference:

Geometry::CalibrateTarget.


Image registration

Images registration is similar to image calibration in that it utilizes the same image deformation models. The goal of registration is to realign two pairs of images, given a number of point pairs corresponding to the same features in the image, in such a way that all points can be exactly overlaid. Registration is performed for comparison purposes or other.

Reference:

Geometry::ReverseRegister.


Computing the registration transform

This is done in exactly the same way as for the calibration transform, except that all coordinate values are in pixels.


Applying the transform

A point of arbitrary coordinates is transformed from the source image to the destination image by means of the Register method.

Example:

C++ Native

       // Transform the image center

       XY DstPoint= World.Register(XY(160, 120));

C++.NET using namespace mVizNET;

       // Transform the image center

       XY DstPoint= World->Register(XY(160, 120));

C# using mVizNET;

       // Transform the image center

       XY DstPoint = World.Register(new XY(160, 120));

Visual Basic

       ' Transform the image center

       Dim DstPoint As mVizNET.XY = World.Register(New mVizNET.XY(160, 120))

Conversely, a point of arbitrary coordinates is transformed back to the source space from the destination space by means of the ReverseRegister method.

Example:

C++ Native

       // Transform back

       XY SrcPoint= World.ReverseRegister(DstPoint);

C++.NET using namespace mVizNET;

       // Transform back

       XY SrcPoint= World->ReverseRegister(DstPoint);

C# using mVizNET;

       // Transform back

       XY SrcPoint = World.ReverseRegister(DstPoint);

Visual Basic

       ' Transform back

       Dim SrcPoint As mVizNET.XY = World.ReverseRegister(DstPoint)

Reference:

Geometry::Register, Geometry::ReverseRegister.


Matching two images

When a registration transform is defined, the source image can be deformed to match the destination one so that the given feature points are put in correspondence. This is done by the method Register.

Symmetrically, the destination can be deformed to match the source, by a call to ReverseRegister.

As all coordinates are in pixels, there is no need to worry about a scaling factor, usually. Anyway, for images obtained from different imaging modalities, difference in device resolutions can be dealt with using the simple calibration coefficient.

Reference:

Geometry::Register, Geometry::ReverseRegister.


Multi-resolution Processing

In some applications, it is useful to process images at different scales simultaneously or in a sequence. This serves two purposes:

- Being able to process features of widly varying sizes,

- Optimizing for speed by working at small scale to produce gross results, and refining to better resolution from the gross results.

The Pyramid object supplies methods to support these processes. Two types of pyramids are possible:

- Dyadic, i.e. such that every level has half the linear resolution of the previous; Hence the image area reduces to a quarter each time;

- Two-thirds, i.e. such that every level has tow-thirds of the linear resolution of the previous. Hence the image area reduces to roughly a half each time ( [image] ).

Dyadic pyramid


Subsampling and supersampling

A complete set of reduced images can be built from a source image in a single go by means of the method Build. Two options are possible regarding the storage of the base of the pyramid (i.e. the full resolution image): either the original source image is kept, or it is copied inside the pyramid. The first option spares an image copy.

An image pyramid can be drawn in a single go with Draw and DrawingOffset.

You can also downsample an image to a single level with half (dyadic) or two-thirds resolution using Halve; or upsample it to double resolution with Double.


Tiling

In other applications, you want to compress the image by replacing tiles, i.e. contiguous squares of pixel by a single value that summarizes it. The Pyramid object allows you to compute the average gray, standard deviation, range or mid-range in such tiles. They represent the local central trend or dispersion. The corresponding methods are TileMean, TileMidRange, TileDeviation and TileRange.

Standard deviation in 3x3 tiles

Note that these functions are optimized for tile sizes that are a small power of two, but any size is possible.

The method TileWindow will set the target image to the coordinates of any tile, making it ready for further processing, for instance by computing some statistical estimator from the histogram.


Profiles

In mViz, 1D signals are stored and manipulated as instances of the Profile class.

A grayscale profile, from an image

Example:

C++ Native

       // Declare a void profile object

       Profile Row;

C++.NET using namespace mVizNET;

       // Declare a void profile object

       Profile^ Row= gcnew Profile;

C# using mVizNET;

       // Declare a void profile object

       Profile Row = new Profile();

Visual Basic

       ' Declare a void profile object

       Dim Row As mVizNET.Profile = New mVizNET.Profile

A profile is a vector comprising Length values, or samples. By default, the samples have grayscale values encoded as signed 32 bits integers. The size of a profile can be specified using the method Set.

Example:

C++ Native

       // Size the whole profile as 128 grayscale (default) values

       Row.Set(128);

C++.NET using namespace mVizNET;

       // Size the whole profile as 128 grayscale (default) values

       Row->Set(128, PixelTypes::Gray, (IntPtr)0, 0);

C# using mVizNET;

       // Size the whole profile as 128 grayscale (default) values

       Row.Set(128, PixelTypes.Gray, (IntPtr)0, 0);

Visual Basic

       ' Size the whole profile as 128 grayscale (default) values

       Row.Set(128, mVizNET.PixelTypes.Gray, 0, 0)

At any time, samples can be appended to the end of the profile. This is done via the method Append, to which the new sample value is passed.

Example:

C++ Native

       // Append one value

       Row.Append(64);

C++.NET using namespace mVizNET;

       // Append one value

       Row->Append(64);

C# using mVizNET;

       // Append one value

       Row.Append(64);

Visual Basic

       ' Append one value

       Row.Append(64)

Individual profile samples can be accessed for reading or changing the value by means of the Sample method to which the sample index is passed.

Example:

C++ Native

       // Set to white

       Row.Sample(10)= 255;

C++.NET using namespace mVizNET;

       // Set to white

       Row->Sample(10, 255);

C# using mVizNET;

       // Set to white

       Row.Sample(10, 255);

Visual Basic

       ' Set to white

       Row.Sample(10, 255)

As for images, it may make sense to limit processing to an interval of interest, by specifying the index of its first sample and its length. This is done via the method Window.

Profile window

Example:

C++ Native

       // Use an interval of interest, 100 values, centered

       Row.Window(14, 100);

       // More code...

       // Revert to the full profile

       Row.Window();

C++.NET using namespace mVizNET;

       // Use an interval of interest, 100 values, centered

       Row->Window(14, 100);

       // More code...

       // Revert to the full profile

       Row->Window();

C# using mVizNET;

       // Use an interval of interest, 100 values, centered

       Row.Window(14, 100);

       // More code...

       // Revert to the full profile

       Row.Window();

Visual Basic

       ' Use an interval of interest, 100 values, centered

       Row.Window(14, 100)

       ' More code...

       ' Revert to the full profile

       Row.Window()

A profile is plotted to the application window with method Plot. If required, another drawing window can be specified by means of Graph::DrawTo.

Example:

C++ Native

       // Plot the profile values

       Row.Plot(0, 0, 512, 128);

C++.NET using namespace mVizNET;

       // Plot the profile values

       Row->Plot(0, 0, 512, 128, false, 0, 0, (IntPtr)0, 0);

C# using mVizNET;

       // Plot the profile values

       Row.Plot(0, 0, 512, 128, false, 0, 0, (IntPtr)0, 0);

Visual Basic

       ' Plot the profile values

       Row.Plot(0, 0, 512, 128, False, 0, 0, 0, 0)

Reference:

Profile::Set, Profile::Sample, Profile::Window, Profile::Append, Profile::Plot, Graph::DrawTo.


Profile sampling

You can get a profile from a 2D image. Two variants are available: profiles can be extracted along a thin line segment i.e. an image row or image column. Check the Row and Column methods for this purpose.

Profiles can also be computed from a thick line segment i.e. multiple image row or columns, by adding or averaging them together. Check the RowSum and ColumnSum methods.

Example:

C++ Native

       // Project the ten first source columns to the destination profile

       Row.ColumnAdd(0, 10, Src);

C++.NET using namespace mVizNET;

       // Project the ten first source columns to the destination profile

       Row->ColumnAdd(0, 10, Src, true);

C# using mVizNET;

       // Project the ten first source columns to the destination profile

       Row.ColumnAdd(0, 10, Src, true);

Visual Basic

       ' Project the ten first source columns to the destination profile

       Row.ColumnAdd(0, 10, Src, True)

Reference:

Profile::Row, Profile::Column, Profile::RowSum, Profile::ColumnSum.


Profile Processing

A profile contains a 1D discrete signal that can be processed in simple ways.

You retrieve elementary profile statistics such as the mean, trimmed mean, median (central trends) or range and variance (spread). Use one of Quantile, Mean, TrimmedMean, Median, Range or Variance.

You can obtain the derivative or primitive (integrated) signal. Use one of Derive or Integrate.

You can filter using a uniform or Gaussian window. Use one BoxLowPass, GaussLowPass or BoxHighPass.

Gaussian smoothing of a profile

Example:

C++ Native

       // Pass a Gaussion filter of extent 25, in-place

       Profile::GaussLowPass(25, Row, Row);

C++.NET using namespace mVizNET;

       // Pass a Gaussion filter of extent 25, in-place

       Profile::GaussLowPass(25, Row, Row);

C# using mVizNET;

       // Pass a Gaussion filter of extent 25, in-place

       Profile.GaussLowPass(25, Row, Row);

Visual Basic

       ' Pass a Gaussion filter of extent 25, in-place

       Profile.GaussLowPass(25, Row, Row)

Reference:

Profile::Quantile, Profile::Mean, Profile::TrimmedMean, Profile::Median, Profile::Range, Profile::Variance, Profile::Derive, Profile::Integrate, Profile::BoxLowPass, Profile::GaussLowPass, Profile::BoxHighPass.


Lookup-tables

A profile can be used to define a transformation of the gray-level scale, for different purposes. A LUT (lookup-table) can be used to transform all pixels in an image very efficiently since the transformation is precomputed. mViz offers the following:

· GainOffset modifies the contrast and lightness.

· Threshold has the same effect as the Operator::Binarize function, and lets you specify the final pixel values.

· BiThreshold is for double thresholding (low and high thresholds).

· Quantize is for multiple thresholds equally spaced.

· Logarithm is used to turn multiplicative effects into additive ones.

· Gamma is to deal with a gamma precompensation/compression of some acquisition or rendering devices.

· Pseudocolor is for visual purposes, it produces a colored rainbow.

And obviously, you can define your own lookup-table by means of the Profile methods.

When a LUT is defined, you apply it to a whole image with Operator::Transform. In the case of the Pseudocolor LUT, the resulting image is of type Rgb. You can also use it just at display time, by passing it as an argument to Image::Draw. In this case, the image remains unchanged.

Reference:

Profile::GainOffset , Profile::Threshold , Profile::BiThreshold , Profile::Quantize , Profile::Logarithm , Profile::Gamma , Profile::PseudoColor , Operator::Transform and Image::Draw.


Accessing the profile buffer

Usually, the profile pixels are stored in an area of memory which is transparently allocated/deallocated by the Profile object. The user can directly access this data from the property named Buffer. The values are stored contiguously. Every profile sample requires Pitch bytes.

Example:

C++ Native

       // Output the buffer parameters

       printf("Address: 0x%08x - Pitch: %d\n", Row.Buffer, Row.Pitch);

C++.NET using namespace mVizNET;

       // Output the buffer parameters

       Console::WriteLine("Address:
{0:x8}x - Pitch: {1}", int(Row->Buffer),
Row->Pitch);

C# using mVizNET;

       // Output the buffer parameters

       Console.WriteLine("Address: {0:x8}x - Pitch: {1}", (int)(Row.Buffer), Row.Pitch);

Visual Basic

       ' Output the buffer parameters

       Console.WriteLine("Address: {0:x8}x - Pitch: {1}", Row.Buffer, Row.Pitch)


Advanced: Using an external profile buffer

If wanted, the user can provide an external buffer that holds the profile data and specify the appropriate Pitch value.

Example:

C++ Native

       // Use an external data buffer with the default pitch

       int RowData[512];

       Row.Set(512, Gray, RowData);

C++.NET using namespace mVizNET;

       // Use an external data buffer with the default pitch

       int RowData[512];

       Row->Set(512, PixelTypes::Gray, (IntPtr)RowData, 0);

C# using mVizNET;

       // Use an external data buffer with the default pitch (unsafe code)

       int[] RowData = new int[512];

       fixed (int* Data = &RowData[0])

       {

           Row.Set(512, PixelTypes.Gray, (IntPtr)Data, 0);

       }

Visual Basic

       ' Use an external data buffer with the default pitch

       Dim RowData(512) As Integer

       Row.Set(512, mVizNET.PixelTypes.Gray, RowData(0))

Reference:

Profile::Buffer, Profile::Pitch, Profi le::Type.


Paths

A path is a list of points, also called Sites. It can be used to represent curves, when the sites are neighboring each other, as well as polylines. The class Path is defined.

A path traced on an image

Example:

C++ Native

       // Declare a void path object

       Path Outline;

C++.NET using namespace mVizNET;

       // Declare a void path object

       Path^ Outline= gcnew Path;

C# using mVizNET;

       // Declare a void path object

       Path Outline = new Path();

Visual Basic

       ' Declare a void path object

       Dim Outline As mVizNET.Path = New mVizNET.Path()

A path is a vector comprising Length sites, each having X and Y coordinates encoded as signed 16 bits integers (-32768 to +32767).

At any time, sites can be appended to the end of the path. This is done by the method Append, to which the site coordinates are passed.

Example:

C++ Native

       // Append one site

       Outline.Append(Site(100, 200));

C++.NET using namespace mVizNET;

       // Append one site

       Outline->Append(Site(100, 200));

C# using mVizNET;

       // Append one site

       Outline.Append(new Site(100, 200));

Visual Basic

       ' Append one site

       Outline.Append(New mVizNET.Site(100, 200))

Individual path sites can be accessed for reading or changing the value by means of the Vertex method to which a zero-based index is passed.

Example:

C++ Native

       // Get the abscissa of the first vertex

       int X= Outline.Vertex(0).X;

C++.NET using namespace mVizNET;

       // Get the abscissa of the first vertex

       int X= Outline->Vertex(0).X;

C# using mVizNET;

       // Get the abscissa of the first vertex

       int X = Outline.Vertex(0).X;

Visual Basic

       ' Get the abscissa of the first vertex

       Dim X As Integer = Outline.Vertex(0).X

A path is plotted onto the application window with the method Draw. If required, another drawing window can be specified by means of Graph::DrawTo. Paths can be drawn opened or closed, depending on the property Closed.

Example:

C++ Native

       // Plot the closed path

       Outline.Closed= true;

       Outline.Draw();

C++.NET using namespace mVizNET;

       // Plot the closed path

       Outline->Closed= true;

       Outline->Draw(false);

C# using mVizNET;

       // Plot the closed path

       Outline.Closed = true;

       Outline.Draw(false);

Visual Basic

       ' Plot the closed path

       Outline.Closed = True

       Outline.Draw(False)

Reference:

Path::Append,
Path::Vertex, Path::Draw,
Path::Closed, Graph::DrawTo.


Extracting a contour path

A path can be defined by contouring, i.e. by following the outline of the blob obtained by binarization above a given threshold. The coordinates of a starting point must be provided. Use method Follow.

Example:

C++ Native

       // Get a contour path in image Src, from point (100, 200)

       Outline.Follow(Site(100, 200), 128, Src);

C++.NET using namespace mVizNET;

       // Get a contour path in image Src, from point (100, 200)

       Outline->Follow(Site(100, 200), 128, Src, true, true, true);

C# using mVizNET;

       // Get a contour path in image Src, from point (100, 200)

       Outline.Follow(new Site(100, 200), 128, Src, true, true, true);

Visual Basic

       ' Get a contour path in image Src, from point (100, 200)

       Outline.Follow(New mVizNET.Site(100, 200), 128, Src, True, True, True)

Reference:

Path::Follow.


Path features

Several numerical (scalar and non-scalar) features can be obtained from a path, and used for classification purposes or other post-processing.

They are the Area, bounding Box, gravity Center, filled gravity center (FilledCenter), Ellipse of inertia, filled ellipse of inertia (FilledEllipse), Mass, Centroid, convex hull (ConvexHull) and specifically for shape control applications, line and circle deviation (LineDeviation, CircleDeviation).

Reference:

Path::Area, Path::Box,
Path::Center, Path::FilledCenter, Path::Ellipse, Path::FilledEllipse, Path::Mass,
Path::Centroid, Path::ConvexHull, Path::LineDeviation, Path::CircleDeviation.


Path Feature Formulas

This section explains how the available features are computed from the path coordinates and values.


Area

The area is computed as the number of pixels included in the blob.

Count of the pixels


Bounding Box

The X and Y values are the minimum abscissa and ordinate of the pixels in the blob; the Width and Height values are the difference between the maximum and minimum abscissas/ordinates plus one.

Bounding box


Perimeter

When the flag Euclidean is set to true, the shortest distance between the pixels is used.

When false, the Mahattan distance is used.


Gravity Center

The gravity center is the arithmetic average of the coordinates along the path.

Gravity center


Filled Gravity Center

The filled gravity center is also the arithmetic average but all the pixels inside the path are also implied, as if it was a blob.

Gravity center, filled


Ellipse

The ellipse of inertia is centered on the gravity center. The Width and Height are the major and minor axis of the ellipse of inertia, computed from the first and second order moments of the coordinates, assuming uniform distribution of the mass over the pixels. The angle is the direction of the major axis.

Equivalent ellipse


Filled Ellipse

By contrast with the ellipse feature, the pixels inside the blob are also utilzed in the computation.

Equivalent ellipse, filled


Mass

Sum of the gray-levels along the path.


Centroid

The centroid is a weighted average of the coordinates where the weights are the pixel values.

x

x

Weighted average of the coordinates


Convex hull

The convex hull is the tightest convex polygon that surrounds the pixel centers of the given blob.

Tightest convex polygon


Gray Histogram

The histogram is the count of every gray-level value for the pixels along the path.


Line Deviation

Average perpendicular distance to a best-fit line.

RMS:

Absolute:


Circle Deviation

Average perpendicular distance to a best-fit circle.

RMS:

Absolute:


Regions

A region is an area of arbitrary shape, supported by the class Region. It doesn’t need to be connected (doesn’t need to be a single piece) and can have holes.

Regions can be defined in many different ways:

· by binarizing an image (method Binarize),

· by using existing blobs from a Blobs object (method BlobAppend),

· by filling the inside of a path (method PathAppend) or

· by adding already existing region(s (method RegionAppend) or

· the quadrilateral spanned by a Quad object (method QuadAppend), which can be curved,

· by combining several existing regions (methods Unite, Intersect, Subtract).

A single region derived from a rectangle and a path

Using these various modalities allows you to create regions of a complex shape, without limitations.

Example:

C++ Native

       // Position a rectangle (Quad)

       Rect.Set(215, 117, 120, 60);

       // Turn it to a region mask (Region)

       Mask.QuadAppend(Rect);

       // Follow an outline (Path)

       Outline.Follow(Site(353, 274), 182, Src, true, true, true);

       // Add it to the mask (Region)

       Mask.PathAppend(Outline);

C++.NET using namespace mVizNET;

       // Position a rectangle (Quad)

       Rect.Set(215, 117, 120, 60);

       // Turn it to a region mask (Region)

       Mask.QuadAppend(Rect);

       // Follow an outline (Path)

       Outline.Follow(mVizNET::Site(353, 274), 182, Src, true, true, true);

       // Add it to the mask (Region)

       Mask.PathAppend(Outline);

C# using mVizNET;

       // Position a rectangle (Quad)

       Rect.Set(215, 117, 120, 60);

       // Turn it to a region mask (Region)

       Mask.QuadAppend(Rect);

       // Follow an outline (Path)

       Outline.Follow(mVizNET.Site(353, 274), 182, Src, true, true, true);

       // Add it to the mask (Region)

       Mask.PathAppend(Outline);

Visual Basic

       ' Position a rectangle (Quad)

       Rect.Set(215, 117, 120, 60);

       ' Turn it to a region mask (Region)

       Mask.QuadAppend(Rect);

       ' Follow an outline (Path)

       Outline.Follow(mVizNET.Site(353, 274), 182, Src, True, True, True);

       ' Add it to the mask (Region)

       Mask.PathAppend(Outline);

A region can also be created by adding a series of horizontal runs (method Append), which is how regions are represented internally.

Reference:

Region::Append, Region::Binarize, Region::BlobAppend, Region::PathAppend, Region::RegionAppend, Region::QuadAppend. Region::Unite, Region::Intersect and Region::Subtract.


Processing in a region

The main usage of regions is to get statistics about the gray-level distribution of the covered pixels (see the next section on Histograms).

You can also perform blob analysis inside a region mask, to get results from delimited areas. See the overloads of Segment that take a Mask argument.

Regions can also be used to delimit the training area during the learning phase of template matching. See the overload of Train that takes a Mask argument.

Note that processing the inside of a region by means of point-to-point (arithmetic and others) or neighborhood operations (convolutions, morphology) is more efficient when using a rectangular Window and is the preferred way in mViz.

Example:

C++ Native

       // Follow a path (Path)

       Outline.Follow(Site(353, 274), 182, Src, true, true, true);

       // Fill the inside to create a region (Region)

       Inside.PathAppend(Outline, 0);

       // Get the histogram of the region (Histogram)

       Statistics.Compute(Src, Inside, true);

C++.NET using namespace mVizNET;

       // Follow a path (Path)

       Outline->Follow(mVizNET::Site(353, 274), 182, Src, true, true, true);

       // Fill the inside to create a region (Region)

       Inside->PathAppend(Outline, 0);

       // Get the histogram of the region (Histogram)

       Statistics->Compute(Src, Inside, true);

C# using mVizNET;

       // Follow a path (Path)

       Outline.Follow(mVizNET.Site(353, 274), 182, Src, true, true, true);

       // Fill the inside to create a region (Region)

       Inside.PathAppend(Outline, 0);

       // Get the histogram of the region (Histogram)

       Statistics.Compute(Src, Inside, true);

Visual Basic

       ' Follow a path (Path)

       Outline.Follow(mVizNET.Site(353, 274), 182, Src, True, True, True)

       ' Fill the inside to create a region (Region)

       Inside.PathAppend(Outline, 0)

       ' Get the histogram of the region (Histogram)

       Statistics.Compute(Src, Inside, True)

Reference:

Histogram::Compute, Blobs::Segment and Locator::Train.


Combining regions

Once you have created individual regions, it is possible to combine them using the well-known Boolean operators (also called set-theoretic ones): union, intersection or subtraction. These are new regions formed of the pixels belonging to one of the given regions, to both regions or to the first and not the second.

Boolean operators [image] , [image] and

Note that the subtraction operator is asymmetric, do not confuse it with the disjunction.

Example:

We create a rectangle (red) and a circle (green) using a Quad shape, then compute their intersection (blue).

The blue area is an intersection

C++ Native

       // Define rectangle Quad and circle Circ

       Rect.SetMiddle(200, 100, 200, 100, 15);

       Circ.SetCenter(300, 150, 200, 200/3.1416, 0, 360);

       // Convert to regions R and C

       R.QuadAppend(Rect);

       C.QuadAppend(Circ);

       // Intersect, giving I

       I.Intersect(R, C);

C++.NET using namespace mVizNET;

       // Define rectangle Quad and circle Circ

       Rect->SetMiddle(200, 100, 200, 100, 15, 0);

       Circ->SetCenter(300, 150, 200, 200/3.1416, 0, 360);

       // Convert to regions R and C

       R->QuadAppend(Rect);

       C->QuadAppend(Circ);

       // Intersect, giving I

       I->Intersect(R, C);

C# using mVizNET;

       // Define rectangle Quad and circle Circ

       Rect.SetMiddle(200, 100, 200, 100, 15, 0);

       Circ.SetCenter(300, 150, 200, 200/3.1416, 0, 360);

       // Convert to regions R and C

       R.QuadAppend(Rect);

       C.QuadAppend(Circ);

       // Intersect, giving I

       I.Intersect(R, C);

Visual Basic

       // Define rectangle Quad and circle Circ

       Rect.SetMiddle(200, 100, 200, 100, 15, 0);

       Circ.SetCenter(300, 150, 200, 200/3.1416, 0, 360);

       // Convert to regions R and C

       R.QuadAppend(Rect);

       C.QuadAppend(Circ);

       // Intersect, giving I

       I.Intersect(R, C);

Reference:

Region::Unite, Region::Intersect and Region::Subtract.


Region morphology

The same way that an image can be dilated or eroded using a structuring element with a variable shape (square, diamond, rectangular…), you can apply these operations to an exisiting region. The following methods are available: Dilate, Erode, Gradient.

Another operation is Containment. It allows you to compare two regions to decide if one is inside the other, if the are disjoint or intersect. Check the method Containment. The result of the function is a value among RangeMode.

Reference:

Region::Dilate, Region::Erode, Region::Gradient and Region::Containment.


Region Features

After you have defined a region, you can query if for a few features:

- Area: number of pixels inside it.

- Center: geometric center (gravity center).

- Box: tightest axis-aligned bounding rectangle.

- Rectangle: tightest bounding rectangle, with rotation.

- Circle: tightest bounding circle.

- Mean: average gray-level value in an image, inside the region.

- Variance: variance of the gray-level values in an image, inside the region.

Reference:

Region::Area,
Region::Center, Region::Box,
Region::Rectangle, Region::Circle, Region::Mean
and Region::Variance.


The Quad Shape

In order to define flexible shapes, a special class named Quad is available. It consists of a rectangle, possibly rotated and possibly curved. When the curve makes a full circle, it turns to a ring. And when the inner radius is null, you get a circle.

To obtain these shapes, use the following overloads:

// Axis-aligned Rectangle

void Set(int XLeft, int YTop, int Width, int Height);

// Rotated Rectangle/Wedge at a Given Corner Point

void SetOrigin(double Xo, double Yo, double Width, double Height, double Angle, double Bend= 0);

// Rotated Rectangle/Wedge at a Given Middle Point (= center)

void SetMiddle(double Xm, double Ym, double Width, double Height, double Angle, double Bend= 0);

// Wedge Centered at a Given Point, Size and Aperture

void SetCenter(double Xc, double Yc, double Width, double Height, double Angle, double Bend);

// Wedge Centered at a Given Point, Radii and Delimiting Angles

void SetWedge(double Xc, double Yc, double InnerRadius, double OuterRadius, double BegAngle, double EndAngle);

// Full Circle Centered at a Given Point

void SetCenter(double Xc, double Yc, double Radius, double Angle= 0);

The origin is the top-left corner of the rectangle or wedge. The middle is the intersection of the medians. The center is the center of curvature.

The Quad objects can be drawn and dragged with the mouse cursor, using the usual Draw, HitHandle and Drag methods.

Reference:

Quad::Set, Quad::SetOrigin, Quad::SetMiddle, Quad::SetCenter, Quad::SetWedge, Quad::Draw, Quad::HitHandle and Quad::Drag.


Advanced: Filtering in a Region

For fast processing, the image filters in mViz operate in a rectangular window. In some cases, though, you will want to modify an image partially, only inside a region. You can use the following method: apply the filter to the whole image, out-of-place. Then copy back the result of the filtering to the initial image, inside the desired region. The method Fill, which selectively copies, is made for this purpose.

C++ Native

       // Define a wedge region

       Quad Q; Q.SetWedge(200, 200, 50, 150, 45, 225);
       Region Wedge; Wedge.QuadAppend(Q);

       // Apply a Prewitt filter on an image of the same size
       Kernel::Prewitt(Src, Prewitt0, Rescale);

       // Transfer to the source image, inside the wedge
       Wedge.Fill(Prewitt0, Src);

Filtering in a wedge region

Notice that the above procedure will not be efficient for small regions, as the whole image is transformed. To work around this problem, you can define a tight window around the region, as provided by the method Box, and process only inside that window.

C++ Native

// Define a wedge region
Quad
Q; Q.SetWedge(200, 200, 50, 150, 45, 225);
Region Wedge; Wedge.QuadAppend(Q);

// Get the region bounding box, with a 1 pixel
margin
Limits L= Wedge.Box(1);

// Apply the Prewitt filter in the bounding
box, using an image of the same size
Prewitt0.Set(Src);

Src.Window(L); Prewitt0.Window(L);
Kernel::Prewitt(Src, Prewitt0, Rescale);
Src.Window(); Prewitt0.Window();

// Transfer to the source image, inside
the wedge
Wedge.Fill(Prewitt0, Src);

Reference:

Region::Fill and Region::Box.


Advanced: Region Edition

You can access the individual runs that make up a region, by means of the accessors NumRuns and Run, for instance to implement your own shape. [You can even modify the coordinates in these runs.]

You can also add new runs yourself. Anyway, you should make it in such a way that no runs overlap. See Append.

Reference:

Region::NumRuns and Region::Run and Region::Append.


Histograms

The statistical distribution of gray-levels in an image is conveniently studied by means of histograms, i.e. the sequence of pixel counts for every possible gray-level value.

Histograms are handled by the class Histogram. (A histogram is also a special case of a Profile object.)

Plot of gray values frequencies

Example:

C++ Native

       // Declare a void histogram object

       Histogram Histo;

C++.NET using namespace mVizNET;

       // Declare a void histogram object

       Histogram^ Histo= gcnew Histogram;

C# using mVizNET;

       // Declare a void histogram object

       Histogram Histo = new Histogram();

Visual Basic

       ' Declare a void histogram object

       Dim Histo As mVizNET.Histogram = New mVizNET.Histogram

A histogram is a vector comprising Length 32 bits integer values, or bins, holding frequency counts. The size of a histogram can be specified using the method Set but usually this is done by the methods you call.

Example:

C++ Native

       // Size the whole histogram as having 256 bins

       Histo.Set(256);

C++.NET using namespace mVizNET;

       // Size the whole histogram as having 256 bins

       Histo->Set(256, PixelTypes::Gray, (IntPtr)0, 0);

C# using mVizNET;

       // Size the whole histogram as having 256 bins

       Histo.Set(256, PixelTypes.Gray, (IntPtr)0, 0);

Visual Basic

       ' Size the whole histogram as having 256 bins

       Histo.Set(256, mVizNET.PixelTypes.Gray, 0, 0)

At any time, bins can be appended to the end of the histogram. This is done via method Append, to which the new bin value is passed.

Example:

C++ Native

       // Append one frequency value

       Histo.Append(64);

C++.NET using namespace mVizNET;

       // Append one frequency value

       Histo->Append(64);

C# using mVizNET;

       // Append one frequency value

       Histo.Append(64);

Visual Basic

       ' Append one frequency value

       Histo.Append(64)

Individual histogram bins can be accessed for reading or changing the value by means of the Bin method to which the bin index is passed.

Example:

C++ Native

       // Clear a bin

       Histo.Bin(10)= 0;

C++.NET using namespace mVizNET;

       // Clear a bin

       Histo->Bin(10, 0);

C# using mVizNET;

       // Clear the bin at index 10

       Histo.Bin(10, 0);

Visual Basic

       ' Clear a bin

       Histo.Bin(10, 0)

In certain circumstances, it all makes sense to limit processing to an interval of interest, by specifying the index of its first bin and its length. This is done via the method Window.

Histogram window

Example:

C++ Native

       // Use an interval of interest, 100 values, centered

       Histo.Window(78, 100);

       // More code...

       // Revert to the full histogram

       Histo.Window();

C++.NET using namespace mVizNET;

       // Use an interval of interest, 100 values, centered

       Histo->Window(78, 100);

       // More code...

       // Revert to the full histogram

       Histo->Window();

C# using mVizNET;

       // Use an interval of interest, 100 values, centered

       Histo.Window(78, 100);

       // More code...

       // Revert to the full histogram

       Histo.Window();

Visual Basic

       ' Use an interval of interest, 100 values, centered

       Histo.Window(78, 100)

       ' More code...

       ' Revert to the full histogram

       Histo.Window()

A histogram is plotted to the application window with method Plot. If required, another drawing window can be specified by means of Graph::DrawTo.

Example:

C++ Native

       // Plot the histogram values in a 512 x 128 frame

       Histo.Plot(0, 0, 512, 128);

C++.NET using namespace mVizNET;

       // Plot the histogram values in a 512 x 128 frame

       Histo->Plot(0, 0, 512, 128, false, 0, 0, (IntPtr)0, 0);

C# using mVizNET;

       // Plot the histogram values in a 512 x 128 frame

       Histo.Plot(0, 0, 512, 128, false, 0, 0, (IntPtr)0, 0);

Visual Basic

       ' Plot the histogram values in a 512 x 128 frame

       Histo.Plot(0, 0, 512, 128, False, 0, 0, 0, 0)

Reference:

Histogram::Set, Histogram::Bin, Histogram::Window, Histogram::Append, Histogram::Plot, Graph::DrawTo.


Computing an image histogram

Pixel grayscale value frequency counts in an image are determined by the method Compute.

Example:

C++ Native

       // Compute the histogram of Src

       Histo.Compute(Src);

C++.NET using namespace mVizNET;

       // Compute the histogram of Src

       Histo->Compute(Src, true);

C# using mVizNET;

       // Compute the histogram of Src

       Histo.Compute(Src, true);

Visual Basic

       ' Compute the histogram of Src

       Histo.Compute(Src, True)


Computing a region histogram

In some cases you would like to evaluate pixels in an area of arbitrary shape, not just a rectangular window. This is possible by first creating a Region object of the desired shape and invoking the method Compute that takes a Mask argument.

Example:

C++ Native

       // Define the mask from an outline

       Mask.PathAppend(Outline);

       // Compute the histogram of Src inside the mask

       Histo.Compute(Src, Mask);

C++.NET using namespace mVizNET;

       // Define the mask from an outline

       Mask->PathAppend(Outline, 0);

       // Compute the histogram of Src inside the mask

       Histo->Compute(Src, Mask, true);

C# using mVizNET;

       // Define the mask from an outline

       Mask.PathAppend(Outline, 0);

       // Compute the histogram of Src inside the mask

       Histo.Compute(Src, Mask, true);

Visual Basic

       ' Define the mask from an outline

       Mask->PathAppend(Outline, 0);

       ' Compute the histogram of Src inside the mask

       Histo.Compute(Src, Mask, True)


Computing statistics from a histogram

Several statistical estimators can be computed from a histogram. After the image histogram has been computed, the range, the mean, the variance and other estimators can be obtained.

Central trend estimators:

  • Mean: arithmetic average of all pixel values.
  • Median: gray value separating the higher half from the lower half.
  • Mode: most frequent gray value.

Spreading estimators:

  • Range: smallest and largest value with a nonzero frequency.
  • Quantile: gray value that separates a fraction of the gray values distribution.
  • Variance: average of the squared deviation between pixel values and the mean. The biased estimator formula is used.
  • MedianAbsoluteDeviation (MAD): average absolute difference between the gray values and the median value.

Distribution shape estimators:

  • Skewness: measure of the asymmetry of the gray values distribution.
  • Kurtosis: measure of the "peakedness" of the gray values distribution.
  • Entropy: measure of the amount of information in the gray values distribution.

Example:

C++ Native

       // Compute the mean of the histogram of Src

       double Mean= Histo.Mean();

C++.NET using namespace mVizNET;

       // Compute the mean of the histogram of Src

       double Mean= Histo->Mean();

C# using mVizNET;

       // Compute the mean of the histogram of Src

       double Mean = Histo.Mean();

Visual Basic

       ' Compute the mean of the histogram of Src

       Dim Mean As Double = Histo.Mean()

Note that the same estimators can be obtained directly, without first computing the image histogram. This is handy when only one estimator needs to be computed. Otherwise, first compute the image histogram and get all estimators from the histogram.

Example:

C++ Native

       // Compute the mean of Src

       Mean= Histogram::Mean(Src);

C++.NET using namespace mVizNET;

       // Compute the mean of Src

       Mean= Histogram::Mean(Src);

C# using mVizNET;

       // Compute the mean of Src

       Mean = Histogram.Mean(Src);

Visual Basic

       ' Compute the mean of Src

       Mean = mVizNET.Histogram.Mean(Src)

Reference:

Histogram::Compute, Histogram::Mean, Histogram::Median, Histogram::Mode, Histogram::Range, Histogram::Quantile, Histogram::Variance, Histogram::MedianAbsoluteDeviation, Histogram::Skewness, Histogram::Kurtosis, Histogram::Entropy .


Histogram Formulas

In the next formulas, let Hi be the count in the ith bin, i.e the frequencies, let H be the sum of all Hi s, i.e. the pixel count.


Mean

The average index value weighted by the frequencies


Median

med = the largest m that accumulates half of the frequencies


Quantile

The largest m that cumulates a given fraction of the frequencies


Median Absolute Deviation

The average of the absolute difference to the median


Mode

The index with the largest frequency


Range

The smallest and largest indices i such that


Variance

The average squared deviation to the mean


Skewness

The ratio of the centered third and second order moments


Kurtosis

The ratio of the centered fourth and second order moments


Entropy

The average number of bits required to express all frequencies


Equalizing an image histogram

Usually, the graph of an image histogram is not flat, it has one or more peaks corresponding to the dominant shades of gray. A classical method known as histogram equalization can flatten the histogram by defining a nonlinear transform of the grayscale. Such a transformation maximizes the usage of the dynamic range and often reveals invisible features in the dark areas. The visual appearance of the image is improved.

Example (caution, this is a member of the Operator class):

C++ Native

       // Equalize the source image

       Operator::Equalize(Src, Dst);

C++.NET using namespace mVizNET;

       // Equalize the source image

       Operator::Equalize(Src, Dst);

C# using mVizNET;

       // Equalize the source image

       Operator.Equalize(Src, Dst);

Visual Basic

       ' Equalize the source image

       mVizNET.Operator.Equalize(Src, Dst)


Cumulating a histogram

The cumulative histogram of an image gives the count of pixels with a value less than a given threshold, for all possible values of the threshold. It is obtained by adding together all bin values up to the threshold. This is repeated for all threshold values.

Example:

C++ Native

       // Compute the cumulated histogram

       Histogram Cumulated;

       Cumulated.Cumulate(Histo);

C++.NET using namespace mVizNET;

       // Compute the cumulated histogram

       Histogram^ Cumulated= gcnew Histogram;

       Cumulated->Cumulate(Histo);

C# using mVizNET;

       // Compute the cumulated histogram

       Histogram Cumulated = new Histogram();

       Cumulated.Cumulate(Histo);

Visual Basic

       ' Compute the cumulated histogram

       Dim Cumulated As mVizNET.Histogram = New mVizNET.Histogram

       Cumulated.Cumulate(Histo)

Reference:

Operator::Equalize, Histogram::Cumulate.


Blob Analysis

Blob analysis is a general-purpose technique to locate and characterize objects in an image. The blob analysis tool is implemented by the class Blobs.

It starts by segmenting the image, i.e. assigning a class number to all of the pixels according to a suitable criterion. For a simple example, pixels can be marked as background or foreground, depending on their gray-level values (assuming that background pixels are darker than foreground pixels).

 à

Background/foreground classification

When the pixels have each been assigned a class, blobs are formed by grouping the pixels of the same class that are in contact with each other.

 à

Blobs connection

A pixel can touch another along a common edge or on a common corner. If only edge contact is considered, we speak of 4-connectivity; when both edge and corner contacts are considered, we speak of 8-connectivity.

4-connected vs. 8-connected pixels

Blob segmentation can be achieved by the Segment method which uses simple thresholding for pixel classification. The connectivity rule is governed by the argument Connexity8. Blobs smaller than the prescribed MinimumArea are not taken into account.

Processing can also be restricted to a region of arbitrary shape, by passing an extra Mask argument, a Region object.

Example:

C++ Native

       // Create a Blobs object

       Blobs Pads;

       // Segment the source image, using automatic thresholding and discarding isolated pixels

       Pads.Segment(Src, true, true, 1);

C++.NET using namespace mVizNET;

       // Create a Blobs object

       Blobs^ Pads= gcnew Blobs;

       // Segment the source image, using automatic thresholding and discarding isolated pixels

       Pads->Segment(Src, true, true, 1);

C# using mVizNET;

       // Create a Blobs object

       Blobs Pads = new Blobs();

       // Segment the source image, using automatic thresholding and discarding isolated pixels

       Pads.Segment(Src, true, true, 1);

Visual Basic

       ' Create a Blobs object

       Dim Pads As mVizNET.Blobs = New mVizNET.Blobs()

       ' Segment the source image, using automatic thresholding and discarding isolated pixels

       Pads.Segment(Src, True, True, 1)

After the blobs have been formed, different feature values can be computed to characterize the position, the extent or the shape of the blobs. Among these, the axis parallel bounding box, the tightest bounding box, also known as the Feret box, the ellipse of inertia, the convex hull… The individual blobs are referred to by an index value that runs from 0 to NumBlobs-1.

Many of these features are described by a small number of numerical parameters, which can be integer (area) of floating-point (average gray-level). Some others are more general and described by other mViz objects (histogram of the pixels, outline path…).

Feret rectangle, ellipse of inertia, convex hull

Corresponding methods are Area, ConvexArea, Box , Center, Ellipse, FeretBox, Average, Deviation, Minimum, Maximum, Centroid, Ellipsoid, PixelHistogram, Outlineand ConvexHull. The method Border allows to check if the given blob touches an image border, meaning that it could be incomplete.

Example:

C++ Native

       // Loop on the blobs to compute the total area

       Area= 0;

       for (int Index= 0; Index < Pads.NumBlobs; Index++)

       {

              // Accumulate

              Area+= Pads.Area(Index);

       }

C++.NET using namespace mVizNET;

       // Loop on the blobs to compute the total area

       Area= 0;

       for (int Index= 0; Index < Pads->NumBlobs; Index++)

       {

              // Accumulate

              Area+= Pads->Area(Index);

       }

C# using mVizNET;

       // Loop on the blobs to compute the total area

       Area = 0;

       for (int Index = 0; Index < Pads.NumBlobs; Index++)

       {

           // Accumulate

           Area += Pads.Area(Index);

       }

Visual Basic

       ' Loop on the blobs to compute the total area

       Area = 0

       For Index As Integer = 0 To Pads.NumBlobs - 1

       ' Accumulate

       Area += Pads.Area(Index)

       Next Index

Reference:

Blobs::Segment , Blobs::NumBlobs , Blobs::Area , Blobs::Box , Blobs::Border , Blobs::Center , Blobs::Ellipse , Blobs::FeretBox , Blobs::Average, Blobs::Deviation, Blobs::Minimum, Blobs::Maximum , Blobs::Centroid , Blobs::Ellipsoid , Blobs::Outline , Blobs::ConvexHull , Blobs::PixelHistogram.


Individual Blobs Processing

When working with blob analysis, the geometric features are used to characterize parts or defects on parts in one way or another. For instance, they can be used to check the correct position or correct size of assembly elements, or detect the presence of unwanted stains on a surface.

In many cases, the first step of segmentation detects extra blobs that are of no interest for the problem at hand. Different criteria can be used to get rid of unwanted blobs and focus on the right ones. The blob selection process is often organized as a cascade of acceptance tests.

In the example below, we will first discard the incomplete blobs, those that touch the image borders or a region border, and then ignore those below a certain area threshold. The remaining blobs are used for a mere counting.

Blobs of interest

Example:

C++ Native

       // Process all blobs

       int PadCount= 0;

       for (Index= 0; Index < Pads.NumBlobs; Index++)

       {

              // Keep the complete ones

              if (!Pads.Border(Index, Src))

              {

                     // Keep the large ones

                     if (Pads.Area(Index) > 400)

                     {

                           // Increase the counter

                           PadCount++;

                     }

              }

       }

C++.NET using namespace mVizNET;

       // Process all blobs

       int PadCount= 0;

       for (int Index= 0; Index < Pads->NumBlobs; Index++)

       {

              // Keep the complete ones

              if (!Pads->Border(Index, Src))

              {

                     // Keep the large ones

                     if (Pads->Area(Index) > 400)

                     {

                           // Increase the counter

                           PadCount++;

                     }

              }

       }

C# using mVizNET;

       // Process all blobs

       int PadCount = 0;

       for (int Index = 0; Index < Pads.NumBlobs; Index++)

       {

           // Keep the complete ones

           if (!Pads.Border(Index, Src))

           {

              // Keep the large ones

              if (Pads.Area(Index) > 400)

              {

              // Increase the counter

              PadCount++;

              }

           }

       }

Visual Basic

       ' Process all blobs

       Dim PadCount As Integer = 0

       For Index As Integer = 0 To Pads.NumBlobs - 1

       ' Keep the complete ones

       If Not Pads.Border(Index, Src) Then

           ' Keep the large ones

           If Pads.Area(Index) > 400 Then

              ' Increase the counter

              PadCount += 1

           End If

       End If

       Next Index

Reference:

Blobs::Segment , Blobs::NumBlobs , Blobs::Area , Blobs::Box , Blobs::Border , Blobs::Center , Blobs::Ellipse , Blobs::FeretBox , Blobs::Average, Blobs::Deviation, Blobs::Minimum, Blobs::Maximum , Blobs::Centroid , Blobs::Ellipsoid , Blobs::ConvexHull , Blobs::PixelHistogram.


Collective Blobs Processing

Instead of handling the blobs one by one, you can process them collectively by means of selection and sorting functions. After segmenting the image, the ByFeatureSelect method allows you to keep only the blobs that fulfill certain criteria, by specifying an allowed or disallowed range of value for any feature.

Selection based on the blob area

Then the IntFeature and FloatFeature let you query the feature values of the remaining blobs, together with the number of available blobs, NumSelectedBlobs.

Selections can be cascaded. Blobs along the image edges or touching a region outline can also be discarded by means of the methods BorderSelect.

Border blobs

Blobs interfering with an arbitrary rectangle or region can be selected by the method BlobInWindowSelect.

Window blobs

Similarly, blobs interfering with an arbitrary region can be selected by the method BlobInRegionSelect.

Complex selections can be obtained by choosing between different selection modes:

  • Add: check all unselected blobs; if their feature value falls into the range, select them; keep unchanged the blobs that were already selected.
  • Remove: check all selected blobs; if their feature value falls into the range, unselect them; keep unchanged the blobs that were not selected.
  • Select: check all blobs and select all those with a feature value in the range.
  • Deselect: check all blobs and select all those with a feature value outside the range.

After selection, the blobs can be ordered by increasing or decreasing feature value by means of the ByFeatureSort method.

Example:

C++ Native

       // Discard the small (< 10 pixels) and large (>500 pixels) blobs

       Pads.ByFeatureSelect(BlobArea, Src, 10, 500, Remove);

       // Discard the flat (< 20 pixels high) blobs

       Pads.ByFeatureSelect(BlobBoxHeight, Src, 20, MaxInt, Remove);

       // Sort by increasing abscissa

       Pads.ByFeatureSort(BlobBoxX, Src);

C++.NET using namespace mVizNET;

       // Discard the small (< 10 pixels) and large (>500 pixels) blobs

       Pads->ByFeatureSelect(Features::BlobArea, Src, 10, 500, SelectionMode::Remove, RangeMode::Outside);

       // Discard the flat (< 20 pixels high) blobs

       Pads->ByFeatureSelect(Features::BlobBoxHeight, Src, 20, Int32::MaxValue, SelectionMode::Remove, RangeMode::Outside);

       // Sort by increasing abscissa

       Pads->ByFeatureSort(Features::BlobBoxX, Src, true);

C# using mVizNET;

       // Discard the small (< 10 pixels) and large (>500 pixels) blobs

       Pads.ByFeatureSelect(Features.BlobArea, Src, 10, 500, SelectionMode.Remove, RangeMode.Outside);

       // Discard the flat (< 20 pixels high) blobs

       Pads.ByFeatureSelect(Features.BlobBoxHeight, Src, 20, Int32.MaxValue, SelectionMode.Remove, RangeMode.Outside);

       // Sort by increasing abscissa

       Pads.ByFeatureSort(Features.BlobBoxX, Src, true);

Visual Basic

       ' Discard the small (< 10 pixels) and large (>500 pixels) blobs

       Pads.ByFeatureSelect(mVizNET.Features.BlobArea, Src, 10, 500, mVizNET.SelectionMode.Remove, mVizNET.RangeMode.Outside)

       ' Discard the flat (< 20 pixels high) blobs

       Pads.ByFeatureSelect(mVizNET.Features.BlobBoxHeight, Src, 20, Int32.MaxValue, mVizNET.SelectionMode.Remove, mVizNET.RangeMode.Outside)

       ' Sort by increasing abscissa

       Pads.ByFeatureSort(mVizNET.Features.BlobBoxX, Src, True)

When the Select or Sort methods are used, there is no need to explicitly compute the corresponding feature. If anyway you want to do so, you can use the Evaluate method.

Example:

C++ Native

       // Compute the centroids

       Pads.Evaluate(BlobCentroid, Src);

       // Process all computed blobs

       for (Index= 0; Index < Pads.NumSelectedBlobs; Index++)

       {

              // Get the centroid coordinates

              double X= Pads.FloatFeature(Index, BlobCentroidX);

              double Y= Pads.FloatFeature(Index, BlobCentroidY);

       }

C++.NET using namespace mVizNET;

       // Compute the centroids

       Pads->Evaluate(Features::BlobCentroid, Src, BlobSelection::AllSelected);

       // Process all computed blobs

       for (int Index= 0; Index < Pads->NumSelectedBlobs; Index++)

       {

              // Get the centroid coordinates

              double X= Pads->FloatFeature(Index, Features::BlobCentroidX);

              double Y= Pads->FloatFeature(Index, Features::BlobCentroidY);

       }

C# using mVizNET;

       // Compute the centroids

       Pads.Evaluate(Features.BlobCentroid, Src, BlobSelection.AllSelected);

       // Process all computed blobs

       for (int Index = 0; Index < Pads.NumSelectedBlobs; Index++)

       {

           // Get the centroid coordinates

           double x = Pads.FloatFeature(Index, Features.BlobCentroidX);

           double y = Pads.FloatFeature(Index, Features.BlobCentroidY);

       }

Visual Basic

       ' Compute the centroids

       Pads.Evaluate(mVizNET.Features.BlobCentroid, Src, mVizNET.BlobSelection.AllSelected)

       ' Process all computed blobs

       For Index As Integer = 0 To Pads.NumSelectedBlobs - 1

       ' Get the centroid coordinates

       Dim Xc As Double = Pads.FloatFeature(Index, mVizNET.Features.BlobCentroidX)

       Dim Yc As Double = Pads.FloatFeature(Index, mVizNET.Features.BlobCentroidY)

       Next Index

Important: when a collective blob selection/sorting operation is applied, the order of the blobs gets scrambled. This means that the blob indexes are volatile and should not be used as reference to specific blobs.

Reference:

Blobs::ByFeatureSelect, Blobs::BlobInWindowSelect, BlobInRegionSelect, Blobs::BorderSelect, Blobs::NumSelectedBlobs, Blobs::IntFeature, Blobs::FloatFeature, Blobs::ByFeatureSort.


Blob Formulas

This section explains how the available features are computed from the blob pixel coordinates and values.

Notice that when coordinates are involved, they are counted from the origin of the image (top-left pixel) rather than from the origin of the current Window, if any. This impacts features such as Center, Centroid, Box or ConvexHull.


Convex Area

The convex area is the area inside the tightest convex polygon that contains the pixel centers.

Tightest convex polygon

Perimeter

Number of pixels on the outline.

Perimeter

Full Perimeter

Number of pixels on the outer and inner outlines.

Full Perimeter


Center

The gravity center is the arithmetic average of the coordinates.

Average abscissa

Average ordinate


Ellipse of inertia

The ellipse of inertia is centered on the gravity center. The Width and Height are the major and minor axis of the ellipse of inertia, computed from the first and second order moments of the coordinates, assuming uniform distribution of the mass over the pixels. The angle is the direction of the major axis.

Equivalent ellipse


Feret rectangle

The Feret rectangle is the tight rectangular bounding box that has the minimum width. It is constructed from geometric considerations. It passes through the pixel centers, not the pixel outlines.

Tightest bounding rectangle


Mass and Average

The mass is the sum of the pixel values.

The average is the arithmetic mean of the pixel values.

Average of the pixel values


Deviation

The deviation is the square root of the average deviation to the mean of the pixel values.

Deviation of the pixel values


Minimum, Median and Maximum

The minimum (maximum) is the lowest (highest) of the pixel values. The median is the pixel value such that half of the histogram has a lower value.

Lowest (hightest) pixel value


Ellipsoid of inertia

We call the ellipsoid of inertia the equivalent of the ellipse of inertia where the gray values of the pixels are used for weighting. The center of the ellipsoid is the centroid.

Equivalent weighted ellipse


Outline

The pixels that are on the border of the blob, forming a closed path.

8-connected outline


Calibrated blob features

When simple calibration has been activated, the returned measurements are implicitly converted to the desired measurement units.

For some features, explicit calibration with a Geometry object is supported (see the section on advanced calibration). You can pass it to the Evaluate method of a blob detector (collective processing), or to the respective evaluation function (individual processing). You will get calibrated measurements, using the calibration model in use.

The supported features are currently: Box, Worldarea, Center, Centroid, Ellipse, Ellipsoid (note that the WorldArea is the calibrated area, i.e. expressed in squared units instead of pixels), and for the advanced RegistrationModels (perspective, quadratic and general), the values are approximate.


Blob Feature Distribution

When looked at collectively, the blob features form a statistical distribution. You can get the following estimators from such distribution, for any feature:

· Average: FeatureAverage

· Standard Deviation: FeatureDeviation

· Minimum/Maximum: FeatureMinimum, FeatureMaximum

· Quantile: FeatureQuantile

· Covariance (between two features): FeatureCovariance

For the Minimum and Maximum feature, you can also know the index of a blob that achieves them. FeatureMinimumIndex, FeatureMaximumIndex.

The selection mode applies.

Reference:

Blobs::FeatureAverage, Blobs::FeatusreDeviation, Blobs::FeatureMinimum, Blobs::FeatureMaximum, Blobs::FeatureQuantile, Blobs::FeatureCovariance, Blobs::FeatureMinimumIndex and Blobs::FeatureMaximumIndex.


Advanced: Blobs Edition

You can access the individual runs that make up a blob, by means of the accessors NumBlobRuns and BlobRun, for instance to implement your own features. [You can even modify the coordinates in these runs, but you cannot change their number.]

You can also add new blobs defined by regions, so that these blobs can enter the blobs processing pipeline (for features computation, selection, sorting…). See AppendBlob.

Reference:

Blobs::NumBlobRuns, BlobRun and Blobs::AppendBlob.


Edge Maps and Vectorization

Edge detection is an important task in image processing and understanding as it extracts shape information from the outline and inner contours of the objects. It performs information reduction from pixels “in bulk” to a compact representation by elementary geometric primitives.

In its simplest form, edge detection is the process of finding the pixels that belong to an edge, i.e the border line between two regions of different color or shade of gray. This is usually done by using a derivative filter that finds high gradient areas, followed by a thinning process known as non-maxima suppression.

As this process only provides a raw, unstructured set of pixels, stored as an image, the next step is edge linking, by which chains of connected pixels are built. These chains can be exploited as such but are still at a low level of image description.

The next stage is vectorization, a procedure which transforms the pixel chains in more significant geometric primitives. mViz currently supports two of them: line segments (straight edges without curvature) and circular arcs (curved edges with a constant curvature). The vectorization process turns the pixel chains into sequences of lines and/or arcs.


Edge detection as a raster map

The method GradientVector computes the gradient on every pixel of the image. This is a preliminary step in edge detection. Variants of the gradient operator are available: Standard, Prewitt and Sobel, as already described in the chapter on convolution. Note anyway that this method keeps the X and Y components separate, i.e. computes the gradient vector instead of the gradient module.

The method GradientMaxima uses the gradient vector map to estimate one-pixel-thin edges by non-maxima suppression. (Actually, it uses the edge pixel where the gradient has the maximum intensity among neighbors).

Gradient pixels, raw and thinned

The parameter Noise allows getting rid of irrelevant gradient responses corresponding to noise. Only strong gradients are considered.

Upon return of the function, an edge image is provided, where pixels are either 0 for non-edge pixels or nonzero for edge pixels; the nonzero value represents the gradient intensity. If the Binarize flag is activated, all nonzero values are set to 255 (white) instead.

The method StrongEdges adds a level of false edge rejection by using the hysteresis thresholding process: in addition to the Noise level, which applies to individual pixels, the EdgeStrength level rejects whole edge fragments if none of their pixels reaches it.

Example:

C++ Native

       // Gradient Vector (Prewitt)

       EdgeMap::GradientVector(Src, Vec, PrewittGradient);

       // Gradient Maxima (Noise=10, not binarized, Prewitt)

       EdgeMap::GradientMaxima(10, Src, Grd, false, PrewittGradient);

       // Strong Edges (Noise=10, Strength=50, Prewitt)

       EdgeMap::StrongEdges(10, 50, Src, Grd, PrewittGradient);

C++.NET using namespace mVizNET;

       // Gradient Vector (Prewitt)

       mVizNET::EdgeMap::GradientVector(Src, Vec, mVizNET::GradientTypes::PrewittGradient);

       // Gradient Maxima (Noise=10, not binarized, Prewitt)

       mVizNET::EdgeMap::GradientMaxima(10, Src, Grd, false, mVizNET::GradientTypes::PrewittGradient);

       // Strong Edges (Noise=10, Strength=50, Prewitt)

       mVizNET::EdgeMap::StrongEdges(10, 50, Src, Grd, mVizNET::GradientTypes::PrewittGradient);

C# using mVizNET;

       // Gradient Vector (EdgeMap)

       mVizNET.EdgeMap.GradientVector(Src, Vec, mVizNET.GradientTypes.PrewittGradient);

       // Gradient Maxima (EdgeMap)

       mVizNET.EdgeMap.GradientMaxima(10, Src, Grd, false, mVizNET.GradientTypes.PrewittGradient);

       // Strong Edges (EdgeMap)

       mVizNET.EdgeMap.StrongEdges(10, 50, Src, Grd, mVizNET.GradientTypes.PrewittGradient);

Visual Basic

        ' Gradient Vector (EdgeMap)

        mVizNET.EdgeMap.GradientVector(Src, Vec, mVizNET.GradientTypes.PrewittGradient)

        ' Gradient Maxima (EdgeMap)

        mVizNET.EdgeMap.GradientMaxima(10, Src, Grd, False, mVizNET.GradientTypes.PrewittGradient)

        ' Strong Edges (EdgeMap)

        mVizNET.EdgeMap.StrongEdges(10, 50, Src, Grd, mVizNET.GradientTypes.PrewittGradient)


Edge detection as a path map

Contrary to the above methods, the method Follow generates a structured representation of the edges, i.e. as a list of edge fragments. Every fragment is a list of pixel coordinates. By traversing the list of fragments and the pixels of all fragments, one sees all edge pixels.

Edges pixels as continuous paths

The parameter Noise allows getting rid of irrelevant gradient responses corresponding to noise. Only strong gradients are considered.

The parameters MinAverageGray and MinLength are meant to discard false edges; they work differently from the parameter EdgeStrength in the method StrongEdges: for an edge fragment to be considered valid, it must be at least long by MinLength pixels, and the mean edge intensity value must reach at least MinAverageGray.

To retrieve the path data, vertex by vertex, you query the edge map with the method Vertex , passing the index of the path, in range [0.. NumPaths -1] and the index of the vertex in the given path, in range [0.. NumVertexes (PathIndex)-1].

Example:

C++ Native

       // Follow (Noise=10, MinAverageGray=10, MinLength=10)

       Edges.Follow(10, 10, 5, Src);

       // Look at all vertexes

       for (int i= 0; i < Edges.NumPaths; i++)

       {

              for (int j= 0; j < Edges.NumVertexes(i); j++)

              {

                     Site V= Edges.Vertex(i, j);

              }

       }

C++.NET using namespace mVizNET;

       // Follow (Noise=10, MinAverageGray=10, MinLength=10)

       Edges->Follow(10, 10, 5, Src);

       // Look at all vertexes

       for (int i= 0; i < Edges->NumPaths; i++)

       {

              for (int j= 0; j < Edges->NumVertexes(i); j++)

              {

                     Site V= Edges->Vertex(i, j);

              }

       }

C# using mVizNET;

// Follow (Noise=10, MinAverageGray=10, MinLength=10)

       Edges.Follow(10, 10, 5, Src);

       // Look at all vertexes

       for (int i = 0; i < Edges.NumPaths; i++)

       {

           for (int j = 0; j < Edges.NumVertexes(i); j++)

           {

               Site V = Edges.Vertex(i, j);

           }

       }

Visual Basic

        ' Follow (EdgeMap)

        Edges.Follow(10, 10, 5, Src)

        ' Look at all vertexes

        For i As Integer = 0 To Edges.NumPaths

            For j As Integer = 0 To Edges.NumVertexes(i)

                Dim V As mVizNET.Site = Edges.Vertex(i, j)

            Next j

        Next i


Edge detection as a geometric map

Last but not least, the method Vectorize turns the edge fragments into sequences of line segment/circular arcs. This is made in such a way that the distance between the segments approximating the edge fragment and the edge fragment itself does not exceed a given threshold. Tuning this value allows adjusting the accuracy, at the expense of the number of geometric primitives required.

Edges pixels as segments or segments+arcs

The parameters Noise, MinAverageGray and MinLength are as described with method Follow.

The parameter Curved enables the use of the circular arcs. Otherwise, only line segments are generated. The parameter Deviation indicates the allowed discrepancy, in pixels, between the fitted primitives and the digital curves.

To retrieve the path data, segment by segment, you query the edge map with the method Arc , passing the index of the path, in range [0.. NumPaths -1] and the index of the vertex in the given path, in range [0.. NumArcs (PathIndex)-1].

The method Arc returns an ArcNode structure which gives

- the starting point of the segment or arc (the ending point is common with the next segment/arc);

- the aperture angle, in radians. When 0, we have a line segment. When nonzero, the aperture indicates the amplitude of the circular arc from the starting point to the ending point, around the arc center. It runs in range ]0..2p[ for clockwise arcs and ]-2p..0[ counterclockwise.

Segment/arc geometry

Example:

C++ Native

       // Vectorize (Noise=10, MinAverageGray=10, MinLength=10, not arcs, default deviation)

       Edges.Vectorize(10, 10, 5, Src, false, 1);

       // Look at all line segments

       for (int i= 0; i < Edges.NumPaths; i++)

       {

              for (int j= 0; j < Edges.NumArcs(i); j++)

              {

                     ArcNode A= Edges.Arc(i, j);

              }

       }

C++.NET using namespace mVizNET;

       // Vectorize (Noise=10, MinAverageGray=10, MinLength=10, not arcs, default deviation)

       Edges->Vectorize(10, 10, 5, Src, false, 1);

       // Look at all line segments

       for (int i= 0; i < Edges->NumPaths; i++)

       {

              for (int j= 0; j < Edges->NumArcs(i); j++)

              {

                     ArcNode A= Edges->Arc(i, j);

              }

       }

C# using mVizNET;

       // Vectorize (Noise=10, MinAverageGray=10, MinLength=10, not arcs, default deviation)

       Edges.Vectorize(10, 10, 5, Src, false, 1);

       // Look at all line segments

       for (int i = 0; i < Edges.NumPaths; i++)

       {

           for (int j = 0; j < Edges.NumArcs(i); j++)

           {

               ArcNode A = Edges.Arc(i, j);

           }

       }

Visual Basic

        ' Vectorize (EdgeMap)

        Edges.Vectorize(10, 10, 5, Src, False, 1)

        ' Look at all line segments

        For i As Integer = 0 To Edges.NumPaths

            For j As Integer = 0 To Edges.NumArcs(i)

                Dim A As mVizNET.ArcNode = Edges.Arc(i, j)

            Next j

        Next i

Reference:

Raster map

EdgeMap::GradientVector , EdgeMap::GradientMaxima , EdgeMap::StrongEdges .

Path map

EdgeMap::Follow , EdgeMap::Vertex , EdgeMap::NumPaths , EdgeMap::NumVertexes .

Geometric map

EdgeMap::Vectorize, EdgeMap::Arc , EdgeMap::NumPaths , EdgeMap::NumArcs .


Edge Gauging

Very accurate geometric measurements of objects are possible when they have well defined edges (outlines or internal edges). The principle of the measurements is to detect edge points, i.e. pixels with a steep gray-level variation, and to fit a simple geometric model to them. The model can be a straight line, a rectangle or a circular or elliptic arc.

The EdgeLine, EdgeArc, EdgeEllipse and EdgeRectangle tools are available for this purpose. When edges are located, measurements such as distances, orientations or thicknesses can be derived from their position.

The EdgePoint tool finds points along a profile that crosses an edge. The purpose is to locate objects with sub-pixel accuracy. For instance, location of a contrasted square can be achieved by means of two edge tools, one in the vertical direction across the top edge, and one in the horizontal direction across the left edge.

Edge point tools can also be used for thickness and distance measurements. Here, a single edge point tool is able to detect two edges along the same profile, and compute their spacing.

To use the tool, move the profile across the edge to be located, perpendicular to it. The profile plot which is displayed at the top shows the gray-level values along the profile. Edges appear as more or less sharp s-curves that follow a transition from dark to light (raising edge) or light to dark (falling edge).

Raising vs. Falling edges

The plot at the bottom shows the slope of the profile curve, and edges appear as more or less elevated peaks with positive or negative amplitude (raising or falling edges respectively).

Edge Profile and Derivative

Due to image noise, nearby edges of the object, shadows or reflections, spurious edges can be detected. The edge point tool provides means to get rid of these and avoid false measurements. Tuning the edge selection parameters is an important step that shouldn't be underestimated.

Edge strength is characterized by three parameters:

  • The Step is the total gray-level variation along the edge.
  • The Slope is the maximum value of the derivative.
  • The Span is the number of pixels covered by the edge.
  • The Noise is the amplitude of the derivative considered insignificant.

Edge Strength Parameters


Setting up the EdgePoint

Successful measurement depends on appropriate parameter settings. Before starting, it is advised to inquire about the possible variations in the process, including object movement, contrast and sharpness conditions. Images representative of the extreme cases should be available.

Place the gauge

Drag the edge point tool to the vicinity of the desired edge and perpendicular to it. The length of the tool should be such that it always hits the edge even when the object shifts[1].

Ensure that the sampling direction is perpendicular to the edge.

Note that the gauge coordinates are always given with respect to the whole image, even if a Window is active.

Choose the polarity, the breadth and the smoothing

Specify the desired edge polarity: raising, falling or both.

If the edge is straight, it is advisable to increase the edge breadth, to reduce the effect of noise and improve accuracy.

Another way to reduce noise is to use smoothing. Note anyway that smoothing will diminish the edge strength.

Assess the edge strength

Compare the values of the edge strength parameters (Step, Slope, Span and Noise) on the desired edge and on unwanted ones. If possible, repeat this with other sample images, until you get a good understanding of the typical values.

The most important parameter is the Step, which corresponds to the global edge contrast (difference of gray levels on either sides). You can set a minimum Slope or Span to accept sharp edges only. Noise is normally set to some multiple of the true noise amplitude, which corresponds to false edges.

Define the selection rule

The easiest way to select the right edge among several detected ones is to consider the sharper one (BestSlope), the most contrasted one (BestStep) or the thicker one (BestSpan)

Another way is to define a rule to discriminate between desired and unwanted edges based on one or more edge parameter. Well contrasted edges are selected with formula |Step|³ MinimumStep; sharp edges are such that |Slope|³ MinimumSlope, and thick edges are such that Span³ MinimumSpan. You will need to adjust the minimum thresholds.

Hints

1. The minimum step is usually the best selection rule.

2. Setting a threshold to zero just disables the corresponding selection rule.

Example:

C++ Native

       // Use a thick probe (9 pixels wide)

       EdgePoint Gauge;

       Gauge.Breadth= 9;

       // Filter on the edge edge step alone (contrast 50)

       Gauge.MinimumStep= 50;

       Gauge.MinimumSlope= 0;

       Gauge.MinimumSpan= 0;

       Gauge.Detect(Src);

C++.NET using namespace mVizNET;

       // Use a thick probe (9 pixels wide)

       EdgePoint^ Gauge= gcnew EdgePoint;

       Gauge->Breadth= 9;

       // Filter on the edge step alone (contrast 50)

       Gauge->MinimumStep= 50;

       Gauge->MinimumSlope= 0;

       Gauge->MinimumSpan= 0;

       Gauge->Detect(Src);

C# using mVizNET;

       // Use a thick probe (9 pixels wide)

       EdgePoint Gauge = new EdgePoint();

       Gauge.Breadth = 9;

       // Filter on the edge step alone (contrast 50)

       Gauge.MinimumStep = 50;

       Gauge.MinimumSlope = 0;

       Gauge.MinimumSpan = 0;

       Gauge.Detect(Src);

Visual Basic

       ' Use a thick probe (9 pixels wide)

       Dim Gauge As mVizNET.EdgePoint = New mVizNET.EdgePoint()

       Gauge.Breadth = 9

       ' Filter on the edge step alone (contrast 50)

       Gauge.MinimumStep = 50

       Gauge.MinimumSlope = 0

       Gauge.MinimumSpan = 0

       Gauge.Detect(Src)

Reference:

EdgePoint::BestSlope, EdgePoint::BestStep, EdgePoint::BestSpan, EdgePoint::MinimumStep, EdgePoint::MinimumSlope, EdgePoint::MinimumSpan.

[1] If the object can move a lot, it is advisable to grossly locate it first.


Getting the Detected Points

If you want to handle all the points that have been detected, you can get the number of points with the property NumPoints and retrieve them with method FittedPoint to which you pass an index. Alternatively, the point coordinates can be retrieved with method FittedPoint as an XY object.

When the index is in range [0..NumPoints-1], you get the Ith point from the beginning of the probe. When the index is in range [-1..-NumPoints], you get the Ith point from the end of the probe.

A second argument allows you to consider the rising or falling edges distinctly.

Example:

C++ Native

       // Process all edges

       for (int Index= 0; Index < Gauge.NumPoints(Raising); Index++)

       {

              // Get the edge step

              int Step= Gauge.FittedEdge(Index, Raising).Step;

       }

C++.NET using namespace mVizNET;

       // Process all edges

       for (int Index= 0; Index < Gauge->NumPoints(Polarities::Raising); Index++)

       {

              // Get the edge step

              int Step= Gauge-> FittedEdge(Index, Polarities::Raising).Step;

       }

C# using mVizNET;

       // Process all edges

       for (int Index = 0; Index < Gauge.NumPoints(Polarities.Raising); Index++)

       {

           // Get the edge step

           int Step = Gauge. FittedEdge(Index, Polarities.Raising).Step;

       }

Visual Basic

       ' Process all edges

       For Index As Integer = 0 To Gauge.NumPoints(mVizNET.Polarities.Raising) - 1

       ' Get the edge step

       Dim PointStep As Integer = Gauge. FittedEdge(Index, mVizNET.Polarities.Raising).Step

       Next Index

Reference:

EdgePoint::NumPoints, EdgePoint::FittedPoint.


Advanced: Peak Splitting

When to edge transitions are very close to each other, they can appear as merged. This occurs when the profile derivative does not decrease below the noise threshold between the two transitions.

To deal with this situation, the split peak mode is meant to separate neighboring peaks of the derivative where they meet each other. After the split, all strong edges are retained.

The splitting mode is activated by the property SplitPeaks.

Reference:

EdgePoint::SplitPeaks.


Fitting a Line Segment

In order to accurately measure a straight edge, you need to place an EdgeLine gauge in a close vicinity of this edge. This is done by providing the two endpoint coordinate pairs Beg and End or alternatively Center/Angle/Length information by means of the method Locate. (Note that the gauge coordinates are always given with respect to the whole image, even if a Window is active.)

The Detect method will fit the exact line segment onto the edge. The fitted coordinates are retrieved as properties FittedBeg and FittedEnd.

Endpoints (big black dots) and fitted line (yellow)

The gauge will work by finding a number of points along the given edge, using the mechanics of the EdgePoint. The spacing of the points is specified as the Density property (spacing between the sampling profiles). If needed, the area close to the gauge endpoints can be avoided by setting the Clearance property.

Sampling density (green crosses)

Goodness of the fit can be assessed by mean of the Deviation parameter. It indicates the average distance of the points to the fitted model. In case of a good fit, this parameter should be a fraction of a pixel.

Otherwise, this can be an indication that the linear model is not appropriate or that outlier points have been detected.

Non-linear edge, outlier points

Example:

C++ Native

       // Position the gauge by providing both endpoints

       LineGauge.Beg= XY( 50, 100);

       LineGauge.End= XY(250, 100);

       // Detect and fit a line, using the default BestStep rule

       LineGauge.Detect(Src);

       // Get the fitted line endpoints

       XY Beg= LineGauge.FittedBeg;

       XY End= LineGauge.FittedEnd;

C++.NET using namespace mVizNET;

       // Position the gauge by providing both endpoints

       LineGauge.Beg= XY( 50, 100);

       LineGauge.End= XY(250, 100);

       // Detect and fit a line, using the default BestStep rule

       LineGauge.Detect(Src, EdgeSelection::BestStep);

       // Get the fitted line endpoints

       XY Beg= LineGauge.FittedBeg;

       XY End= LineGauge.FittedEnd;

C# using mVizNET;

       // Position the gauge by providing both endpoints

       LineGauge.Beg= new XY( 50, 100);

       LineGauge.End= new XY(250, 100);

       // Detect and fit a line, using the default BestStep rule

       LineGauge.Detect(Src, EdgeSelection.BestStep);

       // Get the fitted line endpoints

       XY Beg= LineGauge.FittedBeg;

       XY End= LineGauge.FittedEnd;

Visual Basic

        ' Position the gauge by providing both endpoints

        LineGauge.Beg = New mVizNET.XY(50, 100)

        LineGauge.End = New mVizNET.XY(250, 100)

        ' Detect and fit a line, using the default BestStep rule

        LineGauge.Detect(Src, mVizNET.EdgeSelection.BestStep)

        ' Get the fitted line endpoints

        Dim Beg_ As mVizNET.XY = LineGauge.FittedBeg

        Dim End_ As mVizNET.XY = LineGauge.FittedEnd

Reference:

EdgeLine::Beg, EdgeLine::End, EdgeLine::Locate, EdgeLine::Detect, EdgeLine::FittedBeg, EdgeLine::FittedEnd, EdgeLine::Density, EdgeLine::Clearance, EdgeLine::Deviation.


Fitting a Circular Arc

Fitting a circular arc is very similar to fitting a straight edge. You need to place an EdgeArc gauge in a close vicinity of this edge. This is done by providing three endpoint coordinate pairs Beg, Mid, End, or alternatively Center/Radius/Angles information by means of the method Locate. The Closed property tells if a full circle or or a circular arc is considered. (Note that the gauge coordinates are always given with respect to the whole image, even if a Window is active.)

The Detect method will fit the exact circular arc onto the edge. The fitted coordinates of the center and the radius are retrieved as properties FittedCenter and FittedRadius .

Endpoints (big black dots) and fitted circle (yellow)

The gauge will work by finding a number of points along the given edge, using the mechanics of the EdgePoint. The spacing of the points is specified as the Density property (spacing between the sampling profiles). If needed, the area close to the gauge endpoints can be laid aside by setting the Clearance property.

Sampling density (green crosses)

Accuracy of the fit can be assessed by mean of the Deviation parameter. It indicates the average distance of the points to the fitted model. In case of a good fit, this parameter should be a fraction of a pixel.

Otherwise, this can be an indication that the circular model is not appropriate or that outlier points have been detected.

Non-circular edge, outlier points

Example:

C++ Native

       // Position the gauge at (250, 200), from 0 to 180 degrees

       ArcGauge.Locate(XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       ArcGauge.Detect(Src);

       // Get the fitted center and radius

       XY Center= ArcGauge.FittedCenter;

       double Radius= ArcGauge.FittedRadius;

C++.NET using namespace mVizNET;

       // Position the gauge at (250, 200), from 0 to 180 degrees

       ArcGauge.Locate(XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       ArcGauge.Detect(Src, EdgeSelection::BestStep);

       // Get the fitted center and radius

       XY Center= ArcGauge.FittedCenter;

       double Radius= ArcGauge.FittedRadius;

C# using mVizNET;

       // Position the gauge at (250, 200), from 0 to 180 degrees

       ArcGauge.Locate(new XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       ArcGauge.Detect(Src, EdgeSelection.BestStep);

       // Get the fitted center and radius

       XY Center= ArcGauge.FittedCenter;

       double Radius= ArcGauge.FittedRadius;

Visual Basic

       // Position the gauge at (250, 200), from 0 to 180 degrees

        ArcGauge.Locate(New mVizNET.XY(250, 200), 100, 0, 180, 20)

        ' Detect and fit an arc, using the default BestStep rule

        ArcGauge.Detect(Src, mVizNET.EdgeSelection.BestStep)

        ' Get the fitted center and radius

        Dim Center As mVizNET.XY = ArcGauge.FittedCenter

        Dim Radius As Double = ArcGauge.FittedRadius

Reference:

EdgeArc::Beg, EdgeArc::End, EdgeArc::Locate, EdgeArc::Detect, EdgeArc::Fitted Center, EdgeArc::FittedRadius, EdgeArc::Density, EdgeArc::Clearance, EdgeArc::Deviation.


Fitting an Ellipse

Fitting an ellipse or elliptic arc is very similar to fitting a circular edge. An ellipse has more flexibility (5 degrees of freedom) so is more difficult to control. You need to place an EdgeEllipse gauge in a close vicinity of this edge. This is done by providing five endpoint coordinate pairs Beg, Mid0, Mid1, Mid2, End, or alternatively Center/Axis/Angles information by means of one of the methods Locate. The Closed property tells if a full ellipse or or a circular ellipse is considered. (Note that the gauge coordinates are always given with respect to the whole image, even if a Window is active.)

CAUTION: if the ellipsity is weak (eccentricity near zero), the orientation cannot be determined accurately and the FittedAngle can be meaningless. Consider using and EdgeArc.

The Detect method will fit the exact elliptical arc onto the edge. The fitted coordinates of the center, the axis lengths and the orientation angle are retrieved as properties FittedCenter, FittedFirstAxis, FittedSecondAxis and FittedAngle.

Detected point (green crosses) and fitted circle (yellow)

The gauge will work by finding a number of points along the given edge, using the mechanics of the EdgePoint. The spacing of the points is specified as the Density property (spacing between the sampling profiles). If needed, the area close to the gauge endpoints can be laid aside by setting the Clearance property.

Accuracy of the fit can be assessed by mean of the Deviation parameter. It indicates the average distance of the points to the fitted model. In case of a good fit, this parameter should be a fraction of a pixel.

Otherwise, this can be an indication that the elliptical model is not appropriate or that outlier points have been detected.

Example:

C++ Native

       // Position the gauge at (250, 200), semi-axis 100 and 50, from 0 to 180 degrees

       EllipseGauge.Locate(XY(250, 200), 100, 50, 0, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       EllipseGauge.Detect(Src);

       // Get the fitted center and axis

       XY Center= EllipseGauge.FittedCenter;

       double A= EllipseGauge.FittedFirstAxis;

       double B= EllipseGauge.FittedSecondAxis;

       double Theta= EllipseGauge.FittedAngle;

C++.NET using namespace mVizNET;

       // Position the gauge at (250, 200), semi-axis 100 and 50, from 0 to 180 degrees

       EllipseGauge.Locate(XY(250, 200), 100, 50, 0, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       EllipseGauge.Detect(Src, EdgeSelection::BestStep);

       // Get the fitted center and axis

       XY Center= EllipseGauge.FittedCenter;

       double A= EllipseGauge.FittedFirstAxis;

       double B= EllipseGauge.FittedSecondAxis;

       double Theta= EllipseGauge.FittedAngle;

C# using mVizNET;

       // Position the gauge at (250, 200), semi-axis 100 and 50, from 0 to 180 degrees

       EllipseGauge.Locate(new XY(250, 200), 100, 50, 0, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       EllipseGauge.Detect(Src, EdgeSelection.BestStep);

       // Get the fitted center and axis

       XY Center= EllipseGauge.FittedCenter;

       double A= EllipseGauge.FittedFirstAxis;

       double B= EllipseGauge.FittedSecondAxis;

       double Theta= EllipseGauge.FittedAngle;

Visual Basic

       // Position the gauge at (250, 200), semi-axis 100 and 50, from 0 to 180 degrees

        EllipseGauge.Locate(New mVizNET.XY(250, 200), 100, 50, 0, 0, 180, 20)

        ' Detect and fit an arc, using the default BestStep rule

        EllipseGauge.Detect(Src, mVizNET.EdgeSelection.BestStep)

        ' Get the fitted center and axis

        Dim Center As mVizNET.XY = EllipseGauge.FittedCenter

        Dim A As Double = EllipseGauge.FittedFirstAxis

        Dim B As Double = EllipseGauge.FittedSecondAxis

        Dim Theta As Double = EllipseGauge.FittedAngle

Reference:

EdgeEllipse::Beg, EdgeEllipse::End, EdgeEllipse::Mid0, EdgeEllipse::Mid1, EdgeEllipse::Mid2, EdgeEllipse::Locate, EdgeEllipse::Detect, EdgeEllipse::Fitted Center, EdgeEllipse::FittedFirstAxis, EdgeEllipse::FittedSecondAxis, EdgeEllipse::FittedAngle, EdgeEllipse::Density, EdgeEllipse::Clearance, EdgeEllipse::Deviation.


Fitting a Rectangle

Fitting a rectangle is also very similar. You need to place an EdgeRectangle gauge in a close vicinity of this edge. This is done by providing Center/Size/Angles information by means of the method Locate. (Note that the gauge coordinates are always given with respect to the whole image, even if a Window is active.)

The Detect method will fit the exact rectangle onto the edge. The fitted coordinates of the center and the radius are retrieved as properties FittedPoint, FittedSize and FittedAngle.

Handles (white dots) and fitted rectangle (yellow)

The gauge will work by finding a number of points along the given edge, using the mechanics of the EdgePoint. The spacing of the points is specified as the Density property (spacing between the sampling profiles). If needed, the area close to the gauge endpoints can be avoided by setting the Clearance property.

Sampling density (green crosses)

Accuracy of the fit can be assessed by mean of the Deviation parameter. It indicates the average distance of the points to the fitted model. In case of a good fit, this parameter should be a fraction of a pixel.

Otherwise, this can be an indication that the rectangle model is not appropriate or that outlier points have been detected.

Example:

C++ Native

       // Position the gauge at (250, 200), size (100, 100), upright

       RectangleGauge.Locate(XY(250, 200), XY(100, 100), 0);

       // Detect and fit an arc, using the default BestStep rule

       RectangleGauge.Detect(Src);

       // Get the fitted center

       double CenterX= RectangleGauge.FittedCenterX;

       double CenterY= RectangleGauge.FittedCenterY;

C++.NET using namespace mVizNET;

       // Position the gauge at (250, 200), size (100, 100), upright

       RectangleGauge.Locate(XY(250, 200), XY(100, 100), 0);

       // Detect and fit a rectangle, using the default BestStep rule

       RectangleGauge.Detect(Src, EdgeSelection::BestStep);

       // Get the fitted center

       double CenterX= RectangleGauge.FittedCenterX;

       double CenterY= RectangleGauge.FittedCenterY;

C# using mVizNET;

       // Position the gauge at (250, 200), size (100, 100), upright

       RectangleGauge.Locate(XY(250, 200), XY(100, 100), 0);

       // Detect and fit an arc, using the default BestStep rule

       RectangleGauge.Detect(Src, EdgeSelection.BestStep);

       // Get the fitted center

       double CenterX= RectangleGauge.FittedCenterX;

       double CenterY= RectangleGauge.FittedCenterY;

Visual Basic

        ' Position the gauge at (250, 200), size (100, 100), upright

       RectangleGauge.Locate(New mVizNET.XY(250, 200), New mVizNET.XY(100, 100), 0)

        ' Detect and fit a line, using the default BestStep rule

        RectangleGauge.Detect(Src, mVizNET.EdgeSelection.BestStep)

        ' Get the fitted line endpoints

        Dim CenterX As Double = RectangleGauge. FittedCenterX

        Dim CenterY As Double = RectangleGauge. FittedCenterT

Reference:

EdgeRectangle::Locate, EdgeRectangle::Detect,  EdgeRectangle::FittedPoint, EdgeRectangle::FittedSize, EdgeRectangle::FittedAngle, EdgeRectangle::Density, EdgeRectangle::Clearance, EdgeRectangle::Deviation.


Calibrated gauging

When simple calibration has been activated, the returned measurements are implicitly converted to the desired measurement units.

When a calibration transform has been defined using a Geometry object (see the section on advanced calibration), you can pass it to the Edgeline method of a gauge. You will get calibrated measurements, using the advanced calibration model in use.

When the model includes deformation modes, the deformation is automatically corrected. This ensures maximum accuracy of the measurements.

Important note: only the results are expressed in the calibrated coordinates; the gauge location coordinates still relate to the uncalibrated image.

Example:

C++ Native

       // Position the gauge at (250, 200) pixels, from 0 to 180 degrees

       ArcGauge.Locate(XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the World calibrator

       ArcGauge.Detect(Src, World);

       // Get the calibrated radius, in mm

       double Radius= ArcGauge.FittedRadius;

C++.NET using namespace mVizNET;

       // Position the gauge at (250, 200) pixels, from 0 to 180 degrees

       ArcGauge.Locate(XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the World calibrator

       ArcGauge.Detect(Src, World, EdgeSelection::BestStep);

       // Get the calibrated radius, in mm

       double Radius= ArcGauge.FittedRadius;

C# using mVizNET;

       // Position the gauge at (250, 200) pixels, from 0 to 180 degrees

       ArcGauge.Locate(new XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the World calibrator

       ArcGauge.Detect(Src, World, EdgeSelection.BestStep);

       // Get the calibrated radius, in mm

       double Radius= ArcGauge.FittedRadius;

Visual Basic

       // Position the gauge at (250, 200) pixels, from 0 to 180 degrees

        ArcGauge.Locate(New mVizNET.XY(250, 200), 100, 0, 180, 20)

        ' Detect and fit an arc, using the World calibrator

        ArcGauge.Detect(Src, mVizNET.EdgeSelection.BestStep)

        ' Get the calibrated radius, in mm

        Dim Radius As Double = ArcGauge.FittedRadius


Fitting Parallel Sides, Thickness and Caliper Tool

By default the EdgeRectangle detects and fits four edges forming a rectangle. The property FourSides is set to true. But if you set it to false, only the two sides with the direction given by Angle (0 for horizontal) are processed. This allows you to measure the distance between straight parallel sides, i.e. thickness.

Thickness measurement (FourSides false)

Now, using the property FittingSide, one can distinguish between fitting the measurement lines over the edges (FitOver), or against them (FitBefore). In the latter case, you will obtain the tightest thickness that includes all the fitted points. This implements a caliper function.

FittingSide Over vs. FitBefore (Caliper function)

Reference:

EdgeRectangle::FourSides,  EdgeRectangle::Fitting and FittingSide.


Points along a Circular Arc

The EdgePoint detects edges along a line segment. The same can be done along a circular arc by means of the method DetectAlong.

After locating the EdgeArc and invoking the method, you obtain the results of detection just as with the EdgePoint: using the property NumPoints and the method FittedPoint. Note that the Width parameter of the EdgeArc is taken for the Breadth parameter of the point gauge.

The direction angle of the detected edges (w.r.t. the gauge center) can also be obtained as the T component of the FittedEdge field. The method Draw will show the detected edges.

Detection along the circle

Example:

C++ Native

       // Position the gauge at (250, 200), from 0 to 180 degrees

       ArcGauge.Locate(XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       ArcGauge.DetectAlong(Src);

       // Process all raising edges

for (int Index= 0; Index < Gauge.NumPoints(Raising); Index++)

       {

              // Get the edge step

              int Step= Gauge.FittedEdge(Index,Raising).Step;

       }

C++.NET using namespace mVizNET;

       // Position the gauge at (250, 200), from 0 to 180 degrees

       ArcGauge.Locate(XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       ArcGauge.DetectAlong(Src, EdgeSelection::BestStep);

       // Process all rasing edges

       for (int Index= 0; Index < Gauge->NumPoints(Polarities::Raising); Index++)

       {

              // Get the edge step

              int Step= Gauge->FittedEdge(Index, Polarities::Raising).Step;

       }

C# using mVizNET;

       // Position the gauge at (250, 200), from 0 to 180 degrees

       ArcGauge.Locate(new XY(250, 200), 100, 0, 180, 20);

       // Detect and fit an arc, using the default BestStep rule

       ArcGauge.DetectAlong(Src, EdgeSelection.BestStep);

       // Process all raising edges

       for (int Index= 0; Index < Gauge.NumPoints(Raising); Index++)

       {

              // Get the edge step

              int Step= Gauge.FittedEdge(Index, Raising).Step;

       }

Visual Basic

       // Position the gauge at (250, 200), from 0 to 180 degrees

        ArcGauge.Locate(New mVizNET.XY(250, 200), 100, 0, 180, 20)

        ' Detect and fit an arc, using the default BestStep rule

        ArcGauge.DetectAlong(Src, mVizNET.EdgeSelection.BestStep)

       ' Process all raising edges

       For Index As Integer = 0 To Gauge.NumPoints(mVizNET.Polarities.Raising) - 1

       ' Get the edge step

       Dim PointStep As Integer = Gauge. FittedEdge(Index, mizNET.Polarities.Raising).Step

       Next Index

Reference:

EdgeArc::BestSlope, EdgeArc::BestStep, EdgeArc::BestSpan, EdgeArc::MinimumStep, EdgeArc::MinimumSlope, EdgeArc::MinimumSpan, EdgeArc::DetectAlong and EdgeArc::Draw.


Advanced: Serializing the Gauge Settings

All the gauges descriptors, including position and edge detection parameters, can be saved to a disk file and later reloaded. This is done for the individual gauges, by means of Write and Read methods.

The following file extensions are suggested, though not mandated:

EdgePoint | edp
EdgeLine | edl
EdgeArc | eda
EdgeEllipse | ede
EdgeRectangle | edr

Gauge File Types

Reference:

EdgePoint::Read, EdgeLine::Read, EdgeArc::Read, EdgeEllipse::Read, EdgeRectangle::Read, EdgePoint::Write, EdgeLine::Write, EdgeArc::Write, EdgeEllipse::Write and EdgeRectangle::Write.


Advanced: Getting all Fitted Points

In case you would like to perform your own analysis of the points found along an EdgeLine, EdgeArc, or EdgeRectangle, you can use the procedure below.

Perform a loop where you make the property SampleIndex vary from 0 to NumSamples –1.

· Call the Detect method; it will analyze a single profile (instead of doing the whole fitting as when SampleIndex == All);

· Check the value of the property NumPoints. It must be at least 1, meaning that at least one point was found (or more depending on the value of EdgeIndex that you passed);

· Get the coordinates of the desired point with the method FittedPoint (be sure to pass the same value of EdgeIndex and Polarity).

Make sure to reset SampleIndex= All if you want to perform model fitting anew with the gauge.

Example:

C++ Native

       // Detect the sample points one by one

       for (LineGauge.SampleIndex= 0; LineGauge.SampleIndex < LineGauge.NumSamples; LineGauge.SampleIndex++)

       {

              // Analyze this profile, looking for the BestStep edge

              LineGauge.Detect(Src, BestStep);

              if (LineGauge.NumPoints() > 0)

              {

                     // Get the edge point location

                     XY Point= LineGauge.FittedPoint(BestStep);

              }

       }

C++.NET using namespace mVizNET;

       // Detect the sample points one by one

       for (LineGauge.SampleIndex= 0; LineGauge.SampleIndex < LineGauge.NumSamples; LineGauge.SampleIndex++)

       {

              // Analyze this profile, looking for the BestStep edge

              LineGauge.Detect(Src, EdgeSelection::BestStep);

              if (LineGauge.NumPoints(Polarities::Both) > 0)

              {

                     // Get the edge point location

                     XY Point= LineGauge.FittedPoint((int)EdgeSelection::BestStep, Polarities::Both);

              }

       }

C# using mVizNET;

       // Detect the sample points one by one

       for (LineGauge.SampleIndex= 0; LineGauge.SampleIndex < LineGauge.NumSamples; LineGauge.SampleIndex++)

       {

              // Analyze this profile, looking for the BestStep edge

              LineGauge.Detect(Src, EdgeSelection.BestStep);

              if (LineGauge.NumPoints(Polarities.Both) > 0)

              {

                     // Get the edge point location

                     XY Point= LineGauge.FittedPoint((int)EdgeSelection.BestStep, Polarities.Both);

              }

       }

Visual Basic

        ' Detect the sample points one by one

        For Index As Integer = 0 To LineGauge.NumSamples - 1

            ' Analyze this profile, looking for the BestStep edge

            LineGauge.SampleIndex = Index

            LineGauge.Detect(Src, mVizNET.EdgeSelection.BestStep)

            If (LineGauge.NumPoints(mVizNET.Polarities.Both) > 0) Then

                ' Get the edge point location

                Dim Point As mVizNET.XY = LineGauge.FittedPoint(mVizNET.EdgeSelection.BestStep, mVizNET.Polarities.Both)

            End If

        Next

Reference:

EdgeLine::Detect, EdgeLine::NumSamples, EdgeLine::SampleIndex, EdgeArc::Detect, EdgeArc::NumSamples, EdgeArc::SampleIndex, EdgePoint::NumPoints, EdgePoint::FittedPoint, EdgePoint::FittedPoint.


Derived Measurements

When edges have been fitted and located, several quantities can be derived from them by geometric constructions of two kinds: distance and angle measurements. The Euclidean plane is assumed.

In addition to functions that compute the distances (Distance, Angle), graphical utilities are also provided to draw the measurement arrows with optional labeling of the numerical value (Distance, Angle).

Be sure to use the fitted results from the edge gauges rather than the positioning coordinates: FittedPoint, FittedBeg/FittedEnd (line), FittedCenter/FittedRadius (circle).


Distances

Distances are computed between two points, ligne segments or circles. All combinations are allowed. The closest distance rule is used, corresponding to orthogonal projections.

Note that the line/line distance case is special in that it is defined only when the lines are parallel. As this may not be the case in practice, the average distance over the common area of support is computed.

Reference:

XY::Distance (6 overloads), Graph::Distance (6 overloads), EdgePoint::FittedPoint, EdgeLine::FittedBeg, EdgeLine::FittedEnd, EdgeArc::FittedCenter, EdgeArc::FittedRadius.


Angles

Angles are computed between three points or two line segments (four points).

Reference:

XY::Angle (2 overloads), Graph::Angle (2 overloads), EdgePoint::FittedPoint, EdgeLine::FittedBeg, EdgeLine::FittedEnd.


Template Matching

Template matching is a powerful and general purpose technique to locate features in an image, for alignment purposes (robot guidance) or defining of areas of interest. The class Locator handles the template matching algorithm.

The usage is straightforward: in a first training step, the template is shown and recorded. Then for all subsequent images, the template, or similar instances, are searched for and located. A numerical matching score is computed and is a good indication of the similarity of the initial template and the one(s) found in the target image. In addition, a relative contrast is computed (ratio between the lightness of the instance and that of the instance).

Training a template

Searching for similar occurrence(s)


Template Training

The Train method analyses the given template image (usually from a window of interest), detects alignment features and stores them in a reference model.

For ease of use, the template definition can be saved to an external file and later reloaded. This is done through the methods Write and Read.

Training a template

Example:

C++ Native

       Locator Template;

       // Train

       Src.Window(86, 343, 47, 41);

       Template.Train(Src);

       // Save

       Template.Write("Template.loc");

C++.NET using namespace mVizNET;

       Locator^ Template= gcnew Locator;

       // Train

       Src->Window(86, 343, 47, 41);

       Template->Train(Src);

       // Save

       Template->Write("Template->loc");

C# using mVizNET;

       Locator Template = new Locator();

       // Train

       Src.Window(86, 343, 47, 41);

       Template.Train(Src);

       // Save

       Template.Write("Template.loc");

Visual Basic

       Dim Template As mVizNET.Locator = New mVizNET.Locator

       ' Train

       Src.Window(86, 343, 47, 41)

       Template.Train(Src)

       ' Save

       Template.Write("Template.loc")

Reference:

Locator::Train, Locator::Write, Locator::Read.


Searching

After training, instances are searched for by invoking the Find method. It returns the best instances found, as long as their score exceeds the MinScore property, their contrast exceeds a MinContrast and as long as their count does not exceed MaxLocations. If you want to find damaged instances, lower the minimum score. If you want to find instances in low light, lower the minimum contrast.

The location of the instances can be retrieved by means of the method Location with an index, giving access to a Pose structure that holds the location information. The total number of suitable instances that were found is given by NumLocations.

Searching for similar occurrences

Example:

C++ Native

       // Find the four best instances

       Template.MaxLocations= 4;

       Template.Find(Src);

       // Get the anchor point of the best instance

       double Xa= Template.Location(0).X;

       double Ya= Template.Location(0).Y;

C++.NET using namespace mVizNET;

       // Find the four best instances

       Template->MaxLocations= 4;

       Template->Find(Src);

       // Get the anchor point of the best instance

       double Xa= Template->Location(0).X;

       double Ya= Template->Location(0).Y;

C# using mVizNET;

       // Find the four best instances

       Template.MaxLocations = 4;

       Template.Find(Src);

       // Get the anchor point of the best instance

       double Xa = Template.Location(0).X;

       double Ya = Template.Location(0).Y;

Visual Basic

       ' Find the four best instances

       Template.MaxLocations = 4

       Template.Find(Src)

       ' Get the anchor point of the best instance

       Dim Xa As Double = Template.Location(0).X

       Dim Ya As Double = Template.Location(0).Y

Instances can also be searched for with allowed rotation and/or scaling. Set the rotation limits using the properties MinAngle and MaxAngle, in range -180 to +180° (or 0° to 180°). Set the scaling limits using the properties MinScale and MaxScale. It is advisable to remain in the scale range of 70% to 140%.

Allowing rotation

Search results

Reference:

Locator::Find, Locator::MinScore, Locator::MinContrast, Locator::MaxLocations, Locator::NumLocations, Locator::MinAngle, Locator::MaxAngle, Locator::MinScale, Locator::MaxScale, Locator::Location, Pose.


Calibrated location

When simple calibration has been activated, the returned coordinates are implicitly converted to the desired measurement units.

Explicit calibration with a Geometry object is also supported (see the section on advanced calibration). You can pass it to the Location method of a Locator object.

Note that only the center coordinates are influenced, as the search is deemed to be done using the same calibrated coordinates as the training, and the angle/scale are dimensionless magnitudes.

Also note that only the Translation, Rotation, Scaling and Similarity RegistrationModels make sense here as the other modes would result in a deformed template.


Deskewing and Normalization

In some circumstances, you want to compare the instance(s) that you found to the original template. To enable this, you must compensate for the translation, rotation and/or scaling to make the two images comparable.

In other circumstances, you just want to restore the instance(s) in a standard position, i.e. perform deskewing or restore the original scale.

This is made possible by means of the method Register, which will extract the content of the instance window and reset it to the same size and direction as the training window.

Trained template

Instance found

Registered instance

Note that there is also an overload of the Register method wich allows you to find the coordinates of corresponding points either in the training image or in the search image.

Reference:

Locator::Register.


Advanced feature: overlapping instances

In some circumstances, one is interested in finding several instances of parts which can be in close contact, or even one on top of each other, with partial occlusion.

The parameter MaxOverlap expresses an overlap allowance as a fraction of the template area. A value 0 disallows any overlap, and 1 full overlap – which does not make sense. We recommend to avoid exceeding the value 0.5.

Notes. The whole training area is used to define the template, and overlapping refers to that area, even if the object of interest is smaller. In the area mode, the matching score can be severely lowered by the overlap. This effect is lessened in the edge mode.

Reference:

Locator::MaxOverlap.


Advanced feature: training with don’t care areas

Sometimes you want to train for templates that have an irregular shape or with a varying content that shouldn’t be part of the template, such as a variable marking or unfinished side.

The template matcher allows you to train from rectangular or circular windows, and it also supports arbitrarily shaped ones.

There are two ways to specify the template shape:

- As a bitmap mask image: every white pixel corresponds to an active pixel in the template;

- As a region mask: the region defines the useful template area.

Training Area to be ignored

Any method to create a mask is allowed, such as binarizing an existing image (binarize) or combining regions into another (see the Region class). Then use one of the Train overloads taking an image mask argument or a region argument in addition to the usual image argument.

           void Train(const Image& Mask, const Image& Src);

           void Train(const Region& Mask, const Image& Src);

Example:

Train on the light parts of the image (gray level ³ 128).

C++ Native

       Locator Template;

       // Train

       Src.Window(86, 343, 47, 41);
       Operator::Binarize(128, Src, Msk);

       Template.Train(Msk, Src);

C++.NET using namespace mVizNET;

       Locator^ Template= gcnew Locator;

       // Train

       Src->Window(86, 343, 47, 41);

       Operato::Binarize(128, Src, Msk);

       Template->Train(Msk, Src);

C# using mVizNET;

       Locator Template = new Locator();

       // Train

       Src.Window(86, 343, 47, 41);
       Operator.Binarize(128, Src, Msk);

       Template.Train(Src);

Visual Basic

       Dim Template As mVizNET.Locator = New mVizNET.Locator

       ' Train

       Src.Window(86, 343, 47, 41)
       Operator.Binarize(128, Src, Msk)

       Template.Train(Msk, Src)

Reference:

Locator::Train, Locator::Write, Locator::Read.


Advanced Feature: searching in non-rectangular areas

Sometimes you want to search in regions that are not the whole image nor a rectangular window, for example to avoid finding all instances. To achieve this, the method SearchMask can be called before the search itself. From then on the search will be restricted to the region defined, until you call the method with no argument (this resets to the whole image).

There are two ways to specify the searchmask shape:

- As a bitmap mask image: every white pixel corresponds to an active pixel in the template;

- As a region mask: the region defines the useful template area.

Any method to create a mask is allowed, such as binarizing an existing image (binarize) or combining regions into another (see the Region class). Then use one of the SearchMask overloads taking an image mask argument or a region argument in addition to the usual image argument.

           void SearchMask(const Image& Mask);

           void SearchMask(const Region& Mask);

The third overload removes the current mask.

           void SearchMask();

Example:

C++ Native

       // Search inside a binarized image

       Operator::Binarize(128, Reg, Msk);
       Template.SearchMask(Msk);

       Template.Find(Src);

C++.NET using namespace mVizNET;

       // Search inside a binarized image

       Operator.Binarize(128, Reg, Msk);
       Template->SearchMask(Msk);

       Template->Find(Src);

C# using mVizNET;

       // Search inside a binarized image

       Operator.Binarize(128, Reg, Msk);
       Template.SearchMask(Msk);

       Template.Find(Src);

Visual Basic

       ' Search inside a binarized image

Operator.Binarize(128, Reg, Msk);
       Template.SearchMask(Msk);

       Template.Find(Src);

Note that when a mask is active, saving the template with Write will save the search mask as well. The method SearchMaskImage lets you retrive the current mask.

Note that the search in a non-rectangular area can be slower.

Reference:

Locator::SearchMask, Locator::SearchMask Image, Locator::Write, Locator::Read.


Advanced Feature: Symmetric templates

In many cases, the template has a rotational symmetry or quasi-symmetry. When searching for such templates, ambiguities can arise, causing the matching to be wrong by 90° or 180°.

There are also cases where you want to detect if a component was not placed turned-over by a half turn or a quarter turn. But doing that with full-rotation can be time-consuming.

The locator provides a property for that purpose: Symmetry. This is an integer that announces the rotational symmetry of the template (2 for 180°, 4 for 90° - other integers are allowed). When the symmetry is larger than 1, angles in multiple of 2Pi/S will be tried.

Matching with 180° reversal

Reference:

Locator::Symmetry.


Optimizing the search

Be cautious when setting these values as too large search ranges will increase the running time and make false matches more probable.

Also make sure that the template to be searched is unambiguously defined for the chosen degrees of freedom, and has sufficient contrast on different scales.

Poor templates

1 2 3 4

1: ambiguous for translation

2: low contrast

3: not enough larges scale features

4: ambiguous for rotation (if rotation used)

Good templates

The Locator works by using an image pyramid, where the levels are made of a coarser and coarser representation of the image, to speed up operation. The levels used range from MaxDepths (coarsest, typically 5 to 8) down to StopDepth (finest, 0 by default).

When searching suffers from reliability, the value of MaxDepths can be decreased to start working on finer details. This is done at the expense of running-time, though.

On another hand, you can bypass the last refinement steps by setting the StopDepth parameter to a value higher than 0. You will gain in speed but loose in accuracy.

The following constraint holds:

0 £ StopDepth £ MaxDepths £ MaxAreaDepths

where MaxAreaDepths is computed during the training phase. (For the geometric mode, there is a corresponding MaxEdgesDepths limit.)

Reference:

Locator::MaxDepths, Locator::StopDepth, Locator::MaxAreaDepths and Locator::MaxEdgesDepths.


Standard vs Geometric Matching

As state of the art in machine vision software has established, there are two well-known approaches to template matching.

One is the so-called Normalized Grayscale Correlation, or area-based template matching. It works by computing a matching score based on the pixel-by-pixel comparison of gray-level values, applying a linear transform of the gray scale to deal with global changes in illumination.

The other is called Geometric Template Matching, or edge-based matching. It focuses on the location and direction of the edges of the template rather than on the whole area, so that it better captures shape information. For this reason, it is suited for dealing with non-linear and non-uniform changes in illumination, as well as clutter and occlusion.

The Locator object supports both matching methods. To switch between these, use the property Edges before performing a Find. There is no need to train again. As simple as that!

Reference:

Locator::Find, Locator::Edges.


Shape Matching

Template matching is a very powerful way to find copies of a previously trained image, defined either by all pixels or all edges in a region. This functionality is supported by the Locator object.

An alternative is provided by the ShapeMatcher, which is based exclusively on the outline of an object. Outlines can be obtained from contouring (using the Follow method), from blob analysis (Outline) or can be created directly by the user (Append).

The ShapeMatcher can be trained on one or more shape to serve as reference for future comparison. Then when a new outline is presented, possibly with rotation and scaling, the ShapeMatcher can retrieve the pose information.

In addition to that, the ShapeMatcher will also discriminate between the different models that have been trained and reports the most similar matching. In so doing, it performs at the same time recognition and precise location.


Shape Training

Training is performed by submitting shapes one after the other. Two methods are possible:

· The shapes are defined using a Path object, explicitly filled or obtained by contouring; it is also possible to get the path around a Region;

· The shapes are defined from the outline of blobs previously segmented.

Note that training is made one shape at a time. At the same time as you specify the shape, you will provide a Class index, specifying some classification information to distinguish it. The call is one of:

       void ShapeMatcher::Train(Path& Outline, int ClassIndex, int Symmetry= 1);

or

       void ShapeMatcher::Train(Blobs& Src, int BlobIndex, int ClassIndex, int Symmetry= 1);

You can also specify a Symmetry information, which is a hint to the matcher about symmetry present in the shape. Setting the appropriate symmetry has two benefits:

· It can reduce the search time by avoiding unnecessary comparisons,

· It can avoid rotational ambiguities.


Shape Recognition

Similarly as for training, recognition is achieved by presenting an outline, either stored in a Path or as the outline of a blob.

       int ShapeMatcher::Recognize(Path& Outline, int& Class, Pose& Location);

or

       void ShapeMatcher::Recognize(Blobs& Src, int BlobIndex= AllSelected);

When recognition has been performed, you get information on the pose of the recognized instance, and the Class index. In the case of a simple outline, this information is directly returned. In the case of blob(s) outline(s), this information is stored in the blobs feature table where it can be handled like ordinary features (sorting, selection…). Several blobs can be processed at a time.


Character Recognition

Human-readable markings such as serial numbers or expiration dates printed with block characters can also be read by the computer. The characters are first segmented out of the image to treat them in isolation. Then they are compared to a reference font and the closest matches are reported.

The class CharReader handles character recognition.

Segmentation followed by recognition

For an effective reading, the characters in the font must look like those in the above images. Some predefined character fonts are available. Anyway, for best results, it is advisable to create a custom font file based on available text samples.

The layout of the character string(s) can be free, i.e. the reader reports what it finds in the image, or pre-trained, i.e. the reader keeps a stored model of the character placement and checks the matching with the new marking. (Check the Layout section).

The nature of the individual characters can be free, or restricted to a category such as letters or digits. (Check the Filtering section).


Font Training

Training is the process of defining the set of characters to be recognized, also called the font. The training can be done from an existing training utility program such as mViz OCR or can be done programmatically.

Reference character samples

When a character has been segmented out, a numeric code is associated to it (taken from the ASCII or UNICODE standards), as well as an optional class value. The character image is stored for later use, while its size is normalized to a fixed value to ease later comparison.

Size normalization

The training can be done character by character or a whole string at a time. The font definition can be saved to a file for later reuse.


Character Segmentation

The first step in OCR is to find the characters. You first specify a region of interest that contains the text to be recognized. In case that the characters are not in upright position, you can select an alternative orientation, in multiples of 90°.

Then you specify the contrast of the characters (usually black on white but can be the converse). If the illumination is not uniform, you can specify that an adaptive threshold be used for better binarization.

The next step is to indicate the size of the characters. By default, mViz is able to find it automatically. Anyway, in difficult cases such as when there are several character sizes visible, you can specify the size manually. In some fonts, the characters don’t all have the same width; this can be dealt with, with the option VariableWidth.

The size of the characters must be specified with the properties CharWidth and CharHeight, or can be estimated automatically using GuessSize. (When a font has characters of varying heights, such as mixed-case, it is safer to use GuessSize in combination with KeepRatio.)

White on black, rotated characters, auto size

You display the segmented characters by means of the method Draw, and you can retrieve their coordinates with GetBoxes.

Characters segmentation can fail when the characters are too thin and appear fragmented, or too thick, they can touch each other. mViz supports heuristics to work around these difficulties.

Special character conditions can be dealt with as follows: the RepairBroken flag will group character pieces that are close together. The MaxTouching parameter sets an allowance on the number of characters that might touch each other, requiring automatic splits. (Setting a 0 value will disallow splitting.) You can also adjust the relative size of the inter-character space via GapFraction .

Tiny blobs that correspond to clutter, dirt or stains are automatically discarded. Any blob with a size smaller than 50% of the character size in both height and width is ignored. If this causes small characters like hyphens '-' or dots '.' to be removed, you can lower the DotFraction criterion.

Normally the characters are segmented individually where they are found. Mixed-case fonts can cause problems as some lowercase letters are smaller than uppercase. This is handled by considering all characters to rest on a common baseline.

Realignment

Reference:

CharReader::Read, CharReader::CharsSegment, CharReader::Draw, CharReader::GetBoxes, CharReader::CharWidth, CharReader::CharHeight, CharReader::GuessSize, CharReader::KeepRatio, CharReader::RepairBroken, CharReader::MaxTouching, CharReader::GapFraction, CharReader::DotFraction, CharReader::CharsRead, CharReader::CharsDecode, CharReader::AsciiString, CharReader::UnicodeString, CharReader::InsertSpaces, CharReader::OCVScoring, CharReader::InsertNewlines and CharReader::VariableWidth.


Recognition of the Characters

When a font has been trained (loaded from a file via Read), recognition is done in a single step, using the CharsRead method, which performs segmentation then recognition. The result is available as properties AsciiString or UnicodeString, as well as a global recognition score AverageScore and global contrast AverageContrast.

You can display the recognized character with the overlay by passing Draw the value true for the Codes argument .

Caution: to obtain the best results, it is important that the recognition be made with the same settings as those that were used at training time. Otherwise, there is a stronger chance that the characters will look different or will be framed differently, resulting in a poor matching score.

Example:

C++ Native

       // Read the text (white on black, unknown size)

       Ocr.WhiteOnBlack= true;

       Ocr.GuessSize= true;

       Ocr.CharsRead(Src);

       // Display the string and score

       printf("%s, Score: %.3f\n", Ocr.AsciiString, Ocr.AverageScore);

C++.NET using namespace mVizNET;

       // Read the text (white on black, unknown size)

       Ocr->WhiteOnBlack= true;

       Ocr->GuessSize= true;

       Ocr->CharsRead(Src);

       // Display the string and score

       Console::WriteLine("{0}, Score: {1}", Ocr->AsciiString, Ocr->AverageScore);

C# using mVizNET;

       // Read the text (white on black, unknown size)

       Ocr.WhiteOnBlack = true;

       Ocr.GuessSize = true;

       Ocr.CharsRead(Src);

       // Display the string and score

       Console.WriteLine("{0}, Score: {1}", Ocr.AsciiString, Ocr.AverageScore);

Visual Basic

       ' Read the text (white on black, unknown size)

       Ocr.WhiteOnBlack = True

       Ocr.GuessSize = True

       Ocr.CharsRead(Src)

       ' Display the string and score

       Console.WriteLine("{0}, Score: {1}", Ocr.AsciiString, Ocr.AverageScore)

Reference:

CharReader::Read, CharReader::Draw, CharReader::CharsRead, CharReader::AsciiString, CharReader::UnicodeString, CharReader::AverageScore and CharReader::AverageContrast.


Advanced feature: Stroke Width and Connectedness

Stroke width (thickness) plays an important role in character recognition. The same characters with different stroke width will match poorly.

In cases where training has been performed with a different thickness than the characters to be recognized (in particular when using pre-trained font files), you may correct the thickness using the property InkingCorrection, a small positive or negative number.

Thickness adjustment required

Caution: when the training and processed characters are the same, leave InkingCorrection=0.

Characters produced by a dot printer (needle or ink jet) can be made of disconnected dots. These are challenging to segment. A workaround is provided by the property Dotted (a small positive number), which improves connectedness (but contrary to InkingCorrection, it does not modify the stroke thickness).

Connectedness adjustment required

Use the same setting a training and reading-times.

Reference:

CharReader::InkingCorrection and CharReader::Dotted.


Advanced feature: Global Filtering

In some cases, in particular when you use the pre-trained font files, you want to allow only some categories of characters in the recognition process (among lowercase letters, uppercase letters, digits and special characters). The GlobalFilter serves this purpose by using a one-character code that corresponds to a combination of those catagories.

 | Any | A lphabetic | L owercase | U ppercase | Digit | Special
Alone | * | a | l | u | 9 | .
+ digits |  | A | L | U |  |
+ special |  | b | m | v | 0 |
+ digits + special |  | B | M | V |  |

Special characters are any printable character that is neither a letter or a digit. The pre-trained fonts contain the following special characters: <=>+-*/\()%#&@$€¥.

The default is * which accepts any characters. Common choices are u (uppercase only), U (uppercase or digit), V (uppercase or digit or special). Make sure to adjust the global filter to the marking to be processed, to optimize speed and reliability.

Reference:

CharReader::GlobalFilter.


Advanced feature: Per-character Filtering

When the structure of the string is fixed, it is possible to specify the type of characters to be found. This process is known as filtering. It reduces the running time while increasing the robustness.

The filter string is composed of the following specifiers (compatible with the GlobalFilter convention):

%9: any digit,

%l: any lowercase letter,

%L: any lowercase letter or digit,

%u: any uppercase letter,

%U: any uppercase letter or digit,

%a: any letter (lower or uppercase),

%A: any alphanumeric,

%0: any digit or special character,

%m: any lowercase letter or special character,

%M: any lowercase letter or digit or special character,

%v: any uppercase letter or special character,

%V: any uppercase letter or digit or special character,

%b: any letter (lower or uppercase) or special character,

%B: any alphanumeric or special character,

%.: any special character,

%*: any character,

%-: ignore this character,

any printing character: exactly this character, verbatim

%%: the % character.

When no character in the font matches a filter specifier, a question mark character is returned. When a printing character is forced (verbatim), its score is assumed to be 100% (unless OCVScoring is activated).

If the filter string is shorter than the string to be recognized, the last specifier is repeated as many times as needed. For this reason, the default string "%*" will accept anything.

Example:

C++ Native

       // 'Serial' folllowed by an uppercase letter and three digits

       char Filter[]= "Serial%u%9%9%9";

C++.NET using namespace mVizNET;

       // 'Serial' folllowed by an uppercase letter and three digits

       char Filter[]= "Serial%u%9%9%9";

C# using mVizNET;

       // 'Serial' folllowed by an uppercase letter and three digits

       string Filter = "Serial%u%9%9%9";

Visual Basic

       ' 'Serial' folllowed by an uppercase letter and three digits

       Dim Filter As String = "Serial%u%9%9%9"

Reference:

CharReader::OCVScoring and CharReader::Filter.


Advanced feature: Jittering

Character segmentation relies on binarization. In unlucky cases, the location of the characters can be mis-estimated by a few pixels. To compensate, jittering will try different positions by moving the character box up to the specified number of pixels horizontally and vertically. Use the feature sparingly to limit the computational load. The default value is 1 on X and Y.

Example:

C++ Native

       // Allow +/- two pixels of horizontal jitter

       Ocr.JitterX= 2;

       Ocr.CharsRead(Src);

C++.NET using namespace mVizNET;

       // Allow +/- two pixels of horizontal jitter

       Ocr->JitterX= 2;

       Ocr->CharsRead(Src);

C# using mVizNET;

       // Allow +/- two pixels of horizontal jitter

       Ocr.JitterX = 2;

       Ocr.CharsRead(Src);

Visual Basic

       ' Allow +/- two pixels of horizontal jitter

       Ocr.JitterX = 2

       Ocr.CharsRead(Src)

Reference:

CharReader::JitterX and CharReader::JitterY.


Advanced feature: Space and Newline Detection

The reader will automatically detect white space (void in the text as large as a character) and line jumps (vertical shift downward).

By default, it will insert space (' ') and newline characters ('\n') in the output string. This behavior can be disabled by means of the properties InsertSpaces and InsertNewlines.

Example:

C++ Native

       // Disable space insertion

       Ocr.InsertSpaces= false;

       Ocr.CharsRead(Src);

C++.NET using namespace mVizNET;

       // Disable space insertion

       Ocr->InsertSpaces= false;

       Ocr->CharsRead(Src);

C# using mVizNET;

       // Disable space insertion

       Ocr.InsertSpaces = false;

       Ocr.CharsRead(Src);

Visual Basic

       ' Disable space insertion

       Ocr.InsertSpaces = False

       Ocr.CharsRead(Src)

Reference:

CharReader::InsertSpaces and CharReader::InsertNewlines.


Advanced feature: Layout

At training time if you invoke the LayoutTrain method, the CharReader will remember the exact arrangement of the characters and store it as a layout model.

Trained layout

Then at the next CharsRead operation, the segmented characters will be matched to the layout model. Translation and rotation are allowed during the matching. The range of skew angles can be specified by means of MinAngle and MaxAngle. After the correspondence has been established, missing characters will be reported as ‘?’ items in the recognized string and extra characters of clutter will be ignored.

No layout, extra character detected

Rigid layout, slight misalignment

Flexible layout, misalignment fixed

The layout mode supports two further options: in the rigid mode, the layout model is applied exactly as at train-time and moves rigidly. In the flexible mode, a secondary translation allowance is given after matching of the whole model, so that individual characters are matched closely. This behavior is driven by the property LayoutMode.

Reference:

CharReader::LayoutTrain, CharReader::MinAngle, CharReader::MaxAngle and CharReader::LayoutMode.


Advanced feature: Font Optimization

You are free to train as many samples of the characters as you like, and they will all be used for recognition. Anyway, this lengthens the recognition time proportionally to the total number of samples.

You can alleviate this by means of the method Optimize, which selects a subset of the samples in such a way that the recognition performance does not degrade.

Large training set

Optimized training set

Important note: the global filter is applied when optimizing, so that the trained characters foreign to the filter are discarded.

Important note: during the training operations, all samples are retained, even if you optimize. When you save the font to a file (using Write), you have the option of keeping all samples, or just the result of optimization. In the latter case, all other samples are lost. Depending on your needs, you can work in two ways:

· Save and later reload only the optimized font;

· Save the whole font and every time you reload it, perform the optimization anew.

Reference:

CharReader::Optimize, CharReader::GlobalFilter and CharReader::Write.


Verification

In some applications, it is more important to check what has been printed than to read it. In the first case, the content of the text is known beforehand and a rating of the quality is wanted; in the second case, the text needs to be discovered.

The CharReader supports both approaches by combining the features below:

1. Characters are recognized from the training set by considering the best matches;

2. Characters are assessed by reporting a matching score that quantifies the resemblance to the original template; the score can be compared to a reference threshold called MinimumScore, or to a threshold automatically determined by comparing to the other characters in the font; see the UseSafeScores property;

3. A per-text AverageScore is also available;

4. Character values can be restricted partially or completely by means of the filter mechanism; for example, filtering with "Serial%u%9%9%9" will assess the quality of the fixed and variable parts of the serial mark. To verify the fixed parts, set the property OCVScoring to true, and train on these characters as well;

5. Character placement can be constrained by means of the LayoutTrain mechanism, meaning that extra, displaced or missing characters can be detected.

Reference:

CharReader::MinimumScore, CharReader::UseSafeScores CharReader::AverageScore, CharReader::OCVScoring and CharReader::LayoutTrain.


More on Training

In order to record a font from a series of images, one needs to:

  • Segment the characters from an image by means of CharsSegment.
  • Pass the corresponding string of characters to FontStringInsert.
  • Repeat for as many images as wanted.

Example:

C++ Native

       // Segment the font characters, providing the size

       Ocr.CharWidth= 20;

       Ocr.CharHeight= 30;

       Ocr.CharsSegment(Src);

       // Train with the segmented characters

       Ocr.FontStringInsert(Src, "012345");

C++.NET using namespace mVizNET;

       // Segment the font characters, providing the size

       Ocr->CharWidth= 20;

       Ocr->CharHeight= 30;

       Ocr->CharsSegment(Src);

       // Train with the segmented characters, in sorted order

       Ocr->FontStringInsert(Src, "012345", 0, -1);

C# using mVizNET;

       // Segment the font characters, providing the size

       Ocr.CharWidth = 20;

       Ocr.CharHeight = 30;

       Ocr.CharsSegment(Src);

       // Train with the segmented characters, in sorted order

       Ocr.FontStringInsert(Src, "012345", 0, -1);

Visual Basic

       ' Segment the font characters, providing the size

       Ocr.CharWidth = 20

       Ocr.CharHeight = 30

       Ocr.CharsSegment(Src)

       ' Train with the segmented characters, in sorted order

       Ocr.FontStringInsert(Src, "012345", 0, -1)

Alternatively, individual characters can be trained one by one by means of FontCharInsert, using an appropriate Window.

Example:

C++ Native

       // Train from the character image

       Ocr.FontCharInsert(Src, '0');

       // Save to a file

       Ocr.Write("MyFont.ocr");

C++.NET using namespace mVizNET;

       // Train from the character image, in sorted order

       Ocr->FontCharInsert(Src, '0', 0, -1);

       // Save to a file (all)

       Ocr->Write("MyFont->ocr", false);

C# using mVizNET;

       // Train from the character image, in sorted order

       Ocr.FontCharInsert(Src, '0', 0, -1);

       // Save to a file (all)

       Ocr.Write("MyFont.ocr", false);

Visual Basic

       ' Train from the character image, in sorted order

       Ocr.FontCharInsert(Src, Chr(0), 0, -1)

       ' Save to a file (all)

       Ocr.Write("MyFont.ocr", False)

For user feedback, the trained characters can be visualized by means of the method DrawFontChars. Unwanted characters can be removed from the font with FontCharDelete. If you want to point at a character in the font, use the method HitFontChar, which will tell you what character is currently under the cursor.

Font characters are drawn in array fashion

In the end, the font can be saved to a file using Write.

Example:

C++ Native

       // Draw the raw font characters in a 256 by 128 window, with spacing

       Ocr.DrawFontChars(0, 0, 256, 128, 5, 10);

       // Delete the character under the cursor, if any

       if (Ocr.HitFontChar(0, 0, 256, 128, 5, 10) == AllHandle)

       {

              Ocr.FontCharDelete(Ocr.FontCharIndex);

       }

C++.NET using namespace mVizNET;

       // Draw the raw font characters in a 256 by 128 window, with spacing

       Ocr->DrawFontChars(0, 0, 256, 128, 5, 10, true, true);

       // Delete the character under the cursor, if any

       if (Ocr->HitFontChar(CursorX, CursorY, 0, 0, 256, 128, 5, 10, true) ==
              DraggingHandles::AllHandle)

       {

              Ocr->FontCharDelete(Ocr->FontCharIndex);

       }

C# using mVizNET;

       // Draw the raw font characters in a 256 by 128 window, with spacing

       Ocr.DrawFontChars(0, 0, 256, 128, 5, 10, true, true);

       // Delete the character under the cursor, if any

       if (Ocr.HitFontChar(CursorX, CursorY, 0, 0, 256, 128, 5, 10, true) ==
              DraggingHandles.AllHandle)

       {

              Ocr.FontCharDelete(Ocr.FontCharIndex);

       }

Visual Basic

       ' Draw the raw font characters in a 256 by 128 window, with spacing

       Ocr.DrawFontChars(0, 0, 256, 128, 5, 10, True, True)

       ' Delete the character under the cursor, if any

       If Ocr.HitFontChar(CursorX, CursorY, 0, 0, 256, 128, 5, 10, True) =
              mVizNET.DraggingHandles.AllHandle Then

         Ocr.FontCharDelete(Ocr.FontCharIndex)

       End If

Reference:

CharReader::CharsSegment, CharReader::FontStringInsert, CharReader::FontCharInsert, CharReader::FontCharDelete, CharReader::HitFontChar, CharReader::FontCharIndex and CharReader::Write.


Linear Code Reading (Barcodes)

Barcodes are well known markings that can be read by a scanning device in a reliable way. The Code1DReader class serves the purpose of finding such a code in an image and reading it.

The currently supported symbologies are:

· GS1 128 (EAN128)

· EAN13

· EAN8

· UPC-A

· UPC-E

· Code 39 (Standard, Extended)

· ITF (Interleaved 2 of 5 IATA)

· Code93

· Codabar

· Pharmacode

· GS1 Databar (Standard, Limited)

Other symbologies can be supported on your request.

EAN128 code

EAN13 code

EAN8 code

UPC-A barcode image

UPC-A code

UPC-E code

Code39 code

ITF code

Pharmacode

Codabar code

Databar code

Caution: the Code39 and Code39Extended cannot be discriminated and this can cause wrong decodes. If possible do not use them simultaneously. Contact the Technical Support for more details


Bar Reading

To operate the reader, it suffices to pass an image to the method Decode and retrieve the decoded contents as the property AsciiString or UnicodeString.

Example:

C++ Native

       // Read a barcode

       Code1DReader Barcode;

       Barcode.Decode(Src);
       char* Content = Barcode.AsciiString;

C++.NET using namespace mVizNET;

       // Read a barcode

       Code1DReader^ Barcode= gcnew Code1DReader;

       Barcode->Decode(Src);
       String^ Content= Barcode.AsciiString;

C# using mVizNET;

       // Read a barcode

       Code1DReader Barcode = new Code1DReader();

       Barcode.Decode(Src);
       String Content= Barcode.AsciiString;

Visual Basic

       ' Read a barcode

       Dim Barcode As mVizNET.Code1DReader = New mVizNET.Code1DReader

       Barcode.Decode(Src)
Dim Content As
String = Barcode.AsciiString

You can selectively enable or disable any symbology in order to improve the running time and/or avoid ambiguities. It is advisable to do so. By default, all symbologies are enabled.

Set the following flags to true or false:

· DetectEAN128

· DetectEAN13

· DetectEAN8

· DetectUPCE

· Detect2of5

· Detect39

· Detect39Extended

· Detect93

· DetectDatabar

· DetectDatabarLimited

· DetectPharmacode

The code should be printed black on white with a good contrast.

The Pharmacodes are special in that they can be decoded both ways (left to right or right to left). The user needs to specify the correct direction by means of the Reverse property.

Multiple codes

When there are several barcodes in the image, the reader will decode all of them. To obtain the decodes and other information, call the method Choose after decoding and pass an index, in range 0..NumDecoded-1.

Reference:

Code1DReader, Code1DReader::Choose, Code1DReader::Decode, Code1DReader::AsciiString,   Code1DReader::UnicodeString, Code1DReader::DetectEAN128, Code1DReader::DetectEAN13, Code1DReader::DetectEAN8, Code1DReader::DetectUPCE, Code1DReader::Detect39, Code1DReader::Detect93, Code1DReader::Detect39Extended, Code1DReader::Detect2of5, Code1DReader::DetectDatabar, Code1DReader::DetectDatabarLimited, Code1DReader::DetectPharmacode, Code1DReader::NumDecoded, Code1DReader::Reverse.


Reading parameters

The reader works by drawing profiles across the image and detecting bar-like features. Then the pattern of bar thicknesses is checked for consistency with the supported symbologies. For increased reliability, at least three profiles must be successfully decoded.

Barcodes are quite often imaged horizontally or vertically. By default, the reader is set to detect both configurations. In some situations, such as parcel reading on a conveyor, the barcodes can be seen in a random direction. You will enable reading in oblique directions by increasing the NumDirections parameter. The required number will depend on the dimensions of the barcode: consider the angle formed by the diagonal of the code and its base, and divide 180° by this angle.

Instead of specifying the number of directions, you set the value Auto, which will let the reader guess the direction. This is the default.

30° are covered by 6 directions

By default, profiles are cast on every fifth row. Sometimes, in case of low quality or very thin codes, it may be necessary to use closer profiles. This is achieved by lowering the Density value, which can be as small as 1.

Increasing the scanning Density

Usually, barcodes are printed with an excellent contrast, black on white. Sometimes, the contrast can be poorer due to mis-printing, aging, wear, dirt or other kinds of degradation. If you suspect a lack of contrast, lowering the value of the Noise parameter can help.

From their definitions, barcodes must be framed by a quiet zone on both sides. The quiet zone is an area free of any marking, which must be at least 7 times as large as a thin bar. (For some symbologies, the coefficient differs.) In some cases, the quiet zone may be missing or narrower. Even though such barcodes should be rejected, you can try to read them by disabling the detection of the quiet zone. Use the CheckQuietZone flag for that purpose. Beware though that this could result in false reads inside a valid code, especially if you enabled many symbologies.

To achieve reliable readings and avoid false reads, most symbologies are equipped with a checksum digit feature. (A checksum is a control digit added to the encoded content, such that not all digit combinations are possible.) In principle, a decode with a bad checksum value should be ignored. Anyway, there are symbologies such that the checksum is optional (Code2of5, Code39). mViz helps you deal with that issue by updating the ValidCRC flag. When this flag is true after a read, this means that the CRC value is as expected. For these symbologies, the content is returned in any case; for the other ones, an unsuccessful read is reported in case of a wrong CRC.

Reference:

Code1DReader::NumDirections, Code1DReader::Density, Code1DReader::CheckQuietZone and Code1DReader::ValidCRC.


EAN128 features: FNC1-Reader Programming-Append

The special features described in this section are supported in the frame of the Code 128 symbology only. Refer to the standard ISO/IEC 15417 for more details.

The FNC1 (Function Code One) is an invisible character used to identify and separate fields for variable length application identifiers (following GS1 conventions). An application identifier is used to identify the meaning of the encoded data.

When an FNC1 is met in the first position, the symbology identifier ]C1 is inerted before the decoded string and the flag ReadFNC1 is set. You can disable insertion of the symbology identifier by setting the property SymbologyIdentifier to false.

The Append flag is set when Structured Append is in use, meaning that a large content can be split into several consecutive barcodes. The Append mode is triggered by an FNC2 (Function Code Two) character within the barcode stream. Note that mViz only reports that the Append marker is present, but still works in unbuffered mode; it is the duty of the user to reconstruct the complete message.

The ReaderProgramming flag is set to mean that the barcode content is not aimed at a normal decode but contains information directly intended for the barcode reader. The ReaderProgramming mode is triggered by an FNC3 (Function Code Three) character within the barcode stream. Such codes should just be ignored.

The Extended Mode is triggered by an FNC4 (Function Code Four) character within the barcode stream. It signals to the reader that the following characters are taken from the extended ASCII character set. This feature is handled transparently by the mViz reader.

Reference:

Code1DReader::SymbologyIdentifier, Code1DReader::ReadFNC1, Code1DReader::Append and Code1Dread er::ReaderProgramming.


Pharmacode features: Bar Count-Reverse

The Pharmacode codes are different from others in that they have no checksum and can be very short (2 to 16 bars), so that accidental decodes can occur on bar-like decodes. For this reason, the Pharmacode symbology is disabled by default. Make sure to use a region of interest containing no extraneous feature.

To avoid false detection of tiny symbols, a required number of bars can be specified. By default this is set to 3. You can reduce or increase this value by means of the property MinimumBars.

As nothing indicates the reading direction of a Pharmacode, the flag Reverse allows to specify the orientation: right-to-left instead of left-to-right, or bottom-up instead of top-down.

Direct and Reverse reading directions

Reference:

Code1DReader::MinimumBars and Code1DReader::Reverse.


Barcode Quality Indicators

The Quality Indicators are normalized measures to assess the quality and legibility of a marking (according to ISO/IEC 15416). They are measured on an A-B-C-D-F grade scale, A being ideal; on the opposite, an F grade is unacceptable and means that the code shouldn’t be used. To assess the grades, ten scans are taken across the symbol and different characteristics are evaluated:

- Overall: this takes an average of the ten scan grades below, giving a global idea of the printing quality. Then, per scan:

o    Scan: this is the worst of all following grades (except Quiet Zone), a global indication of the quality of one particular scan.

o    Minimum Reflectance: adequate contrast is required. When the black color level exceeds the half of the white color level, the code gets an F grade and other indicators are not evaluated.

o    Edge Determination: indicates if the scan has the expected number of bars. When that’s not the case, the scan gets an F grade and other indicators are not evaluated.

o    Symbol Contrast: this is complementary to the Minimum Reflectance. The difference between the white and black levels must cover a significant fraction of the possible range.

o    Modulation: is a measure of the contrast on the individual edges. Even though the global contrast can be good, local contrast weakness will reduce this grade.

o    Defect: contrast can be weakened inside the bars (inking defect) or in the spaces (dirty background). The defect grade accounts for this.

o    Decode: reports an F grade if this particular scan cannot be correctly decoded because of wrong bar/space thicknesses.

o    Decodability: compares the bar and space thicknesses to the values in an ideal code and estimates how close we are to an undecodable symbol.

o    Quiet Zone: checks the presence of a sufficient quiet zone at the endpoints of the scan. This grade is not mandated by the ISO standard and does not influence the Scan grade.

To get meaningful values for the indicators, you must enable them via the member CheckQuality. They require the PrintInspection license.

Currently the Quality Indicators are not available for the RSS symbology. They are reported as

- a single character AsciiGrade/UnicodeGrade for the global grade,

- a character in the string AsciiProfileGrades/UnicodeProfileGrades, for all ten scans, in the order

Scan,
Minimum Reflectance,
Edge Determination,
Symbol Contrast,
Edge Contrast,
Modulation,
Defects,
Decode,
Decodability,
Quiet Zone.

For a perfect code: A and ten A AAAAAAAAA.

Typical output

Reference:

Code1DReader::CheckQuality, Code1DReader::AsciiGrade, Code1DReader::UnicodeGrade, Code1DReader::AsciiProfileGrades and Code1DReader::UnicodeProfileGrades.


Advanced: Bar Color Inspection (Pharmacodes)

The Pharmacode symbology allows printing some of the bars in color. This allows to check the colors in use for printing the packages.

Color Pharmacode

To perform this check, first train the Code1DReader on a good quality sample by means of the method ColorTrain. Then, on subsequent calls of the Decode method, colors will automatically be assessed by comparison to the trained references.

The sensitivity of the comparison can be adjusted by the property RgbTolerance, on a 0 to 255 scale. The property ValidColors indicates if all bars successfully pass the check. The overlay drawing will surround the individual bars with a green or red frame.

Reference:

Code1DReader::ColorTrain, Code1DReader::RgbTolerance, Code1DReader::ValidColors.


Advanced: GS1 Application Identifiers

The international organization GS1 uses some barcode and 2D code symbologies to encode product information in a standardized way. They define a number of Application Identifiers with a standard meaning.

E.g., when a barcode encodes the following raw content:

]C101194158357140731081100126339581

The first three characters indicate an EAN128 barcode, while the following digits can be split in several fields, as follows:

GTIN (01): 19415835714073
BATCH/LOT (10): 81100126339581

GS1 format, verbose (non normative)

Conventionally, the barcode content can be printed as

(01)19415835714073(10)81100126339581

GS1 format (normative)

The Code1DReader supplies a method ExpandGS1 that turn the raw representation to the GS1 format with Application Identifiers.

The conversion is done intwo steps: as the length of the string is not known in advance, you need to query the function to determine that length, passing a null for the buffer address. Then after obtaining length information, you allocate a buffer large enough to receive the string and call the function a second time. (If you already know the string length, you can bypass the first call.)

Note that if the raw string starts with a Symbology Identifier (three characters ]cm), it will be ignored.

Reference:

Code1DReader::ExpandGS1.


Bidimensional Code Reading (matrix codes)

2D Codes are a little less well known markings that can be read by a scanning device in a reliable way. The Code2DReader class serves the purpose of finding such a code in an image and reading it.

Data Matrix code

QR Code

The currently supported symbologies are:

· Data Matrix (ISO/IEC 16022, ECC200)

· Quick Response (QR) (ISO/IEC 18004)

The code should be printed with good contrast and sharpness.


Reading

To operate the reader, simply pass an image to the method Decode and retrieve the decoded contents as the property AsciiString or UnicodeString (holding StringLength characters).

Operation of the reader is fully automatic, with arbitrary size and 360° rotation allowed, so there are little things that you need to adjust.

You can selectively enable or disable any symbology in order to improve the running time and/or avoid ambiguities. It is advisable to do so. CAUTION: by default, only the DataMatrix symbology is enabled.

Set the following flags to true or false:

· DetectDataMatrix

· DetectQR

You can specify the exact symbol size (number of cells) or a range of sizes by means of SizeFrom and SizeTo. This is usually unnecessary.


Multiple codes

When there are several barcodes in the image, the reader will decode as many as possible, but you must specify a maximum. The property MaxDecoded is one by default, and you need to increase it before calling Decode.

Then to obtain the text content and other information, call the method Choose and pass an index, in range 0..NumDecoded-1.


Contrast

In some cases the symbols are printed in white on a dark background. In some rare cases, you don’t know beforehand.

The property EnabledPolarities allows you to specify which contrast applies. It can take one of the values BlackOnWhite (the default), WhiteOnBlack, AutoPolarity.

After a successful read, the property Polarity indicates the actual contrast.

White on black symbol


View

Usually, the codes are looked at from the front. Sometimes they are seen through a mirror, or the image is flipped for some reason. Sometimes even you don’t know beforehand.

The property EnabledViews allows you to specify from which side the code is viewed. It can take one of the values Straight (the default), Mirrored, AutoView.

After a successful read, the property View indicates the actual viewing direction.

Straight vs. mirrored (you can’t tell the difference)

Example:

C++ Native

       // Read a dotcode

       Code2DReader Dotcode;

       Dotcode.Decode(Src);

       char* Content = Barcode.AsciiString;

C++.NET using namespace mVizNET;

       // Read a dotcode

       Code2DReader^ Dotcode= gcnew Code2DReader;

       Dotcode->Decode(Src);

       String^ Content= Barcode.AsciiString;

C# using mVizNET;

       // Read a dotcode

       Code2DReader Dotcode = new Code2DReader();

       Dotcode.Decode(Src);

       String Content= Barcode.AsciiString;

Visual Basic

       ' Read a dotcode

       Dim Dotcode As mVizNET.Code2DReader = New mVizNET.Code2DReader

       Dotcode.Decode(Src)

       Dim Content As String = Barcode.AsciiString

Reference:

Code2DReader, Code2DReader::Decode, Code2DReader::MaxDecoded, Code2DReader::NumDecoded, Code2DReader::Choose, Code2DReader::DetectDataMatrix, Code2DReader::DetectQR, Code2DReader::Symbology, Code2DReader::EnabledPolarities, Code2DReader::Polarity, CodePolarities::BlackOnWhite, CodePolarities::WhiteOnBlack, CodePolarities::AutoPolarity, EnabledPolarities, Code2DReader::EnabledViews, Code2DReader::View, CodeViews::Straight, CodeViews::Mirrored, CodeViews::AutoView, Code2DReader::EnabledViews, Code2DReader::AsciiString,   Code2DReader::UnicodeString, Code2DReader::StringLength, Code2DReader::SizeFrom, Code2DReader::SizeTo.


Special features: Symbology Identifier

When a symbol is decoded, the standard allows to insert a prefix before the decoded string, which will identify the symbology in question.

The possibilities are

· DataMatrix ]dm, where m is a digit in range 1-6,

· QR ]Qm, where m is a digit in range 1-6.

The digit used depends on the the ECI and FNC1 protocols (check the corresponding standards).

]d1(01)03400938990997(17)12 2012(10)B12345678-0123

(01)03400938990997(17)12 2012(10)B12345678-0123

Decoded content w/o Symbology Identifier

The presence of this prefix is controlled by the property SymbologyIdentifier.

Reference:

Code2DReader::SymbologyIdentifier.


Special features: Status Information

A few informational fields are handled by the reader in support of miscellaneous features.

· ReadFNC1: indicates that an Alternate Data Specifier has been met (FNC1 in first positions);

· ReaderProgramming: the symbol content is intended for the reader, for control purposes;

· SymbolPosition/SymbolTotal: when Structured Append is in use, it contains the position and total indexes (maximum 16). Buffered Structured Append is not supported. Note that the corresponding bytes are not prepended to the string.

· SymbolFileID1/SymbolFileID2: these are the two parts of the File Identification encoding (DataMatrix only).

· ParityData: stored checksum information (QR only).

Reference:

Code2DReader::ReadFNC1, Code2DReader::ReaderProgramming, Code2DReader::SymbolPosition, Code2DReader::SymbolTotal, Code2DReader::SymbolFileID1 and Code2DReader::SymbolFileID2.


Special features: Acceleration by Subsampling

Sometimes the acquired image has a higher resolution than is required for proper decoding. Decoding will work but can take longer than needed. As the reader uses an image pyramid, skipping the first levels makes it faster. This is appropriate for resolutions like, say 10 linear pixels per cell.

This effect is achieved by setting the property StartLevel to a higher value than the default 0 (try increasing values, every level reduces the image size by a factor 2/3).

Reference:

Code2DReader::StartLevel.


Special features: Improving the reading rate by Supersampling

When the codes are tiny (cell size below three pixels), they can be challenging to decode. An option is supplied to enlarge the image before detection, so that the chances of successful decoding are increased. Beware tha this increases the running time, of course.

This effect is achieved by setting the property StartLevel to a negative value (-1 to double, -2 to quadruple).

This case requires magnification

Reference:

Code2DReader::StartLevel.


Special features: Corner Locations

In some cases, it matters to get the exact position of the symbol, for instance to use it for guidance.

The reader returns the position by means of X, Y, Width, Height and Angle properties, assuming a rectangle shape.

The method Corner is also available to return the coordinates of the individual corners, forming a quadrilateral (the rectangle model is not enforced).

By default, the corners are computed with some uncertainty as small as a fraction of a cell. If extreme accuracy is wanted, the property AccurateEdges will enable an additional fitting of the edges to ensure optimal precision and repeatability.

Reference:

Code2DReader::X, Code2DReader::Y, Code2DReader::Width, Code2DReader::Height, Code2DReader::Angle and Code2DReader::AccurateEdges.


Advanced: GS1 Application Identifiers and MIL STD 130

The international organization GS1 uses some barcode and 2D code symbologies to encode product information in a standardized way. They define a number of Application Identifiers with a standard meaning.

E.g., when a Data Matrix code encodes the following raw content:

]d001034009496565161713050010E102

the first three characters indicate a Data Matrix code, while the following digits can be split in several fields, as follows:

GTIN (01): 03400949656516
USE BY (17): 130500
BATCH/LOT (10): E102

GS1 format, verbose (non normative)

Conventionally, the barcode content can be printed as

(01)03400949656516(17)130500(10)E102

GS1 format (normative)

The Code2DReader supply a method ExpandGS1 that turns the raw representation to the GS1 format with Application Identifiers.

The conversion is done intwo steps: as the length of the string is not known in advance, you need to query the function to determine that length, passing a null for the buffer address. Then after obtaining length information, you allocate a buffer large enough to receive the string and call the function a second time. (If you already know the string length, you can bypass the first call.)

Note that if the raw string starts with a Symbology Identifier (three characters ]cm), it will be ignored.

Similarly, the conventions in MIL-STD-130 can be used to convert raw Data Matrix content to Identifier fields (see the standard for more information). The transcoding is performed with ExpandMIL, which is used in the same way.

Currently, the formats 05 (Application Identifiers), 06 (Data Identifiers) and 12 (Text Element Identifiers) are supported. The format DD is handled like 12.

GIAI (8004): 0614141MH80312
SERIAL (21): MH80312
ADDITIONAL ID (240): F100200300400AP
INTERNAL (95): 0614141

Format 05 sample decoding, verbose

(25S) UN123456789MH80312
(30P) F100200300400AP
(12V) 123456789

Format 06 sample decoding, verbose

MFR 1U2R7
SER MH80312P

Format 12 sample decoding, verbose

Reference:

Code2DReader::ExpandGS1 and Code2DReader::ExpandMIL.


2D Code Quality Indicators

The Quality Indicators are normalized measures to assess the quality and legibility of a marking (according to the standard ISO/IEC 15415, together with ISO/IEC 16022 -Data Matrix - and ISO/IEC 18004 – QR -). They are measured on an A-B-C-D-F grade scale, A being ideal; on the opposite, an F grade is unacceptable and means that the code shouldn’t be used. The following characteristics are assessed:

- Overall Grade: this takes the worst of the lower grades, giving a global idea of the printing quality.

- Symbol Contrast: indicates how different the foreground and background intensities are. The larger the better, as noise, dirt or other degradation can modify these intensities and complicate location/decoding.

- Print Growth (Horizontal and Vertical): a measure of the relative thickness of the black/white cells, which can be adverse because of overinking/underinking or similar effects due to the marking process.

- Axial Non Uniformity: indicates if the size of the cells differs along one axis compared to the other. This is often an indication of a mismatch in marking speeds across and along the substrate.

- Grid Non Uniformity: indicates if the cells are aligned on a regular grid, with no local deformation. This is often an indication of a mechanical disturbance in the marking motion.

- Unused Error: the 2D codes have a built-in error decoding capability, enabled by redundancy in the content. The more error correction capacity is consumed, the more likely a reading failure can arise.

- Modulation: is a measure of the uniformity of the reflectance of the light and dark cells respectively. Uneven modulation can be caused by irregular ink supply.

- Reflectance Margin: is a measure of how well each cell is distinguishable as light or dark in comparison to the global threshold. Insufficient margin can be caused by irregular ink supply or lack of contrast.

- Fixed Pattern Damage: detects various anomalies in the fixed parts of the code (finder pattern). Damage in these areas can make the symbol undecodable by lack of proper geometric references. The causes can be diverse.

Two extra indicators are QR Code-specific:

- Format Information Damage: checks if the three Format fields (alongside the three finder patterns) are unaltered. Wrong format infomation makes the QR unreadable.

- Version Information Damage: checks if the two Version fields (near two of the finder patterns) are unaltered. Wrong version infomation makes the QR unreadable.

To get meaningful values for the indicators, you must enable them via the member CheckQuality before decoding. They require the PrintInspection license.

Currently the Quality Indicators are available for the DataMatrix, Quick Response and Dot Code codes. They are reported as a string in AsciiGrades/UnicodeGrades, in the order

Overall,
Symbol Contrast,
Print Growth H,
Print Growth V,
Axial NonUniformity,
Grid NonUniformity,
Unused Error,
Modulation,
Reflectance Margin,
Fixed Pattern Damage.

Format Information Damage (QR only)
Version Information Damage (QR only)

For a perfect code: A AAAAAAAAA.

Typical output

Note that the Decode Grade is implicitly an A as a symbol which cannot be decoded cannot be processed by the reader for quality check. It does not belong in the grade string.

Reference:

Code2DReader::CheckQuality, Code2DReader::AsciiGrades and Code2DReader::UnicodeGrades.


Handling Harder Cases

Sometimes the quality of the image is questionable and causes low reliability of the reading. In particular, poor contrast, high noise level/texturing, poor connectivity of the dots, very small dot size can compromise the success of reading.

In such cases, one can attempt to improve the situation by adapted preprocessing means:

- Contrast stretching: very low contrast is challenging, because the symbol will not stand out clearly from the background. One way to improve it is by using histogram equalization, which stretches the range of gray levels as much as it can.

- Deblurring: the contrast can be reinforced only on the edges of the cells, by means of the high-pass filters, such as unsharp masking. Use them sparingly anyway, as they will increase the noise level.

- Denoising: strong noise can cause false cells to be detected and perturb the location process of the codes. The denoising filters, including lowpass, median and bilateral can help reduce the amount of noise. These three filters preserve the edges increasingly better, at the expense of an increasing running time.

- Morphological erosion or dilation: in case the connectivity of the cells is poor, this can be improved by morphological processing: underinking (i.e. black cells too tiny, that don’t touch each other) is dealt with by the erosion operation, while overinking (black cells too fat) requires dilation; in both cases, choose the size of the structuring element in such a way that the black and white cells get approximately the same size.

- High-pass filtering: is useful in case of an uneven illumination, part of the field of view being much brighter that another part. The box highpass is effective in correcting this effect.

- Image enlargement: when the cells are tiny (close to 3x3 pixels or less), reading can easily fail. This is improved upon by enlarging the image by a factor 2 or more.

- Image shriking: on the opposite, very large cells should be shrunk to a smaller size; the reader has an internal reduction mechanism that will make them readable, but this can be at the expense of the running time.

Here is sample code that illustrates (non-exhaustively) how these effects can be achieved.

C++ Native

// Equalize (Operator)

       Operator::Equalize(Src, Equalized);

       // Unsharp (Kernel)

       Kernel::Unsharp(2, Src, Unsharpened);

       // Median (Morpho)

       Structel.Set(5, 5, 1);

       Structel.Median(Src, Denoised);

       // Erode (Morpho)

       Structel.Set(3, 3, 3);

       Structel.Erode(Src, Eroded0);

       // BoxHighPass (Kernel)

       Kernel::BoxHighPass(31, 31, Src, HighPassed, Rescale, 1);

       // UpSample (Geometry)

       Geometry::UpSample(1280, 960, Src, UpSampled);

       // DownSample (Geometry)

       Geometry::DownSample(160, 120, Src, DownSampled);

C++.NET using namespace mVizNET;

       // Equalize (Operator)

       mVizNET::Operator::Equalize(Src, Equalized);

       // Unsharp (Kernel)

       mVizNET::Kernel::Unsharp(2, Src, Unsharpened);

       // Median (Morpho)

       Structel->Set(5, 5, 1);

       Structel->Median(Src, Denoised);

       // Erode (Morpho)

       Structel->Set(3, 3, 3);

       Structel->Erode(Src, Eroded0);

       // BoxHighPass (Kernel)

       mVizNET::Kernel::BoxHighPass(31, 31, Src, HighPassed, mVizNET::GrayClipping::Rescale, 1);

       // UpSample (Geometry)

       mVizNET::Geometry::UpSample(1280, 960, Src, UpSampled);

       // DownSample (Geometry)

       mVizNET::Geometry::DownSample(160, 120, Src, DownSampled);

C# using mVizNET;

       // Equalize (Operator)

       mVizNET.Operator.Equalize(Src, Equalized);

       // Unsharp (Kernel)

       mVizNET.Kernel.Unsharp(2, Src, Unsharpened);

       // Median (Morpho)

       Structel.Set(5, 5, 1);

       Structel.Median(Src, Denoised);

       // Erode (Morpho)

       Structel.Set(3, 3, 3);

       Structel.Erode(Src, Eroded0);

       // BoxHighPass (Kernel)

       mVizNET.Kernel.BoxHighPass(31, 31, Src, HighPassed, mVizNET.GrayClipping.Rescale, 1);

       // UpSample (Geometry)

       mVizNET.Geometry.UpSample(1280, 960, Src, UpSampled);

       // DownSample (Geometry)

       mVizNET.Geometry.DownSample(160, 120, Src, DownSampled);

Visual Basic

       ' Equalize (Operator)

       mVizNET.Operator.Equalize(Src, Equalized)

       ' Unsharp (Kernel)

       mVizNET.Kernel.Unsharp(2, Src, Unsharpened)

       ' Median (Morpho)

       Structel.Set(5, 5, 1);

       Structel.Median(Src, Denoised)

       ' Erode (Morpho)

       Structel.Set(3, 3, 3);

       Structel.Erode(Src, Eroded0)

       ' BoxHighPass (Kernel)

       mVizNET.Kernel.BoxHighPass(31, 31, Src, HighPassed, mVizNET.GrayClipping.Rescale, 1)

       ' UpSample (Geometry)

       mVizNET.Geometry.UpSample(1280, 960, Src, UpSampled)

       ' DownSample (Geometry)

       mVizNET.Geometry.DownSample(160, 120, Src, DownSampled)


Classification

A classifier is used to recognize objects based on numerical features, such as size or average brightness, that have been computed on them, and that are compared to the same features computed on previously known samples. These features are used to tell the similarity between items, or in other words, measure a distance between them.

For instance, bolts might be distinguished by their length, diameter and/or thread pitch. In a training phase, you will enter the characteristics of various bolts and assign them a label, also called class index. After training is performed, the classifier will be able to retrieve the most likely class index for a new bolt that is shown, by comparison to the previously trained samples.

Recognizing an unknown bolt

mViz offers a classification engine via the class classifier. Two classification strategies are available: nearest-cluster based or nearest-neighbor based. The first approach works well when the cloud of points formed by the feature values are concentrated around a center and well separated. The second approach is better for clouds of arbitrary shape and more complex and/or fuzzy class borders.

Clustered data

Unclustered data

For clustered data, a new sample is assigned the class of the nearest class center. The distance is either Euclidean (isotropic) or takes into account the size or the shape of the clusters, seen as ellipsoids. The anisotropic distances are known as the normalized or the Mahalanobis metric (space around a cluster is stretched so that the ellipsoid becomes a unit sphere sphere). It is directly related to the variance/covariance matrix of the features and performs so-called data whitening.

For unclustered data, the classifier is of the so-called K-nearest-neighbor type (K is a small integer). It works by finding the k trained samples which are the closest to the query sample, and reports the class that wins a majority vote (the class with the highest count). When the classes are well separated, K=1 is fine. When the classes are closer and tend to somewhat overlap, K=3 or K=5 are better choices. (But think that if the classes overlap too much, classification becomes unreliable and you should question the feature set.)

In cases of ties (several classes getting the same count), the class with the closest distance wins. The three types of distances can be used, this time with the variances/covariances being computed globally for all classes.

The classifier is used in two steps. First you perform the training, i.e. you enter a sufficient number of representative samples, each labelled appropriately (this is called supervised training, providing ground truth information). The classifier will remember and organize them. When this has been done, recognition of new samples can take place.


A few notions

Terminology

A feature is a numerical value attached to an item. It has a type, which is a data type (integer or floating-point or other). The class (not to be confused with the meaning in OO programming) is a feature of type integer which designates an object category.

Also understand that classification features can be drawn from feature values obtained from blob analysis, but this is not the only source. Other image processing techniques lead to the extraction of features, for instance gray-level histogram statistics or gauging measurements or others.

Feature selection

The features that are relevant for a particular application are variable. They can be related to the extent of the items (area, perimeter, bounding boxes, ellipse of inertia…), to their shape (elongation, aspect ratio, ellipse axis ratio, roundness, relative convex hull area…), to the distribution of gray levels (average gray or color, deviation and other distribution coefficients). In more rare cases, the position or the orientation of the objects can matter. There is no limit to the list. mViz provides many ways to compute features, but it is eventually up to the user to make an appropriate selection.

Features need to be discriminant, i.e. be characteristic of the differences you want to stress, and be different enough between the classes. More features give more flexibility to express those differences, but require more training samples. It is often advantageous to use as little features as possible.

A typical classification case is often solved as follows:

- You prepare a sufficiently large data set labelled with ground truth (i.e. for every sample, the class is known);

- You choose numerical features and implement a procedure to compute them from the samples;

- You use one half of the samples for training, and another half for validation;

- You train the engine with the training subset;

- You measure the misclassification error with the validation subset;

- You repeat this process with different sets of features and keep the one that yields a satisfactory error score.

Classification error

There is an important thing you need to know: in many real-life applications, classification is an imperfect process and there can be an overlap between classes. That means that sometimes a sample of a given class can look more similar to a sample of another class than to one of its own class. This can be due to gross errors in the ground truth, but also inherent in the task at hand: the limits between classes can be fuzzy, or even subjective.

So be prepared to the observation of a residual classification error, i.e. never reaching zero misclassified samples when doing the cross validation test. Sometimes this can be fixed by improving the feature set, sometimes there is nothing you can do.

Data normalization and whitening

Arbitrary features can be heterogeneous and needn’t values of a similar order of magnitude. For instance, width of an object can be 200 pixels and its area 50000. With such imbalanced values, the distance functions are biaised towards the larger components. When this is the case, rescaling the values by their variance will bring them back to more comparable values.

Another unwanted phenomenon is correlation of the features: when two features are highly correlated, they will bring a similar contribution to classification, so that the “value” of information is lowered. Data decorrelation, also called whitening, will discard the correlated components and extract a more significant residue, to maximize the efficiency of the information.


Using the classifier

Classification is handled by the Classifier class. It will store the feature values in a tabular way and let you perform training and classification.

       Classifier Sort;


Classifier Training

You first create the feature entries (columns in the table) by means of the method AppendFeature, specifying a data type and an optional name. The number of stored features is available as the property NumFeatures, and you can query a feature Type or Name.

       // Add the feature columns 0:Width|1:Height|2:Type to the classifier

       Sort.AppendFeature(Int, L"Width");

       Sort.AppendFeature(Int, L"Height");

       Sort.AppendFeature(Int, L"Class");

When the column headers are set, you can add a sample descriptor, i.e. provide the set of feature values for a given item, i.e. fill out a row of the table. Use the method AppendSample, then an accessor among Bool Value, Gray Value, Gray16 Value, Rgb Value, Int Value, Float Value or Dble Value to read or write the feature value, using a feature index and a sample index. By default, the last sample row is accessed. You can repeat this at will.

              // Add a row

              Sort.AppendSample();

              // Set the feature values (obtained from blob analysis) and the class index

              Sort.Int(0)= Blob.IntFeature(I, BlobBoxWidth);

              Sort.Int(1)= Blob.IntFeature(I, BlobBoxHeight);

              Sort.Int(2)= 1;

When the feature values have been provided for all the training samples, you can perform the training, using a method among two: TrainClusters or TrainNeighbors. At this stage, the metric used for the comparisons need not be specified yet.

As the training is not required to operate on all the features (as is the case when feature selection is under study), you have to pass a “feature set” as an array containing the indexes of the relevant features.

       // Train on the width and height features (column indexes 0 and 1)

       int Set[2]= { 0, 1 };

       Sort.Train(2, Set);

Beware that the training feature set does not include the class index, as the latter is unknown for the samples to be classified. This index is specified separately.

Reference:

Classifier::NumFeatures, Classifier::Type, Classifier::Name, Classifier::Bool Value, Classifier::Gray Value, Classifier::Gray16 Value, Classifier::Rgb Value, Classifier::Int Value, Classifier::Float Value, Classifier::Dble Value, Classifier::TrainClusters and Classifier::TrainNeighbors.


Recognition of the Shape

Eventually, you perform the classification of new samples by adding their features as a new row in the table (AppendFeature and accessors), then call one of the NearestCluster or NearestNeighbor/NearestNeighbors method (with the desired parameter K). The classifier will report the index of the most frequent class among the K nearest trained samples, the index(es) of the corresponding neighbors, and the closest distance(s) to the query one.

       // Add a row for the test sample

       Sort.AppendSample();

       // Set the feature values for the test sample

       Sort.Int(0)= Blob.IntFeature(I, BlobBoxWidth);

       Sort.Int(1)= Blob.IntFeature(I, BlobBoxHeight);

       // Find the nearest neighbor(s)

       int NearestIndex;

       double Distance;

       int Type= Sort.NearestNeighbor(3, 2, NearestIndex , Distance);

Note that there are three variants of the NearestNeighbor method. One just uses the nearest neighbor rule (K=1). The second reports the K nearest neighbors and their distances, and lets the user implement his own decision process. The third one finds the K nearest neighbors and reports the winner of the majority vote.

When performing the search, the classifier can use one among the three supported distance metrics. To choose it, assign the property Mode one of StraightDistance (Euclidean), ScaledDistance (normalized), MahalanobisDistance (Mahalanobis).

Technical note. The nearest-neighbor classifier is optimized for speed using tree-search techniques, so that a large training set remains practical. Anyway the Mahalanobis distance cannot be supported in this approach, and the function SlowNearestNeighbor needs to be used instead.

Reference:

Classifier::Mode, Classifier::NearestCluster, Classifier::NearestNeighbor and Classifier::NearestNeighbors.


Validation

Cross-validation can be achieved by the classifier. First perform a training with the training samples. Then add the validation samples. Then use the method CrossValidateClusters or CrossValidateNeighbors to get the success count. The success rate is just the ratio of the success count over the number of validation samples.

Reference:

Classifier::CrossValidateClusters and Classifier::CrossValidateNeighbors.


Inspection by Image Comparison

The Comparator is a general and powerful tool to perform inspections in a simple way, based on image comparison. The principle is to show one or more defect-free sample image(s), often called a golden template, and later compare next images pixel-by-pixel in order to detect significant discrepancies in the gray-levels or colors.

Reference image with an inspected area (yellow) and don't care (red)

Image to be inspected

Result of the comparison

As fixturing is not always perfect, or can just be absent, the inspected items will have some motion freedom from picture to picture, so that realignment must be performed before comparison. If lighting is not stable, intensity correction is also possible.

The Comparator works in two phases:

- The training phase is used to show the golden template and describe the possible motion and to set variation tolerances. Training is done offline;

- The inspection phase performs the comparison and reports significant discrepancies, either graphically, as an overlay, or using the blob analyzer of mViz (Blobs object; refer to the "Blob Analysis" section). Inspection is done online.

Note that the comparison is performed by realigning the inspect image to the stored reference, rather than conversely.


Use cases

Different inspection scenarios are supported:

- The field of view contains a single object of interest, which moves little; a typical case is label inspection.

- The field of view contains several objects of interest, each at a predictable location; a typical case is inspection of multiple labels in a single go.

- The field of view contains several objects of interest, at unpredictable locations; a typical case is inspection of parts in bulk.

- The field of view contains a single object of interest, with possible 3D displacement, causing visible perspective deformation; a typical case is inspection of containers approximately facing the camera.


Training and Inspection phases

For the comparator to perform its work, a preparation phase is required. It is needed to define

- Detail(s) in the image to be used for alignment, such as - but not limited to - fiducial marks;

- Which area of the image will be inspected, with possible "don't care" exclusions;

- The golden template image itself;

- The motion allowance limits;

- The allowed pixel color variation limits.

The first step is to present the reference image, using a call to SetReference.

When the alignment and intensity correction information has been captured, the Comparator is ready to perform inspections and will automatically report the significant discrepancies with respect to the reference image.

The utility program mViz Comparator is supplied to perform these training phases and test them. You can also build your own GUI to create a model editor the way you like. The Comparator API provides the needed methods for graphical or programmatic model definition.


Aligners

An aligner is a device used for registration of the object(s) of interest, so that it can be realigned to the reference image for comparison.

Aligner comprising a template (blue) inside a search are (green)

In most common cases, a single aligner is needed, whether there is one or more instance of the objects to be inspected. In more advanced cases, several aligners may be required. (This is specified during the call to SetReference; read the section "Advanced: Multiple Aligners" for more information).

An aligner comprises

- A reference template that is used for template matching; the template could be a fiducial mark, an arbitrary (but unique) detail on the part, or even a large area of the reference;

- A searching area that delimits where the template will be looked for, and implicitly describes the motion allowance.

In common cases, the parts under scrutiny are well fixtured, so that only (short) translation needs to be corrected. In other cases, slight rotation or change of magnification are possible. In yet other, free motion is allowed. The Comparator supports all these situations.

To place an aligner programmatically, use one of AlignerTrainROI or AlignerSearchROI. You can also adjust by graphical interaction using the methods HitROI to activate handles and DragROI to move an activated handle. Drawing of the handles is made via DrawROI.

Reference:

Comparator::SetReference, Comparator::AlignerTrainROI, Comparator::AlignerSearchROI, Comparator::HitROI, Comparator::DragROI and Comparator::DrawROI.


Inspected area

Independently of the aligners, you specify a so called "detector", that defines which area of the image will be inspected by comparison.

Detector area (yellow) before and after alignment

You also specify tolerances to cope with the unavoidable variations between the successive samples which are always present but acceptable. The tolerances can be set in two ways:

- From a single reference image, by adjusting a geometric margin that allow features to be slightly larger or thinner than expected, and a radiometric margin that allows features to be slightly lighter or darker than expected. Both parameters also deal with noise, be it in the shape or in the colors. The is done with the method StraightTolerancing.

- From several reference images, by a statistical process. When you show several reference images, all registered by means of aligners, the Comparator will use the statistical distribution of the individual pixel values to define acceptance ranges, pixel by pixel. This way, you get the most accurate tolerancing, based on real data. Read the section "Advanced: Statistical Tolerancing" for more information.

Reference

Upper and lower tolerance with geometric margin

Upper and lower tolerance with grayscale margin

To adjust a detector programmatically, use DetectorROI. You can also adjust by graphical interaction using the methods HitROI to activate handles and DragROI to move an activated handle. Drawing of the handles is made via DrawROI.

Reference:

Comparator::StraightTolerancing, Comparator::DetectorROI, Comparator::AlignerSearchROI, Comparator::HitROI, Comparator::DragROI and Comparator::DrawROI.


Inspection Results

The inspection results can be one of

- Purely visual feedback, with the image being annotated with gray-levels/colors where discrepancies are detected;

- Global assessment of image dissimilarity, such as the count of significantly different pixels, or the average value of those discrepancies;

- Connected components analysis performed on the discrepancies. The full range of blob tools is then available.


Usable Area and Overrun

Usually, the reference image and inspected image are not perfectly aligned with respect to each other and this is why realignment is necessary. For this reason, not all pixels can be compared. The Comparator allows you to deal with this in two ways:

  1. Avoid situations such that the inspected area overruns. The Comparator will warn you if overrun occurs. If needed, you can reduce the inspected area to avoid overrun.
  2. Accept such situations and only inspect where possible. The Comparator will warn you anyway that overrun occurred.

It is important to understand that there is a relation between the degrees of freedom of the template location for realignment, and the usable area for inspection.

Train – Search - Inspect
The translational play limits the inspected area

Train – Search - Inspect
The rotation or scaling further limits

This limitation implies that the motion range should be as tight as possible to allow a large inspection area.

For given translation/rotation/scaling allowances, the Comparator can tell you the maximum possible inspected area, such that it will never overrun the image.

Alternatively, you can let the Comparator perform defect detection only for the pixels that fall inside the inspected image, leaving dead zones (in red).

Train – Search - Inspect
Truncated inspection

Note that if the inspected area has the size of the whole image, overrun unavoidably occurs.


Usage

In the first place, you pass the reference image to the Comparator object using the SetReference method. This will predefine a Train region, a Search region and an Inspect region, with default sizes. From there, you are free to modify the limits of these regions using AlignerTrainROI, AlignerSearchROI or DetectorROI.

You can as well implement interactive adjustment with the mouse using the DrawROI method for graphical output with optional handles, HitROI to detect the cursor over a handle, and DragROI to move a handle, as is done with other mViz Objects.

Note: for convenience, the Drag method applied to a Train ROI automatically adjusts the Search ROI as well, taking into account the specified search range parameters, as supplied with AlignerSearchRange. On the opposite, adjusting the Search ROI does not affect the Train ROI.

Reference:

Comparator::SetReference, Comparator::AlignerTrainROI, Comparator::AlignerSearchROI, Comparator::DetectorROI, Comparator::DrawROI , Comparator::HitROI, Comparator::DragROI:: and Comparator::AlignerSearchRange.


Simple Alignment

The most basic way to use the Comparator is to look at a single part at a time, with no rotation nor scaling. You need a single aligner.

//
Show the reference
Cmp.SetReference(Src);

// Adjust the search range (±20 pixels horizontal, ±5 vertical)
Cmp.AlignerSearchRange(false, -20, 20, -5, 5);

// Adjust the Train area (or use graphical interaction); Search
area follows
Cmp.AlignerTrainROI(Limit(…));

// Adjust the Inspect region (or use graphical interaction)
Cmp.AlignerInspectROI(Limit(…));

// Perform the template training
Cmp.TrainAligners();

// Create the tolerance images
Cmp.StraightTolerancing(Src, 20, 2);

After these steps, the reference model is ready. Inspection is performed with the following calls:

//
Perform the alignment; Dst is the realigned image
Limits
ROI;
Cmp.Align(Src, Dst);

// Generate a difference image
Cmp.Differences(Dst, Diff);

If you want to normalize the image intensities before comparison, set the Normalize flag before calling Differences.

// Activate normalization of the intensities
Cmp.Normalize= true;

// Perform the alignment; Dst is the realigned, normalized image
Cmp.Align(Src, Dst);

// Generate a difference image
Cmp.Differences(Dst, Dif);


Simple Alignment with Resampling

As already said, if rotation and/or scaling is allowed, before comparison is possible, image resampling is done to compute the pixels of the inspected image that face those of the reference. Resampling is done with bilinear interpolation.

Regarding the training of the reference, only one thing changes: you specify an angle or scale range. Note that rotation and magnification do enlarge the required search space. When you rely on automatic adjustment of the search area, this is taken into account. But you are still free to specify your own search area.

// Adjust the search range (±20 pixels horizontal, ±5 vertical, ±9 degrees)
Cmp.AlignerSearchRange(false, -20, 20, -5, 5, -9, 9);

The rest of the processing is the same:

//
Perform the alignment; Dst is the realigned image
Limits
ROI;
Cmp.Align(Src, Dst);

// Generate a difference image
Cmp.Differences(Dst, Diff);

In case you would know, which parts of the image were effectively compared (so excluding the dead zones and don't care areas), the member Clip is a Region object that describes them.

Reference:

Comparator::AlignerSearchRange, Comparator::Align, Comparator::Differences and Comparator::Clip.


Advanced: Multiple Aligners

When you look at several identical parts at a time, there are yet two different situations:

- The parts are laid randomly, at arbitrary positions and rotations. In this case, the search area is large, possibly causing significant search time.

- The arts are laid in a regular layout, or at predictable locations. In this case, several search areas can be placed around the predicted locations, to reduce the search time and improve reliability.

- When the inspected parts are not perfectly facing the camera, some perspective effect can be noticeable. The Comparator is able to cope by combining several aligners (each with its own template and search area). There are two benefits: the search time is reduced by having small regions, and perspective deformation can be compensated.


Advanced: Statistical Tolerancing

Instead of setting the tolerancing parameters explicitly with the function StraightTolerancing, you can use a statistics-based approach. After supplying the Reference image, you will show an arbitrary number of additional images that are default-free. The Comparator will record for every pixel in the reference the variations seen across those images. From these "normal" variations, lower and upper tolerances can be chosen following one of two rules:

- The minmax rule considers the interval formed by the minimal and maximal gray values observed during statistical training. The width of the range can also be enlarged or shrunk to make the comparison looser or stricter.

- The normal rule considers the arithmetic average plus or minus one standard deviation. This range can also be adjusted by choosing a different multiple of sigma. In case of a normal distribution, choosing a 3-sigma range (respectively 2) is known to correspond to random drawings falling in this range in 99.73% (resp. 95.45%) of the cases.

To perform statistical tolerancing, use the following sequence of operations:

- StartTolerancing once; you have the option of choosing the minmax or normal rule;

- NextTolerancing for every image;

- EndTolerancing once; you have the option to select the scale factor of the interval.

Beware that for successful statistical tolerancing, you should supply enough images to feed a sufficient and representative sample of the distribution. Also avoid to train on images with defects, otherwise similar defects will later fail to be detected.

Reference:

Comparator::StraightTolerancing, Comparator::StartTolerancing, Comparator::NextTolerancing and Comparator::EndTolerancing.


Shape Inspection with Snakes

A SnakeGauge is a flexible shape used to process elongated and annular objects such as pipes, joints, cables, glue traces… It can be used for inspection tasks such as linearity check, circularity check, width control, absence/presence and so on.

A snake has a symmetry axis that can be composed of sections of different types

- line segments (straight sections),

- circular arcs (circular sections),

- spline curves (smoooth tree-form sections).

Possible sections of a snake (segment, arc, spline)

These elements are positioned by means of points through which they pass. Any combination of sections is possible. Snakes can be open or closed.

Note that a SnakeGauge class derives from Snake, a base class that gives minimum support for the representation of the snake shape. Hence it inherits some of its methods.

Snake made of two circular and two linear sections

A snake can be created by program, using one of the available Append functions, or interactively using the mouse, in the utility program mViz Snake. A number of edition functions are available if you want to write your own editor.

Reference:

SnakeGauge, Snake and Snake::Append.


Checking linearity and circularity

When a snake contains straight or circular sections it can be used for straightness or circularity assessement. You will place the snake over the edges to be inspected, and the snake will adjust a best fit line or arc over it. Then deviations from the ideal line will be measured and reported.

The available measurements are

- The absolute deviation,

- The standard (root-mean-square) deviation,

- The percentage of out-of-tolerance values both intrusions[1] and protrusions[2].

These measurements can be obtained section by section, or for the whole snake. You invoke the method InspectEdge with the argument Fit set to true if you want to adjust the snake over the edge and false if you want to keep the default position. After inspection, the methods Deviation (and associated RMS option), Intrusions and Protrusions. The latter two statstics are given as the proportion of the points deviating more than MaxDeviation from the snake axis, inward or outward.

You can also get a graphical display of where the points are out of tolerance.

Deviation statistics, per section and global

Reference:

SnakeGauge::InspectEdge, SnakeGauge::Deviation, SnakeGauge::RMS, SnakeGauge::Intrusions, SnakeGauge::Protrusions and SnakeGauge::MaxDeviation.

[1] Lack of matter compared to the nominal shape

[2] Excess of matter compared to the nominal shape


Checking Width

The available measurements are

- The absolute deviation from the nominal width,

- The standard (RMS) deviation from the nominal width,

- The percentage of out-of-tolerance values both intrusions[1] and protrusions[2].

These measurements can be obtained section by section, or for the whole snake. You invoke the method InspectRibbon with the argument Fit set to true if you want to adjust the snake over the edge and false if you want to keep the default position. After inspection, the methods Deviation (and associated RMS option), Intrusions and Protrusions. The latter two statistics are given as the proportion of the points deviating more than MaxDeviation from the NominalWidth, by default or in excess.

You can also get a graphical display of where the points are out of tolerance.

Reference:

SnakeGauge::InspectRibbon, SnakeGauge::Deviation, SnakeGauge::RMS, SnakeGauge::Intrusions, SnakeGauge::Protrusions, SnakeGauge::NominalWidth and SnakeGauge::MaxDeviation.

[1] Lack of matter compared to the nominal shape

[2] Excess of matter compared to the nominal shape


Fitting

Before inspection, it can arise that the part to be inspected has suffered local deformation so that a rigid model might not be sufficient to match the true situation. The methods InspectEdge and InspectRibbon take the boolean parameter Fit which triggers a best fit (linear or circular) on the detected edge points. This fitted element will be the one used for deviation measurement.

To get the characteristics of these fitted elements, per section, the methods SectionSegment and SectionArc are available. In the case of a ribbon, the midpoints of the edges are used for fitting.

Edge Fitting

Reference:

SnakeGauge::SectionSegment and SnakeGauge::SectionArc.


Edge Parameters and Edge Selection

Edge points are detected along profiles that are perpendicular to the snake axis. They are relatively large variations in the gray-levels, corresponding to strong changes in color (brightness) or light intensity (shadow or glare). The difference between the lowest intensity and highest intensity is called the Step; it is a value in the gray range, [0..255]. The higher the value, the more contrasted the edge. The number of pixels between the low and high intensities is called the Span; it ranges from 1 to a few units. The ratio of the Step over the Span is called the Slope; the higher the value, the sharper the edge.

An edge can be Raising (from dark to light) or Falling (from light to dark). This quality is called the Polarity. Note that regardles the Polarity, Step and Slope are positive numbers. The Raising and Falling values can be compbined as the Both constant.

These parameters are used to specify an edge selection rule, that helps deal with cases with several edges crossed by the profiles, and stay away from noise. The following policies are available, via the parameter Selection, and tell which edge should be used when several are found:

- Zero or positive number selects the nth edge from the beginning of the profile,

- A negative number selects the nth edge from the end of the profile,

- The value BestStep selects the edge with the highest step (best contrast),

- The value BestSlope selects the edge with the largest slope (best sharpness),

- The value BestSpan selects the edge with the shortest span.

The edges are selected among the detected edges that have a sufficient Step (>MinimumStep), Slope (>MinimumSlope) and limited Span (<MaximumSpan).

By default, the edge with the best step and any polarity is selected, and this is usually a suitable rule.

Reference:

Polarities::Raising, Polarities::Falling, Polarities::Both, SnakeGauge::Selection, SnakeGauge::MinimumStep, SnakeGauge::MinimumSlope and SnakeGauge::MaximumSpan.


Estimating the Edge Parameters

As said, the work of the snake gauge is based on edge detection along profiles transverse to the axis and selection of the relevant edge based on strength and polarity. To ease the task of adjusting these parameters, the assessment mode gives you statistical information about the edges under study. Specifically, it gives you the quantile values for a given risk level, as is done in statistics. (I.e. the value of the parameter that is not exceeded in a given percentage of the cases.)

Edge points statistics

To use the assessment functions, place a snake so that its axis covers the edge(s) to be studied and run the method AssessEdges, passing it the desired Fraction of the measurements (passing 1 [100%] will give you the largest of all measurements; a smaller fraction will avoid possible outliers). The method will return suitable threshods for the MinimumStep, MinimumSlope and MaximumSpan parameters, as well as the number of edges of both polarities.

Reference:

SnakeGauge::AssessEdges, SnakeGauge::Fraction, SnakeGauge::MinimumStep, SnakeGauge::MinimumSlope, and SnakeGauge::MaximumSpan.


Realigning the Snake

By default, the snake remains at the same position between inspections. But it is often the case that the items to be inspected move from one picture to the next. The Locator tool can be used to measure the displacements from a reference pose (at trainin-time). Other means, such as what the Geometry tool supports, can be used to establish a geometric transformation.

In order to realign the snake to the image, two methods Register are supplied. The first takes a Locator object as input and will realign on the desired matched instance of the template. The second takes a Geometry object. When Register has been called, the whole snake is displaced, following rigid motion. To revert to the original pose, use the third Register method, that takes no argument.

Reference:

Locator, Geometry and Snake::Register.


Summary: Working with a Snake

The normal procedure to use a snake for a shape or width verification is to:

- Edit a snake model by drawing over an existing image; you will select the successive section types and use mViz Snake or your own editor for this task.

- If necessary, try the edge assessment function to get an idea of the appropriate edge parameter settings.

- Adjust the edge detection thresholds and choose the edge detection method.

- Set the allowed deviation tolerance and possibly the nominal width (ribbon inspection).

- Optionally save to a file for later reuse.

This can be seen as a setup phase, done once for all. Next comes the proper inspection phase, to be done repeatedly.

- If needed, use template matching or equivalent techniques and realign the snake onto the image.

- Perform the edge or ribbon inspection on your images

- Collect the statistical results and make decision.


Advanced: Writing a Snake Editor

Snakes can be created and edited programmatically or interactively. mViz supplies the interaction functions required to interact with a GUI, like in the ready-made utility mViz Snake.

Snakes are made of successive Sections, which can be of three types: a line segment, a circular arc or a smooth spline. The sections are joined (the ending point of a section is the starting point of the next) and are defined by a number of Vertices:

- two for a line segment: the two endpoints;

- three for a circular arc: two endpoints and a third intermediate point;

- three or more for a spline curve: two endpoints and as many intermediate points as you want.

The methods involved by programmatic creation are

void SegmentAppend (const XY& P, const XY& Q): add two vertices defining a line segment;

void ArcAppend (const XY& P, const XY& Q, const XY& R): add three vertices defining a circular arc);

void SplineAppend (const XY P[], int N): add N vertices defining a spline arc;

void CircleAppend (const XY& P, const XY& Q, const XY& R): add a single circle (to an empty snake only);

void Append (const XY P, SectionType Type): add one vertex at a time (advanced use).

Note that when the Snake is not empty, its last vertex and the first vertex of the appended section are merged to a single point.

The methods involved by edition are

void ClosestTo (XY Cursor): selection of vertex or line between two vertexes, by proximity to the mouse cursor;

SectionType& HitType (): telling the kind of vertex that was hit.

void Drag (XY Cursor): moving a vertex;

bool Insert (XY Cursor, SectionType Type, bool CheckOnly= false): insertion of a new vertex along a selected edge edge;

bool Delete (bool CheckOnly= false): deletion of a selected vertex;

bool Retype (SectionType Type, bool CheckOnly= false): changing the type of a selected vertex, if possible.

For the graphical representation, the following functions are relevant:

     void Draw (bool Axis= true, bool Handles= true, bool BreadthHandles= false): snake axis (optional), snake sides and dragging handles (optional).

     void DrawEdge (bool Profiles= false, bool Crosses= false): detected edges (after edge inspection)

     void DrawRibbon (bool Profiles= false, bool Crosses= false): detected edges (after ribbon inspection)

     void DrawFit (): fitted modesl (after inspection with fit)

Reference:

Snake::SegmentAppend , Snake::ArcAppend , Snake::SplineAppend , Snake::CircleAppend, Snake::Append, SnakeGauge::ClosestTo, Snake::HitType, SnakeGauge::Drag, Snake::Insert, Snake::Delete and Snake::Retype.

SnakeGauge::Draw , SnakeGauge::DrawEdge , SnakeGauge::DrawRibbon and SnakeGauge::DrawFit .


3D Inspection

The 3D inspection module allows you to process 3D point clouds and meshes in order to check shapes by comparison to a reference. The process involves a training step, where a representative sample of the objects to inspect is presented and learnt by the system. Next, when other objects are shown, the reference is geometrically aligned to them (there can be one or more instances), and local comparisons are made to detect discrepancies in the shape.

Typical applications are pose verification for correct assembly, bin picking for robot guidance and shape conformity check for defect detection.

The main steps of processing are:

  1. Show a sample the object to be used as the template;
  2. Get the point cloud of the object(s) to be inspected;
  3. Find the instance(s) of the object;
  4. Check the position(s) to detect mis-placement or guide a robot, and/or
  5. Compare the shapes to detect anomalies.

The input data can consist of a point cloud acquired by a 3D device such as a laser profiler, a structured light projector, a 3D Lidar… or a range image, as acquired with a time-of-flight camera, computed from a stereoscopic system, from a tomographic imager…

Note. The 3D module does not deal with the extraction of 3D data from special sensors or by stereoscopy, it works from existing point clouds or range images. It does not assume any specific acquisition technology. Unstructured points clouds as well as range images are supported.


Clouds and Meshes

A point cloud is a raw set of independent 3D points in no particular order. It is assumed to belong to one or more surfaces of objects. A point cloud can be delivered by a 3D image acquisition device, or extracted from an STL file, or from a range image (by considering the gray-levels as altitudes).

Point cloud vs. point mesh

A point mesh is composed of a points cloud and a set of triangular faces having those points as vertices. The triangles may form a closed, watertight surface, but this is not mandated. The mesh can be supplied by the acquisition device, by an STL file, or be obtained by automatic triangulation of an existing point cloud.

3D inspection can be performed either with a point cloud or with a point mesh. A point mesh is visually more pleasing when rendered, and some measurements (surface, volume) require a mesh. A mesh is distinguished from a cloud by the property NumFaces being positive or zero.

Clouds and meshes are both represented by the class PointCloud. When a cloud is used as a template, it is handled by a CloudInspector object. A CloudInspector derives from a PointCloud, so it is also a cloud.

Reference:

PointCloud, CloudInspector and PointCloud::NumFaces.


Loading a Point Cloud

Point clouds and meshes are delivered by some acquisition device and there is no real standardization in that matter. You will need to interface to your device and obtain the points it delivers. Use the method AppendPoint to feed the points one by one. Floating-point values are expected and grouped as a fXYZ struct. As the point clouds are unstructured, no particular order is assumed.

To input a mesh, you need to supply all triples of points corresponding to a face. CAUTION: the numbering of the face vertices must match the order in which you fed the points. It is allowed and advisable to specify only once a vertex common to several faces. The 3D module only supports triangular faces; if yours are larger polygons, triangulate them first.

C++ Native

       // Add points from the external device

       Msh.AppendPoint(fXYZ(X0, Y0, Z0));

       Msh.AppendPoint(fXYZ(X1, Y1, Z1));

       Msh.AppendPoint(fXYZ(X2, Y2, Z2));

       Msh.AppendPoint(fXYZ(X3, Y3, Z4));

       ...

       // Add faces

       Msh.AppendFace(0, 2, 3);

       Msh.AppendFace(1, 3, 4));

       ...

C++.NET using namespace mVizNET;

       // Add points from the external device

       Msh.AppendPoint(fXYZ(X0, Y0, Z0));

       Msh.AppendPoint(fXYZ(X1, Y1, Z1));

       Msh.AppendPoint(fXYZ(X2, Y2, Z2));

       Msh.AppendPoint(fXYZ(X3, Y3, Z4));

       ...

       // Add faces

       Msh.AppendFace(0, 2, 3);

       Msh.AppendFace(1, 3, 4));

       ...

C# using mVizNET;

       // Add points from the external device

       Msh.AppendPoint(new fXYZ(X0, Y0, Z0));

       Msh.AppendPoint(new fXYZ(X1, Y1, Z1));

       Msh.AppendPoint(new fXYZ(X2, Y2, Z2));

       Msh.AppendPoint(new fXYZ(X3, Y3, Z4));

       ...

       // Add faces

       Msh.AppendFace(0, 2, 3);

       Msh.AppendFace(1, 3, 4);

       ...

Visual Basic

       ' Add points from the external device

       Msh.AppendPoint(New mVizNET.fXYZ(X0, Y0, Z0))

       Msh.AppendPoint(New mVizNET.fXYZ(X1, Y1, Z1))

       Msh.AppendPoint(New mVizNET.fXYZ(X2, Y2, Z2))

       Msh.AppendPoint(New mVizNET.fXYZ(X3, Y3, Z4))

       ...

       ' Add faces

       Msh.AppendFace(0, 2, 3)

       Msh.AppendFace(1, 3, 4)

       ...

A point cloud can also be retrieved from a file. Currently the STL format is supported. Use one of Read or ReadCloud. The parameter PointsOnly lets you opt to load just the points, to obtain a cloud, or both the vertices and the faces.

C++ Native

        // Load the template image and bound it

        dXYZ TemCenter, TemSize, MshCenter, MshSize;

        Tem.ReadCloud("Images\\3D\\Tem.stl");

        Tem.MinMax(TemCenter, TemSize);

        // Load the inspected image and bound it

        Msh.Read("D:\\STL\\Msh.stl");

        Msh.MinMax(MshCenter, MshSize);

C++.NET using namespace mVizNET;

        // Load the template image and bound it

        dXYZ TemCenter, TemSize, MshCenter, MshSize;

        Template->ReadCloud("Images\\3D\\Tem.stl", false);

        Template->MinMax(TemCenter, TemSize);

        // Load the inspected image and bound it

        Mesh->Read("Images\\3D\\Msh.stl", false);

        Mesh->MinMax(MshCenter, MshSize);

C# using mVizNET;

        // Load the template image and bound it

        dXYZ TemCenter, TemSize, MshCenter, MshSize;

        Template.ReadCloud("Images\\3D\\Tem.stl", false);

        Template.MinMax(ref TemCenter, ref TemSize);

        // Load the inspected image and bound it

        Mesh.Read("Images\\3D\\Msh.stl", false);

        Mesh.MinMax(ref MshCenter, ref MshSize);

Visual Basic

        ' Load the template image and bound it

        Dim TemCenter, TemSize, MshCenter, MshSize As mVizNET.dXYZ

        Template.ReadCloud("Images\\3D\\Tem.stl", False)

        Template.MinMax(TemCenter, TemSize)

        ' Load the inspected image and bound it

        Mesh.Read("Images\\3D\\Mesh.stl", False)

        Mesh.MinMax(MeshCenter, MeshSize)

Notes:

  1. A cloud without faces cannot be saved back to an STL file. This is an inherent limitation of the STL format.
  2. A CloudInspector context can be saved to a file and later reloaded with the methods Read and Write. (Do not confuse with ReadCloud/WriteCloud.)

Reference:

PointCloud::AppendPoint, fXYZ, PointCloud::Read, CloudInspector::ReadCloud and CloudInspector::WriteCloud.


Cloud Registration

Registration is the process of moving the template cloud to match the inspected cloud as closely as possible, using a rigid transformation (translation and rotation). There are two options:

- Near registration is used when the reference and inspected clouds are known to be in a similar pose, so that the translation and rotation have small amplitude. Near registration is implemented as the method Match.

- Far registration is used when the poses are unrelated, or when there are several instances of the object to be matched. This includes cloud merging, multiple instance detection and pick & place applications. The corresponding method is Find.

In both cases, the matching can be partial, when only different parts of the surfaces are available – provided there is a significant overlap, or lacunary, when there are local discrepancies between the two surfaces (manufacturing defects). The matching can be made robust, meaning that surface anomalies will not impede correct alignment of the surfaces.

The code below performs near registration, then moves the subject mesh to bring it in the same position as the template using the function Move. (This is for the sake of illustration, it is not required to realign for other operations such as comparison.)

C++ Native

       // Match the template to the subject, then align the subject

       Template.Match(Mesh);

       Mesh.Move(Template.Location().XForm, false);

C++.NET using namespace mVizNET;

       // Match the template to the subject, then align the subject

       Template->Match(Mesh);

       array<dXYZ>^ XForm= gcnew array<dXYZ> { Template->Location(0).XFormX, Template->Location(0).XFormY, Template->Location(0).XFormZ, Template->Location(0).XForm };

       Mesh->Move(XForm, false);

C# using mVizNET;

       // Match the template to the subject, then align the subject

       Template.Match(Mesh);

       dXYZ[] XForm= new dXYZ[] {
Template.Location(0).XFormX, Template.Location(0).XFormY,
Template.Location(0).XFormZ, Template.Location(0).XForm };

       Mesh.Move(XForm, false);

Visual Basic

       ' Match the template to the subject, then align the subject

       Template.Match(Mesh)

       Dim XForm As mVizNET.dXYZ() = New
mVizNET.dXYZ(3) { Template.Location(0).XFormX, Template.Location(0).XFormY,
Template.Location(0).XFormZ, Template.Location(0).XForm}

       Mesh.Move(XForm, False)

Reference:

CloudInspector::Match, CloudInspector::Find and CloudInspector::Move D:\Documents\mViz\mViz Help\Reference\PointCloud.Read.htm - PointCloud.Read.


Robust Cloud Registration

By default, all points of the template and subject are taken to perform the alignment. Anyway, partial matches, in case of partial overlap or in case of geometric differences, require to use only a subset of the points for the matching. This is governed by the parameter Inliers, representing the fraction of the points that are effectively used (best points). The default value is 1 (100%), and smaller values represent the fraction that is used. Values lower than 0.5 (50%) are not recommended as alignment can become imprecise.


Object Measurement

After searching, the position of the template is given as a rotation matrix and a translation vector with respect to pose of the trained template.

Global measurements of the objects, such as overall dimensions, surface and volume (in case of closed surfaces) can be obtained. Among them, Area, Volume, MinMax (bounding box), Centroid, Ellipsoid, Length (in a specified direction).

The feature area requires a mesh. If needed you can resort to automatic triangulation with Triangulate. The feature volume requires a watertight mesh. The centroid and ellipsoid assume points of equal weights.

Reference:

PointCloud::Area, PointCloud::Volume, PointCloud::MinMax, PointCloud::Centroid, PointCloud::Ellipsoid, PointCloud::Length and PointCloud::Triangulate D:\Documents\mViz\mViz Help\Reference\PointCloud.Read.htm - PointCloud.Read.


Cloud Comparison

After registration, local distances between the inspected cloud and the reference are evaluated. One can get statistics about them and observe graphically where they occur, based on a user-supplied comparison tolerance. Use the method Compare to observe the discrepancies between the template and the inspected object. You pass the compare function the pose information obtained by registration.

After comparison, the points and/or faces are set to a selected state when they exceed a distance threshold, for defect detection.

Compared template and subject

Reference:

CloudInspector::Compare D:\Documents\mViz\mViz Help\Reference\PointCloud.Read.htm - PointCloud.Read.


Cloud Drawing

A point cloud is drawn a independent points. This is sufficient when the points are dense.

A point mesh is drawn with filled faces, flat shading and hidden parts removal. Optionally, only the edges are drawn, to show a wireframe.

The color of the surface is specified via the property FillColor.

Drawing is done in two steps:

  1. Use a temporary Rgb image of the size you like, and render the cloud using Draw. To render the mesh, also use a temporary image used for Z-buffering.

You can render several clouds to the same image, by acting on the Reset parameter.

  2. Draw the image to the desired window using the usual Draw method.

You can draw the selected and unselected points separately, for instance to implement a color code.

The code below shows how to compare two clouds, the to render the mesh in green (valid points) and red (out-of-tolerance). The drawing of the image is omitted.

C++ Native

// Perform the search and comparison

       Tem.Match(Msh);

       Tem.Compare(Msh, 0.1 * double(trackBar1->Value), 0, true, true);

       // Draw the template surface to an image, using a Z-buffer, in green and red

       mViz::Image D, Dz;

       D.Set(temPanel->Width, temPanel->Height, Rgb);

       Graph::FillColor = Green;

       Msh.Draw(AngleY, AngleX, TemCenter, Zoom * 0.5 * mViz::Site::Norm(D.Size()) / MshSize.Norm(), D, Dz, true, AllSelected);

       Graph::FillColor = Red;

       Msh.Draw(AngleY, AngleX, TemCenter, Zoom * 0.5 * mViz::Site::Norm(D.Size()) / MshSize.Norm(), D, Dz, false, AllDeselected);

C++.NET using namespace mVizNET;

       // Perform the search and comparison

       Tem->Match(Msh);

       Tem->Compare(Msh, 0.1 * double(trackBar1->Value), 0, true, true);

       // Draw the template surface to an image, using a Z-buffer, in green and red

       mVizNET::Image^ D, ^ Dz;

       D = gcnew mVizNET::Image(); Dz = gcnew mVizNET::Image();

       D->Set(temPanel->Width, temPanel->Height, PixelTypes::Rgb, IntPtr(0), 0, 0);

       mVizNET::Graph::FillColor = PredefinedColors::Green;

       Msh->Draw(AngleY, AngleX, TemCenter, Zoom * 0.5 * mVizNET::Site::Norm(D->Size) / MshSize.Norm(), D, Dz, true, mVizNET::BlobSelection::AllSelected, MshSize, false);

       mVizNET::Graph::FillColor = PredefinedColors::Red;

       Msh->Draw(AngleY, AngleX, TemCenter, Zoom * 0.5 * mVizNET::Site::Norm(D->Size) / MshSize.Norm(), D, Dz, false, mVizNET::BlobSelection::AllDeselected, MshSize, false);

C# using mVizNET;

       // Perform the search and comparison

       Tem.Match(Msh);

       Tem.Compare(Msh, 0.1 * (double)trackBar1.Value, 0, true, true);

       // Draw the template surface to an image, using a Z-buffer, in green and red

       mVizNET.Image D,  Dz;

       D = new mVizNET.Image(); Dz = new mVizNET.Image();

       D.Set(temPanel.Width, temPanel.Height, PixelTypes.Rgb, (IntPtr)0, 0, 0);

       mVizNET.Graph.FillColor = PredefinedColors.Green;

       Msh.Draw(AngleY, AngleX, TemCenter, Zoom * 0.5 * mVizNET.Site.Norm(D.Size) / MshSize.Norm(), D, Dz, true, mVizNET.BlobSelection.AllSelected, MshSize, false);

       mVizNET.Graph.FillColor = PredefinedColors.Red;

       Msh.Draw(AngleY, AngleX, TemCenter, Zoom * 0.5 * mVizNET.Site.Norm(D.Size) / MshSize.Norm(), D, Dz, false, mVizNET.BlobSelection.AllDeselected, MshSize, false);

Visual Basic

       ' mViz: match the template to the subject, then align the subject

       Tem.Match(Msh)

       Dim XForm As mVizNET.dXYZ() = New
mVizNET.dXYZ(3) {Tem.Location(0).XFormX, Tem.Location(0).XFormY,
Tem.Location(0).XFormZ, Tem.Location(0).XForm}

       Msh.Move(XForm, False)

       ' Draw the template surface to an image, using a Z-buffer, in green and red

       Dim D, Dz As mVizNET.Image

       D = New mVizNET.Image()

       Dz = New mVizNET.Image()

       D.Set(mshPanel.Width, mshPanel.Height, mVizNET.PixelTypes.Rgb, 0, 0, 0)

       mVizNET.Graph.FillColor = mVizNET.PredefinedColors.Green

       Msh.Draw(AngleY, AngleX, MshCenter, Zoom * 0.5 * mVizNET.Site.Norm(D.Size) / MshSize.Norm(), D, Dz, True, mVizNET.BlobSelection.AllSelected, MshSize, False)

       mVizNET.Graph.FillColor = mVizNET.PredefinedColors.Red

       Msh.Draw(AngleY, AngleX, MshCenter, Zoom * 0.5 * mVizNET.Site.Norm(D.Size) / MshSize.Norm(), D, Dz, False, mVizNET.BlobSelection.AllDeselected, MshSize, False)

Reference:

PointCloud::Draw D:\Documents\mViz\mViz Help\Reference\PointCloud.Read.htm - PointCloud.Read.


Advanced: Search Policies

The behavior of the method Match is governed by the Policy parameter. The following modes are available:

- PlanarSearch: in this mode, only the upper layer of the searched cloud is visited; this is suitable for the pick & place applications;

- VolumeSearch: the whole volume is explored; this is suitable for parts counting, among others; anyway, the search time will be higher;

- OverlapSearch: placement of the template with a partial overlap to the search cloud are tried; this is suitable for merging applications;

- RandomSearch: reserved for special applications.


Advanced: Cloud Edition

Before processing, and in particular in order to train the template shapes, it can be useful to clean up the model to remove outlier points. Cloud edition allows to remove unwanted parts of the cloud by graphical interaction (lasso function). This is obtained with ByPathSelect, using a user-defined Path.

Part removal with a lasso

Using registration, several point clouds can be merged in a single one to reconstruct larger surfaces from several independent scans. This can be achieved using alignment of the mesh by Move, then merging with the template, with AppendMesh.

Reference:

PointCloud::AppendMesh D:\Documents\mViz\mViz Help\Reference\PointCloud.Read.htm - PointCloud.Read and PointCloud::ByPathSelect.


Advanced: Cloud Meshing

As said, depending on the technology, 3D scans can be available as unstructured point clouds or as meshed surfaces. The 3D module does not require that the 3D data be represented as meshed surfaces, and can work on both. Anyway, for cosmetic purposes, automatic meshing from a given cloud is possible. Use Triangulate.

Reference:

PointCloud::Triangulate D:\Documents\mViz\mViz Help\Reference\PointCloud.Read.htm - PointCloud.Read.


Graphics

mViz includes numerous methods (Draw and Plot) for built-in graphics associated to the available processing classes. See the corresponding class documentation.

mViz also provides many graphical primitives for general purpose and supports a few graphical attributes, via the class Graph.


Drawing primitives

Dot: a single pixel or a small circle to denote a location

Cross: a small cross to denote a location

Line: a line segment, possibly with arrowheads

Arc: a circular arc

Circle: a circle

Ellipse: an ellipse, with axes possibly rotated

Box: an axis aligned rectangle

Rectangle: a rotated rectangle

Poly: a polygon

Bezier: a Bezier curve arc

Text: a string of text

Handle: a single dragging handle

Two special methods are also available for metrology annotations:

Distance: a distance measurement arrow between two points/lines

Angle: an angle measurement arrow between two points/lines


Drawing attributes

The attributes are

DotColor: color of the pixels or dot symbols

LineColor: color of the lines

FillColor: color of the filled areas (including character background);

TextColor: color of the characters in a text

TextSize: height of the characters

SetTextFont / GetTextFont: font name

The colors can be chosen among a predefined set of primaries defined as PredefinedColors:

Black, DarkGray, LightGray, White,

Red, Green, Blue,

Cyan, Magenta, Yellow,

NoColor (equivalent to transparent filling).

In principle, the current attributes are used when drawing the primitives and built-in graphics. In some cases, colors are automatically selected to denote special situations (like Green for OK and Red for NOK); this behavior can be overridden by means of the property AutoColor.

Reference:

Primitives

Graph::Dot,
Graph::Cross, Graph::Line,
Graph::Arc,
Graph::Circle, Graph::Ellipse, Graph::Box,
Graph::Text,
Graph::Handle, Graph::Distance, Graph::Angle.

Attributes

Graph::DotColor, Graph::LineColor, Graph::FillColor, Graph::TextColor, Graph::TextSize, SetTextFont/GetTextFont, Graph::AutoColor.


Setting the drawing destination

Before graphics can appear, you must specify the targeted drawing surface, usually a window.

The Graph class provides the property DrawTo to achieve this. For portability reasons, this parameter is a pointer to void (void*).

In some cases, it is necessary to draw into an image, in a way that makes it permanent (inlay), rather than over it (nondestructive overlay). The DrawTo mechanism enables inlaying. Refer to the section Drawing into an image.


System specifics

Windows

Under Microsoft Windows, the value to be set is actually a handle to the Device Context of the drawing window. It is up to the developer to retrieve the appropriate handle.

Under Windows GDI, the function GetSafeHdc can be used; under .NET, the header file mVizNET.h provides the macro UseGraphics that will retrieve the handle from the current System::Drawing::Graphics object. After usage, do not forget to free the handle by means of the ReleaseGraphics macro.

Note: by default, the DrawTo property corresponds to the Device Context of the application console (when visible). So for a console application, there is no need to set it.

Linux

Under Linux X11, the value of DrawTo is the handle to the drawing window.

Reference:

Graph::DrawTo.


Status and Control

Miscellaneous additional features are described in this section.


Angle Unit

All angles, either user-input (passed as arguments) or computed by mViz (received from a function) are expressed in Degrees by default. You can change this behavior by setting

        Status::AngleUnit= Status::FromRadians;

        Status::UnitAngle= Status::ToRadians;

Both assignments are required.

You revert to the Degree mode by

        Status::AngleUnit= Status::FromDegrees;

        Status::UnitAngle= Status::ToDegrees;

Reference:

Status::AngleUnit, Status::FromRadians, Status::FromDegrees, Status::UnitAngle, Status::ToRadians, Status::ToDegrees.


Error processing

When a mViz function meets an abnormal situation such as when attempting to read from a missing image file or processing an object that has not been initialized, it triggers an error condition. The error condition is associated to an error code (enum ErrorCodes), and a verbose error text.

Error code: CannotOpen

To obtain the code of the last error raised, use the Status::Error method. To obtain the error text, use one of the methods Status::AsciiError or Status::UnicodeError.

Example:

C++ Native

       Src.Read("C:\\Temp\\Image.bmp");

       if (Status::Error() != NoError)

       {

              // Prompt for another file...

       }

C++.NET using namespace mVizNET;

       // Load an image from a file

       Src->Read("C:\\Temp\\Image->bmp", PixelTypes::Gray);

       if (Status::Error != ErrorCodes::NoError)

       {

              // Prompt for another file...

       }

C# using mVizNET;

       // Load an image from a file

       Src.Read("C:\\Temp\\Image.bmp", PixelTypes.Gray);

       if (Status.Error != ErrorCodes.NoError)

       {

           // Prompt for another file...

       }

Visual Basic

       ' Load an image from a file

       Src.Read("C:\\Temp\\Image.bmp", mVizNET.PixelTypes.Gray)

       If mVizNET.Status.Error <> mVizNET.ErrorCodes.NoError Then

       ' Prompt for another file...

       End If

Note that the error code is reset by any successful call.

If the application runs several threads in parallel, the error condition is raised per thread.

Reference:

ErrorCodes, Status::Error, Status::AsciiError, Status::UnicodeError.


Changing the default behavior

As soon as an error condition is detected, the error message is displayed in a dialog box. This default behavior can be changed by invoking the ErrorBehavior function with a value from PredefinedBehaviors, as follows:

IgnoreIt | Do nothing
ThrowIt | Throw a C++ exception that can be caught as a Status object
ShowIt | Display the error text in a message box – the default behavior
PrintIt | Print the error text on the standard error output (console)
AssertIt | Throw an assertion that will be caught by the debugger

The C++ interface provides an even tighter control by letting you specify a callback function to be invoked when an error condition arises. Define your own function and assign a pointer to it to the ErrorCallback member. You have the opportunity to pass context information by assigning ErrorContext a pointer to your data.

Examples:

  1. Redirection of the error message.

C++ Native

       // Send error messages to the standard error output

       Status::ErrorBehavior(PrintIt);

C++.NET using namespace mVizNET;

       // Send error messages to the standard error output

       Status::ErrorBehavior(PredefinedBehaviors::PrintIt);

C# using mVizNET;

       // Send error messages to the standard error output

       Status.ErrorBehavior(PredefinedBehaviors.PrintIt);

Visual Basic

        ' Send error messages to the standard error output

        mVizNET.Status.ErrorBehavior(mVizNET.PredefinedBehaviors.PrintIt)

  2. Try/catch handling.

C++ Native

       // Activate error throwing

       Status::ErrorBehavior(ThrowIt);

C++.NET using namespace mVizNET;

       // Activate error throwing

       Status::ErrorBehavior(PredefinedBehaviors::ThrowIt);

C# using mVizNET;

       // Activate error throwing

       Status.ErrorBehavior(PredefinedBehaviors.ThrowIt);

Visual Basic

        ' Activate error throwing

        mVizNET.Status.ErrorBehavior(mVizNET.PredefinedBehaviors.ThrowIt)

The function call:

C++ Native

    try

    {

           Src.Read("C:\\Temp\\Image.bmp");

    }

    catch (Status)

    {

           // Recover from error...

    }

C++.NET using namespace mVizNET;

    try

    {

           Src->Read("C:\\Temp\\Image->bmp", PixelTypes::Undefined);

    }

    catch (Status^)

    {

           // Recover from error...

    }

C# using mVizNET;

    try

    {

        Src.Read("C:\\Temp\\Image.bmp", PixelTypes.Undefined);

    }

    catch

    {

        // Recover from error...

    }

Visual Basic

    Try

      Src.Read("C:\\Temp\\Image.bmp", mVizNET.PixelTypes.Undefined)

    Catch

    ' Recover from error...

    End Try

  3. User-defined processing: counting by means of a user-defined callback.

C++ Native

       // Initialize error counting

       int Counter= 0;

       Status::ErrorContext= &Counter;

       Status::ErrorCallback= CountError;

C++.NET using namespace mVizNET;

       // Initialize error counting

       int Counter= 0;

       Status::ErrorContext= &Counter;

       Status::ErrorCallback= CountError;

C# using mVizNET;

Not available

Visual Basic

Not available

The callback declaration:

C++ Native

void CountError(void* Context)

{

  // Increment the error count

  (*(int*)Context)++;

}

C++.NET using namespace mVizNET;

void CountError(void* Context)

{

  // Increment the error count

  (*(int*)Context)++;

}

Reference:

Status::ErrorBehavior, enum PredefinedBehaviors, Status::ErrorCallback, Status::ErrorContext.


Timing

For accurate timing of the mViz methods, an accurate stopwatch is available. To measure a time lapse, start the watch using Status::StartWatch, perform the operation you want to time and get the value from Status::ReadWatch.

Example:

C++ Native

       // Start timing

       Status::StartWatch();

       // ... (spend X microseconds)

       // Stop timing, returns X

       int Elapsed= Status::ReadWatch();

C++.NET using namespace mVizNET;

       // Start timing

       Status::StartWatch(0, false);

       // ... (spend X microseconds)

       // Stop timing, returns X

       int Elapsed= Status::ReadWatch(0, true);

C# using mVizNET;

       // Start timing

       Status.StartWatch(0, false);

       // ... (spend X microseconds)

       // Stop timing, returns X

       int Elapsed = Status.ReadWatch(0, true);

Visual Basic

       ' Start timing

       mVizNET.Status.StartWatch(0, False)

       ' ... (spend X microseconds)

       ' Stop timing, returns X

       Dim Elapsed As Integer = mVizNET.Status.ReadWatch(0, True)

Reference:

Status::StartWatch, Status::ReadWatch.


Advanced: Using several stopwatches

You can use as many as ten independent stopwatches simultaneously. The StartWatch and ReadWatch methods take a stopwatch index in range 0..9 as the first argument. When omitted, stopwatch 0 is used.

Example:

C++ Native

       // Start timing

       Status::StartWatch(3);

       // ... (spend X microseconds)

       // Stop timing, returns X

       Elapsed= Status::ReadWatch(3);

C++.NET using namespace mVizNET;

       // Start timing

       Status::StartWatch(3, false);

       // ... (spend X microseconds)

       // Stop timing, returns X

       Elapsed= Status::ReadWatch(3, true);

C# using mVizNET;

       // Start timing

       Status.StartWatch(3, false);

       // ... (spend X microseconds)

       // Stop timing, returns X

       Elapsed = Status.ReadWatch(3, true);

Visual Basic

       ' Start timing

       mVizNET.Status.StartWatch(3, False)

       ' ... (spend X microseconds)

       ' Stop timing, returns X

       Elapsed = mVizNET.Status.ReadWatch(3, True)


Advanced: Accumulating time lapses

You can accumulate several time lapses using a sequence of StartWatch/ReadWatch calls. The method StartWatch takes an Accumulate flag as a second argument. When set to true, the previously measured time lapse is not cleared.

Example:

C++ Native

       // Start timing

       Status::StartWatch(0);

       // ... (spend X microseconds)

       // Stop timing

       Status::ReadWatch(0);

       // ... (spend Y microseconds)

       // Restart timing, with accumulation

       Status::StartWatch(0, true);

       // ... (spend Z microseconds)

       // Stop timing, returns X + Z

       Elapsed= Status::ReadWatch(0);

C++.NET using namespace mVizNET;

       // Start timing

       Status::StartWatch(0, false);

       // ... (spend X microseconds)

       // Stop timing

       Status::ReadWatch(0, true);

       // ... (spend Y microseconds)

       // Restart timing, with accumulation

       Status::StartWatch(0, true);

       // ... (spend Z microseconds)

       // Stop timing, returns X + Z

       Elapsed= Status::ReadWatch(0, true);

C# using mVizNET;

       // Start timing

       Status.StartWatch(0, false);

       // ... (spend X microseconds)

       // Stop timing

       Status.ReadWatch(0, true);

       // ... (spend Y microseconds)

       // Restart timing, with accumulation

       Status.StartWatch(0, true);

       // ... (spend Z microseconds)

       // Stop timing, returns X + Z

       Elapsed = Status.ReadWatch(0, true);

Visual Basic

       ' Start timing

       mVizNET.Status.StartWatch(0, False)

       ' ... (spend X microseconds)

       ' Stop timing

       mVizNET.Status.ReadWatch(0, True)

       ' ... (spend Y microseconds)

       ' Restart timing, with accumulation

       mVizNET.Status.StartWatch(0, True)

       ' ... (spend Z microseconds)

       ' Stop timing, returns X + Z

       Elapsed = mVizNET.Status.ReadWatch(0, True)


Advanced: Reading the time lapse after the fact

By default, the ReadWatch method gives you the elapsed time since the last call of StartWatch. You can retrieve the same value at a later time by passing to ReadWatch a Current flag argument set to false.

Example:

C++ Native

       // Start timing

       Status::StartWatch(0);

       // ... (spend X microseconds)

       // Stop timing

       Status::ReadWatch(0);

       // ... (spend Y microseconds)

       // Get the time lapse after the fact, returns X

       Elapsed= Status::ReadWatch(0, false);

C++.NET using namespace mVizNET;

       // Start timing

       Status::StartWatch(0, false);

       // ... (spend X microseconds)

       // Stop timing

       Status::ReadWatch(0, true);

       // ... (spend Y microseconds)

       // Get the time lapse after the fact, returns X

       Elapsed= Status::ReadWatch(0, false);

C# using mVizNET;

       // Start timing

       Status.StartWatch(0, false);

       // ... (spend X microseconds)

       // Stop timing

       Status.ReadWatch(0, true);

       // ... (spend Y microseconds)

       // Get the time lapse after the fact, returns X

       Elapsed = Status.ReadWatch(0, false);

Visual Basic

       ' Start timing

       mVizNET.Status.StartWatch(0, False)

       ' ... (spend X microseconds)

       ' Stop timing

       mVizNET.Status.ReadWatch(0, True)

       ' ... (spend Y microseconds)

       ' Get the time lapse after the fact, returns X

       Elapsed = mVizNET.Status.ReadWatch(0, False)

Reference:

Status::StartWatch, Status::ReadWatch.


Reference

The reference pages list all data types and methods in an exhaustive way.


Enumeration

Enum PixelTypes: type of the pixels in an image and other miscellaneous data types

Case Undefined: uninitialized image, cannot be used for processing

Case Gray: grayscale values, one byte per pixel, 0..255 from black to white

Case Gray16: extended grayscale values, two bytes per pixel, signed, -3276732768

Case Gray32: integer grayscale values, four bytes per pixel, signed, for special purposes

Case Rgb: red/green/blue color channels, three times one byte per pixel

Case Rgba: red/green/blue/alpha color channels, four times one byte per pixel

Case Grad: two signed integers to represent the components of a gradient vector

Case GeoMap: reserved for internal use - subpixel interpolation

Case Int: a signed integer number to represent a discrete feature value

Case Float: a single precision floating-point number to represent a continuous feature value - not used for image pixels

Case Dble: a double precision floating-point number to represent a continuous feature value - not used for image pixels

Case Bool: false or true value to represent a logical decision

Case IntXY: Site coordinates, a pair of short integers

Case FloatXY: Point coordinates, a pair of single precision floating-point values

Case DbleXY: Point coordinates, a pair of double precision floating-point values

Case Gray1: black& white values, one bit per pixel, 0..1 from black to white

Case Short: 16 bits signed integer

Case TypeCount: reserved for internal use


Struct RgbPixel

Color pixel data - red, green and blue components

Constructor RgbPixel: creates an uninitialized Rgb Pixel

Constructor RgbPixel: creates an uninitialized Rgb Pixel

Color Components

Property Blue: blue component

Property Green: green component

Property Red: red component


Member of the class RgbPixel - Containers

Constructor RgbPixel::RgbPixel: creates an uninitialized Rgb Pixel

RgbPixel(int Red, int Green, int Blue);

int Red: red component

int Green: green component

int Blue: blue component


Member of the class RgbPixel - Color Components

Property byte RgbPixel::Blue: blue component


Member of the class RgbPixel - Color Components

Property byte RgbPixel::Green: green component


Member of the class RgbPixel - Color Components

Property byte RgbPixel::Red: red component


Struct RgbaPixel

Color pixel data - red, green and blue components plus transparency

Constructor RgbaPixel: creates an uninitialized Rgba pixel

Constructor RgbaPixel: creates an uninitialized Rgba pixel

Color and Transparency Components

Property Blue: blue component

Property Green: green component

Property Red: red component

Property Alpha: alpha component


Member of the class RgbaPixel

Constructor RgbaPixel::RgbaPixel: creates an uninitialized Rgba pixel

RgbaPixel(int Red, int Green, int Blue, int Alpha);

int Red: red component

int Green: green component

int Blue: blue component

int Alpha: alpha component


Member of the class RgbaPixel - Color and Transparency Components

Property byte RgbaPixel::Blue: blue component


Member of the class RgbaPixel - Color and Transparency Components

Property byte RgbaPixel::Green: green component


Member of the class RgbaPixel - Color and Transparency Components

Property byte RgbaPixel::Red: red component


Member of the class RgbaPixel - Color and Transparency Components

Property byte RgbaPixel::Alpha: alpha component


Struct MapPixel

Subpixel relocation data for use with the geometric transformations

Property Offset: reserved for internal use

Property x: subpixel abscissa

Property y: subpixel ordinate


Member of the class MapPixel

Property int MapPixel::Offset: reserved for internal use


Member of the class MapPixel

Property unsigned short MapPixel::x: subpixel abscissa


Member of the class MapPixel

Property unsigned short MapPixel::y: subpixel ordinate


Struct Gradient

2D gradient vector

Constructor Gradient: creates a void Gradient object

Constructor Gradient: creates a void Gradient object

Gradient vector Components

Property Gx: horizontal component

Property Gy: vertical component


Member of the class Gradient

Constructor Gradient::Gradient: creates a void Gradient object

Gradient(int Gx, int Gy);

int Gx: X component

int Gy: Y component


Member of the class Gradient - Gradient vector Components

Property short Gradient::Gx: horizontal component


Member of the class Gradient - Gradient vector Components

Property short Gradient::Gy: vertical component


Struct Edgel

Edge point with 2D gradient vector

Edge Point Coordinates and Gradient Components

Property X: abscissa

Property Y: ordinate

Property Gx: horizontal gradient component

Property Gy: vertical gradient component


Member of the class Edgel - Edge Point Coordinates and Gradient Components

Property short Edgel::X: abscissa


Member of the class Edgel - Edge Point Coordinates and Gradient Components

Property short Edgel::Y: ordinate


Member of the class Edgel - Edge Point Coordinates and Gradient Components

Property short Edgel::Gx: horizontal gradient component


Member of the class Edgel - Edge Point Coordinates and Gradient Components

Property short Edgel::Gy: vertical gradient component


Enumeration

Enum ErrorCodes: error code of the last failing operation

Case NoError: the operation succeeded

Case UnsupportedType: the operation is not allowed with this pixel or data type; check the type compatibilities

Case IncompatibleType: the types of the pixels or data do not fit together for this operation; check the images types

Case VoidObject: this object has not been sized or typed; size or load from a file

Case IncompatibleSize: the sizes of the objects involved do not fit together; check sizing

Case IncompatibleMode: an attempt was made to use features from different modes of operation

Case CannotAllocate: memory allocation failed; check for heap corruption

Case CannotOpen: the given file could not be found or opened; check the file path and name, and device availability

Case CannotRead: the given file could not be read from; check the file device and file integrity/access rights

Case CannotWrite: the given file could not be written to; check the file device and file access rights

Case UnsupportedFormat: this file format cannot be used; check the source format

Case OutOfRange: this parameter does not fall in the allowed range; check the documentation

Case NotImplemented: reserved for internal purposes; refer to the technical support

Case DeviceFailure: some hardware-related operation such as a board or channel initialization has failed

Case NoLicense: the license for this operation is not granted

Case SystemError: an error was raised by the Operating System

Case CannotPerform: the operation didn't succeed for some reason; check the textual error message


Enumeration

Enum DraggingHandles: names of the dragging handles

Case HCorner: Snake handle, endpoint of a section, making a sharp corner

Case SCorner: Snake handle, endpoint of a section, making a smooth junction

Case Circular: Snake handle, middle point of a circular arc

Case Spline: Snake handle, intermediate point of a spline curve

Case Elliptic: Snake handle, intermediate point of an elliptic curve

Case Corner: Snake handle, endpoint of a section


Struct Site

A site is a 2D point with integer coordinates, usually corresponding to a pixel location

Constructor Site: creates an uninitialized Site

Constructor Site: creates an uninitialized Site

Coordinates

Property X: abscissa, in pixels

Property Y: ordinate, in pixels

Graphics

Method Draw: draws the site as a cross

Method HitHandle: tells if the dragging handle is under the cursor

Property Handle: identity of the last dragging handle hit

Method Drag: move the dragging handle

Geometric Operations

Method Norm: Euclidean norm

Method NormLi: Infinite norm (maximum absolute component)

Method Square: squared length of the vector PQ

Method Distance: the Euclidean distance between two points in the plane

Method Dot: the dot product of vectors AB and CD

Method Area: computes the double of the signed area of the triangle formed by three sites; this quantity allows to tell if the sites are arranges clockwise or counterclockwise

Method Intersection: intersection point of two lines segments

Method Project: projects a point orthogonally onto a line defined by two points

Method InCircle: geometric in-circle test for four points

Method CircumCircle: computes the circumscribing circle of the triangle formed by three sites

Method CircumArc: computes the circumscribing circle of the triangle formed by three sites and the two limiting angles


Member of the class Site

Constructor Site::Site: creates an uninitialized Site

Site(int X, int Y);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down


Member of the class Site - Coordinates

Property short Site::X: abscissa, in pixels


Member of the class Site - Coordinates

Property short Site::Y: ordinate, in pixels


Member of the class Site - Graphics

Method Site::Draw: draws the site as a cross

void Draw(bool Handles = false);

bool Handles: when true, the dragging handles are drawn too


Member of the class Site - Graphics

Method Site::HitHandle: tells if the dragging handle is under the cursor

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: identity of the dragging handle, or NoHandle

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class Site - Graphics

Property DraggingHandles Site::Handle: identity of the last dragging handle hit


Member of the class Site - Graphics

Method Site::Drag: move the dragging handle

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down

Method Site::Drag: move the dragging handle within a given rectangle

void Drag(int CursorX, int CursorY, const Image& Bounds);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down

Image& Bounds: underlying image that provides the dragging limits


Member of the class Site - Geometric Operations

Method Site::Norm: Euclidean norm

static double Norm(const Site& P);

returned double: the norm, as an integer

Site& P: argument


Member of the class Site - Geometric Operations

Method Site::NormLi: Infinite norm (maximum absolute component)

static int NormLi(const Site& P);

returned int: the norm, as an integer

Site& P: argument


Member of the class Site - Geometric Operations

Method Site::Square: squared length of the vector PQ

static int Square(const Site& P, const Site& Q);

returned int: integer value

Site& P: first site

Site& Q: second site


Member of the class Site - Geometric Operations

Method Site::Distance: the Euclidean distance between two points in the plane

static double Distance(const Site& P, const Site& Q);

returned double: the distance value

Site& P: first site

Site& Q: second site


Member of the class Site - Geometric Operations

Method Site::Dot: the dot product of vectors AB and CD

static int Dot(const Site& A, const Site& B, const Site& C);

returned int: integer dot product

Site& A: first site

Site& B: second site

Site& C: third site


Member of the class Site - Geometric Operations

Method Site::Area: computes the double of the signed area of the triangle formed by three sites; this quantity allows to tell if the sites are arranges clockwise or counterclockwise

static int Area(const Site& A, const Site& B, const Site& C);

returned int: signed area, times 2

Site& A: first site

Site& B: second site

Site& C: third site


Member of the class Site - Geometric Operations

Method Site::Intersection: intersection point of two lines segments

static bool Intersection(const Site& A, const Site& B, const Site& C, const Site& D, Site& I);

returned bool: true when an intersection point was found

Site& A: first endpoint of the first segment

Site& B: second endpoint of the first segment

Site& C: second endpoint of the second segment

Site& D: intersection point of two lines segments

Site& I: the intersection point


Member of the class Site - Geometric Operations

Method Site::Project: projects a point orthogonally onto a line defined by two points

static bool Project(const Site& A, const Site& B, const Site& C, double& X, double& Y, bool SegmentOnly = true, bool LeftOnly = false);

returned bool: true if projection succeeded

Site& A: point to be projected

Site& B: first point on the line

Site& C: second point on the line

double& X: abscissa of the projected point

double& Y: ordinate of the projected point

bool SegmentOnly: when true, as, by default, a projection is returned only if it falls inside the segment BC

bool LeftOnly: when true, a projection is returned only if A lies to the left of BC


Member of the class Site - Geometric Operations

Method Site::InCircle: geometric in-circle test for four points

static bool InCircle(const Site& A, const Site& B, const Site& C, const Site& D);

returned bool: true when the circle through A, B, C does not contain D

Site& A: first point

Site& B: second point

Site& C: third point

Site& D: fourth point


Member of the class Site - Geometric Operations

Method Site::CircumCircle: computes the circumscribing circle of the triangle formed by three sites

static bool CircumCircle(Site& A, Site& B, Site& C, double& X, double& Y, double& R);

returned bool: false if the triangle is degenerate, i.e. the sites are aligned

Site& A: first site

Site& B: second site

Site& C: third site

double& X: abscissa of the center of the circle

double& Y: ordinate of the center of the circle

double& R: radius of the circle


Member of the class Site - Geometric Operations

Method Site::CircumArc: computes the circumscribing circle of the triangle formed by three sites and the two limiting angles

static bool CircumArc(const Site& A, const Site& B, const Site& C, double& X, double& Y, double& R, double& T0, double& T1);

returned bool: true when the circumscribing circle could be constructed; false otherwise, i.e. when the given sites are aligned

Site& A: first site

Site& B: second site

Site& C: third site

double& X: abscissa of the center of the circle

double& Y: ordinate of the center of the circle

double& R: radius of the circle

double& T0: starting arc angle

double& T1: ending arc angle


Struct Limits

Coordinates of an axis-parallel bounding box

Constructor Limits: creates a void Limits object

Constructor Limits: creates a void Limits object

Constructor Limits: creates a void Limits object

Property Center: returns the centerpoint of the rectangle (rounded to integer coordinates)

Property Area: the area, in pixels, i.e. width times height

Method Contains: test for inclusion of a point inside the rectangle

Method Include: incorporate a new point or box and extend the limits

Method Include: incorporate a new point or box and extend the limits

Method Intersect: find the intersection with another box and adjust the limits

Coordinates

Property X: top-left corner abscissa

Property Y: top-left corner ordinate

Property Width: width, in pixels

Property Height: height, in pixels

Method Read: load the limit coordinates from a file (ASCII or UNICODE path and name)

Method Write: save the limit coordinates parameters to a file (ASCII or UNICODE path and name)


Member of the class Limits

Constructor Limits::Limits: creates a void Limits object

Limits(const Image& Src);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

mits.Y'>int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels, horizontally

int Height: number of pixels, vertically


Member of the class Limits

Property XY Limits::Center(): returns the centerpoint of the rectangle (rounded to integer coordinates)


Member of the class Limits

Property int Limits::Area(): the area, in pixels, i.e. width times height


Member of the class Limits

Method Limits::Contains: test for inclusion of a point inside the rectangle

bool Contains(Site& S);

returned bool: true if the point is contained

Site& S: coordinates of the test point


Member of the class Limits

Method Limits::Include: incorporate a new point or box and extend the limits

void Include(Limits& L);

Limits& L: the new box to include


Member of the class Limits

Method Limits::Intersect: find the intersection with another box and adjust the limits

bool Intersect(Limits& L);

returned bool: false if the two boxes have a void intersection; true otherwise

Limits& L: the box to intersect with


Member of the class Limits - Coordinates

Property short Limits::X: top-left corner abscissa


Member of the class Limits - Coordinates

Property short Limits::Y: top-left corner ordinate


Member of the class Limits - Coordinates

Property short Limits::Width: width, in pixels


Member of the class Limits - Coordinates

Property short Limits::Height: height, in pixels


Member of the class Limits - Coordinates

Method Limits::Read: load the limit coordinates from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .lim extension recommended

Method Limits::Read: load the limit coordinates parameters from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .lim extension recommended


Member of the class Limits - Coordinates

Method Limits::Write: save the limit coordinates parameters to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .lim extension recommended

Method Limits::Write: save the limit coordinates parameters to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .lim extension recommended


Struct XY

Point-coordinates in the 2D plane, using real values

Constructor XY: creates an uninitialized XY object

Constructor XY: creates an uninitialized XY object

Constructor XY: creates an uninitialized XY object

Constructor operator Site: creates a void XY object

Coordinates

Property X: real abscissa

Property Y: real ordinate

Geometric Operations

Method Norm: Euclidean norm

Method NormLi: Infinite norm (maximum absolute component)

Method Square: squared length of the vector PQ

Method Cosine: cosine of the angle formed by three points in the plane

Method Sine: sine of the angle formed by three points in the plane

Method Dot: dot product of the vectors AB and BC

Method Area: computes the double of the signed area of the triangle formed by three points; this quantity allows to tell if the points are arranges clockwise or counterclockwise

Method Intersects: detects if two line segments AB and CD intersect

Method Intersection: intersection point between two lines defined by a pair of points

Method Project: projects a point orthogonally onto a line defined by two points

Method InCircle: geometric in-circle test for four points

Method CircumCenter: center of the circumscribed circle around the triangle ABC

Method CircumCircle: computes the circumscribing circle of the triangle formed by three points

Method CircumArc: computes the circumscribing circle of the triangle formed by three points and the two limiting angles

Distances

Method Distance: the Euclidean distance between points/lines in the plane

Angles

Method Angle: clockwise angle formed by three points (+ overloads)

Graphics

Method Draw: renders the point as a cross in the current drawing window

Method HitHandle: tells if the dragging handle is under the cursor

Property Handle: identity of the last dragging handle hit

Method Drag: move the dragging handle


Member of the class XY

Constructor XY::XY: creates an uninitialized XY object

XY(const Site& S);

Site& S: site to be converted to floating-point coordinates

ark:XY.XY.Y'>double Y: ordinate


Member of the class XY

Constructor XY::operator Site: creates a void XY object

operator Site();


Member of the class XY - Coordinates

Property double XY::X: real abscissa


Member of the class XY - Coordinates

Property double XY::Y: real ordinate


Member of the class XY - Geometric Operations

Method XY::Norm: Euclidean norm

static double Norm(const XY& P);

returned double: vector length

XY& P: argument


Member of the class XY - Geometric Operations

Method XY::NormLi: Infinite norm (maximum absolute component)

static double NormLi(const XY& P);

returned double: the norm, as an double precision real

XY& P: argument


Member of the class XY - Geometric Operations

Method XY::Square: squared length of the vector PQ

static double Square(const XY& P, const XY& Q);

returned double: floating-point value

XY& P: first site

XY& Q: second site


Member of the class XY - Geometric Operations

Method XY::Cosine: cosine of the angle formed by three points in the plane

static double Cosine(const XY& P, const XY& Q, const XY& R);

returned double: cosine of the angle PQR

XY& P: first point

XY& Q: second point

XY& R: third point


Member of the class XY - Geometric Operations

Method XY::Sine: sine of the angle formed by three points in the plane

static double Sine(const XY& P, const XY& Q, const XY& R);

returned double: sine of the angle PQR

XY& P: first point

XY& Q: second point

XY& R: third point


Member of the class XY - Geometric Operations

Method XY::Dot: dot product of the vectors AB and BC

static double Dot(const XY& A, const XY& B, const XY& C);

returned double: dot product value

XY& A: first site

XY& B: second site

XY& C: third site


Member of the class XY - Geometric Operations

Method XY::Area: computes the double of the signed area of the triangle formed by three points; this quantity allows to tell if the points are arranges clockwise or counterclockwise

static double Area(const XY& A, const XY& B, const XY& C);

returned double: signed area, times 2

XY& A: first point

XY& B: second point

XY& C: third point


Member of the class XY - Geometric Operations

Method XY::Intersects: detects if two line segments AB and CD intersect

static bool Intersects(const XY& A, const XY& B, const XY& C, const XY& D);

returned bool: true if the segments intersect on a point

XY& A: endpoint of the first segment

XY& B: other endpoint of the first segment

XY& C: endpoint of the second segment

XY& D: other endpoint of the second segment


Member of the class XY - Geometric Operations

Method XY::Intersection: intersection point between two lines defined by a pair of points

static bool Intersection(const XY& A, const XY& B, const XY& C, const XY& D, XY& I);

returned bool: true when an intersection was found, false in degenerate cases

XY& A: point A of the line AB

XY& B: point B of the line AB

XY& C: point C of the line CD

XY& D: point D of the line CD

XY& I: computed intersection point


Member of the class XY - Geometric Operations

Method XY::Project: projects a point orthogonally onto a line defined by two points

static bool Project(const XY& A, const XY& B, const XY& C, XY& P, bool SegmentOnly = true, bool LeftOnly = false);

returned bool: the point projection

XY& A: point to be projected

XY& B: first point on the line

XY& C: second point on the line

XY& P: the point projection

bool SegmentOnly: when true, as, by default, a projection is returned only if it falls inside the segment BC

bool LeftOnly: when true, a projection is returned only if A lies to the left of BC


Member of the class XY - Geometric Operations

Method XY::InCircle: geometric in-circle test for four points

static bool InCircle(const XY& A, const XY& B, const XY& C, const XY& D);

returned bool: true when the circle through A, B, C does not contain D

XY& A: first point

XY& B: second point

XY& C: third point

XY& D: fourth point


Member of the class XY - Geometric Operations

Method XY::CircumCenter: center of the circumscribed circle around the triangle ABC

static double CircumCenter(const XY& A, const XY& B, const XY& C, XY& O);

returned double: true if the construction succeeded; false when the given points are aligned

XY& A: first point

XY& B: second point

XY& C: third point

XY& O: computed center


Member of the class XY - Geometric Operations

Method XY::CircumCircle: computes the circumscribing circle of the triangle formed by three points

static bool CircumCircle(const XY& A, const XY& B, const XY& C, double& X, double& Y, double& R);

returned bool: false if the triangle is degenerate, i.e. the points are aligned

XY& A: first point

XY& B: second point

XY& C: third point

double& X: abscissa of the center of the circle

double& Y: ordinate of the center of the circle

double& R: radius of the circle


Member of the class XY - Geometric Operations

Method XY::CircumArc: computes the circumscribing circle of the triangle formed by three points and the two limiting angles

static bool CircumArc(const XY& A, const XY& B, const XY& C, double& X, double& Y, double& R, double& T0, double& T1);

returned bool: true when the circumscribing circle could be constructed; false otherwise, i.e. when the given points are aligned

XY& A: first point

XY& B: second point

XY& C: third point

double& X: abscissa of the center of the circle

double& Y: ordinate of the center of the circle

double& R: radius of the circle

double& T0: starting arc angle

double& T1: ending arc angle


Member of the class XY - Distances

Method XY::Distance: the Euclidean distance between points/lines in the plane

static double Distance(const XY& P, const XY& Q);

returned double: the distance value

XY& P: first point

XY& Q: second point

Method XY::Distance: Euclidean distance between a point and a line segment

static double Distance(const XY& P, const XY& Beg, const XY& End, bool Segment = false);

returned double: the distance value

XY& P: first point

XY& Beg: starting point of the given line segment

XY& End: ending point of the given line segment

bool Segment: when true, the distance to the line segment is computed rather than to the whole line

Method XY::Distance: Euclidean distance between a point and a circle

static double Distance(const XY& P, const XY& Center, double Radius);

returned double: the distance value

XY& P: first point

XY& Center: center of the given circle

double Radius: radius of the given circle

Method XY::Distance: Euclidean distance between two line segments (average value)

static double Distance(const XY& Beg, const XY& End, const XY& Beg1, const XY& End1);

returned double: the distance value

XY& Beg: starting point of the given line segment

XY& End: ending point of the given line segment

XY& Beg1: starting point of the other line segment

XY& End1: ending point of the other line segment

Method XY::Distance: Euclidean distance between a line segment and a circle

static double Distance(const XY& Beg, const XY& End, const XY& Center, double Radius);

returned double: the distance value

XY& Beg: starting point of the given line segment

XY& End: ending point of the given line segment

XY& Center: center of the given circle

double Radius: radius of the given circle

Method XY::Distance: Euclidean distance between two circles

static double Distance(const XY& Center, double Radius, const XY& Center1, double Radius1);

returned double: the distance value

XY& Center: center of the given circle

double Radius: radius of the given circle

XY& Center1: center of the other circle

double Radius1: radius of the other circle


Member of the class XY - Angles

Method XY::Angle: clockwise angle formed by three points (+ overloads)

static double Angle(const XY& P, const XY& Q, const XY& R);

returned double: angle value, in the current angle unit

XY& P: angle apex

XY& Q: angle side vertex

XY& R: other angle side vertex

Method XY::Angle: clockwise angle formed by two line segments

static double Angle(const XY& Beg, const XY& End, const XY& Beg1, const XY& End1);

returned double: angle value, in the current angle unit

XY& Beg: starting point of the given line segment (side of the angle)

XY& End: ending point of the given line segment (side of the angle)

XY& Beg1: starting point of the other line segment (side of the angle)

XY& End1: ending point of the other line segment (side of the angle)


Member of the class XY - Graphics

Method XY::Draw: renders the point as a cross in the current drawing window

void Draw(bool Handles = false);

bool Handles: when true, the dragging handles are drawn too


Member of the class XY - Graphics

Method XY::HitHandle: tells if the dragging handle is under the cursor

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: identity of the dragging handle, or NoHandle

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class XY - Graphics

Property DraggingHandles XY::Handle: identity of the last dragging handle hit


Member of the class XY - Graphics

Method XY::Drag: move the dragging handle

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down

Method XY::Drag: move the dragging handle within the limits of an image

void Drag(int CursorX, int CursorY, const Image& Bounds);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down

Image& Bounds: the image that specifies the limits


Enumeration

Enum PredefinedColors: predefined named colors for use with the drawing or plotting functions

Case Black: black color (gray level 0)

Case DarkGray: dark gray color (gray level 170)

Case LightGray: light gray color (gray level 85)

Case White: white color (gray level 255)

Case Red: primary red color

Case Green: primary green color

Case Blue: primary blue color

Case Cyan: subtractive primary cyan color

Case Magenta: subtractive primary magenta color

Case Yellow: subtractive primary yellow color

Case NoColor: transparency

Case Cycle: pseudo-color that causes automatic color

Case Current: reserved usage


Class Image

The class that stores and handles bitmap images

Constructor Image: creates a void Image object

Method Read: load the image from a Windows Bitmap (*.bmp), PNG (*.png) or JPEG (*.jpg) file (ASCII filename)

Method Read: load the image from a Windows Bitmap (*.bmp), PNG (*.png) or JPEG (*.jpg) file (ASCII filename)

Method Write: save the image to a Windows Bitmap (*.bmp) or JPEG (*.jpg) file (ASCII filename)

Method Write: save the image to a Windows Bitmap (*.bmp) or JPEG (*.jpg) file (ASCII filename)

Sizing

Method Set: adjust the image size and pixel format explicitly

Window of Interest

Method Window: restrict the image to a rectangular window of interest

Property X: upper left point abscissa, in pixels

Property Y: upper left point ordinate, in pixels, top-down

Property Width: number of pixels, horizontally

Property Height: number of pixels, vertically

Property HasWindow: true when an image window is in use

Pixel Data

Method PixelGray1: access the pixel at given coordinates in a binary image

Method PixelGray: access the pixel at given coordinates in a grayscale image

Method PixelGray16: access the pixel at given coordinates in a 16 bits per pixel grayscale image

Method PixelGray32: access the pixel at given coordinates in a 32 bits per pixel grayscale image

Method PixelGrad: access the pixel at given coordinates in a gradient vector image

Method PixelRgb: access the pixel at given coordinates in a color image

Method PixelRgba: access the pixel at given coordinates in a 32 bits per pixel color image

Property Buffer: address of the image pixel data

Property Pitch: image row length, in bytes, padding included

Graphics

Method Draw: display the image in the current drawing window, as specified by the property Status::DrawTo

Method DrawWindow: display a frame around the current image Window in the current drawing window, as specified by the property Status::DrawTo

Method HitHandle: identity of the dragging handle under the cursor

Property Handle: identity of the last hit dragging handle

Method Drag: move the last hit handle

Property Size: image dimensions, in pixels, as a Site object

Property Center: coordinates of the center of the image

Property Area: the area of the Image or its Window, in pixels, i.e. width times height

Storage

Property Type: image pixel type, an enumerated value in PixelTypes

Property StoreWidth: full image width (no windowing)

Property StoreHeight: full image height (no windowing)


Member of the class Image

Constructor Image::Image: creates a void Image object

Image();


Member of the class Image

Method Image::Read: load the image from a Windows Bitmap (*.bmp), PNG (*.png) or JPEG (*.jpg) file (ASCII filename)

void Read(const wchar_t* PathName, enum PixelTypes Type = Gray);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string

PixelTypes Type: type to convert the image to; Undefined keeps the original type


Member of the class Image

Method Image::Write: save the image to a Windows Bitmap (*.bmp) or JPEG (*.jpg) file (ASCII filename)

void Write(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string


Member of the class Image - Sizing

Method Image::Set: adjust the image size and pixel format explicitly

void Set(int Width, int Height, PixelTypes Type = Gray, byte Store[] = 0, int Pitch = 0, int Pad = 0);

int Width: number of pixels, horizontally

int Height: number of pixels, vertically

PixelTypes Type: image pixel type, an enumerated value in PixelTypes

byte* Store: storage space for the data, either allocated internally by the object or passed as an external buffer

int Pitch: image row length, in bytes, row padding included

int Pad: alignment padding; reserved for internal use

Method Image::Set: adjust the image size and pixel format by replicating from another image

void Set(const Image& Src, PixelTypes Type = Undefined);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

PixelTypes Type: image pixel type, an enumerated value in PixelTypes


Member of the class Image - Window of Interest

Method Image::Window: restrict the image to a rectangular window of interest

void Window();

Method Image::Window: reset the image to its full extent

bool Window(const Limits& Box);

returned bool: true if the window fits in the image; false if it was clipped

Limits& Box: restrict the image to a rectangular window of interest, given by its limit coordinates

Method Image::Window: restrict the image to a rectangular window of interest

bool Window(int X, int Y, int Width, int Height);

returned bool: true if the window fits in the image; false if it was clipped

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels, horizontally

int Height: number of pixels, vertically


Member of the class Image - Window of Interest

Property int Image::X: upper left point abscissa, in pixels


Member of the class Image - Window of Interest

Property int Image::Y: upper left point ordinate, in pixels, top-down


Member of the class Image - Window of Interest

Property int Image::Width: number of pixels, horizontally


Member of the class Image - Window of Interest

Property int Image::Height: number of pixels, vertically


Member of the class Image - Window of Interest

Property bool Image::HasWindow(): true when an image window is in use


Member of the class Image - Pixel Data

Method Image::PixelGray1: access the pixel at given coordinates in a binary image

bool PixelGray1(int X, int Y);

returned bool: current pixel value

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

Method Image::PixelGray1: access the pixel at given coordinates in a binary image

void PixelGray1(int X, int Y, bool Pixel);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

bool Pixel: new pixel value


Member of the class Image - Pixel Data

Method Image::PixelGray: access the pixel at given coordinates in a grayscale image

GrayPixel& PixelGray(int X, int Y);

returned GrayPixel&: the requested pixel; can be read of modified

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down


Member of the class Image - Pixel Data

Method Image::PixelGray16: access the pixel at given coordinates in a 16 bits per pixel grayscale image

Gray16Pixel& PixelGray16(int X, int Y);

returned Gray16Pixel&: the requested pixel; can be read of modified

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down


Member of the class Image - Pixel Data

Method Image::PixelGray32: access the pixel at given coordinates in a 32 bits per pixel grayscale image

Gray32Pixel& PixelGray32(int X, int Y);

returned Gray32Pixel&: the requested pixel; can be read of modified

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down


Member of the class Image - Pixel Data

Method Image::PixelGrad: access the pixel at given coordinates in a gradient vector image

Gradient& PixelGrad(int X, int Y);

returned Gradient&: the requested gradient vector as a Gradient struct; can be read of modified

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down


Member of the class Image - Pixel Data

Method Image::PixelRgb: access the pixel at given coordinates in a color image

RgbPixel& PixelRgb(int X, int Y);

returned RgbPixel&: the requested pixel; can be read of modified

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down


Member of the class Image - Pixel Data

Method Image::PixelRgba: access the pixel at given coordinates in a 32 bits per pixel color image

RgbaPixel& PixelRgba(int X, int Y);

returned RgbaPixel&: the requested pixel; can be read of modified

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down


Member of the class Image - Pixel Data

Property byte* Image::Buffer: address of the image pixel data


Member of the class Image - Pixel Data

Property int Image::Pitch: image row length, in bytes, padding included


Member of the class Image - Graphics

Method Image::Draw: display the image in the current drawing window, as specified by the property Status::DrawTo

void Draw(bool WindowOnly = false);

bool WindowOnly: when true, only the currently defined image Window is drawn; when false, as by default, the whole image is drawn

Method Image::Draw: display the image in the current drawing window, as specified by the property Status::DrawTo, using pseudo-coloring

void Draw(const Profile& LookupTable, bool WindowOnly = false);

Profile& LookupTable: profile defining a grayscale or color lookup-table to be applied while displaying

bool WindowOnly: when true, only the currently defined image Window is drawn; when false, as by default, the whole image is drawn

Method Image::Draw: display the image in the current drawing window, as specified by the property Status::DrawTo

void Draw(Limits& Visible);

Limits& Visible: Reserved


Member of the class Image - Graphics

Method Image::DrawWindow: display a frame around the current image Window in the current drawing window, as specified by the property Status::DrawTo

void DrawWindow(bool Handles = false);

bool Handles: when true, the dragging handles are drawn too


Member of the class Image - Graphics

Method Image::HitHandle: identity of the dragging handle under the cursor

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: a value enumerated in DraggingHandles

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class Image - Graphics

Property DraggingHandles Image::Handle: identity of the last hit dragging handle


Member of the class Image - Graphics

Method Image::Drag: move the last hit handle

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class Image - Graphics

Property Site Image::Size(): image dimensions, in pixels, as a Site object


Member of the class Image - Graphics

Property XY Image::Center(): coordinates of the center of the image


Member of the class Image - Graphics

Property int Image::Area(): the area of the Image or its Window, in pixels, i.e. width times height


Member of the class Image - Storage

Property PixelTypes Image::Type: image pixel type, an enumerated value in PixelTypes


Member of the class Image - Storage

Property int Image::StoreWidth: full image width (no windowing)


Member of the class Image - Storage

Property int Image::StoreHeight: full image height (no windowing)


Enumeration

Enum SourceMode: specifies how a source object is being processed; reserved for internal use

Case Idle: no operation in progress

Case NotIdle: operaiton in progress

Case AsciiFiles: reading frames from separate image files using the ASCII naming convention

Case UnicodeFiles: reading frames from separate image files using the UNICODE naming convention

Case Sequence: reading frames from an image sequence file (AVI)

Case Camera: grabbing frames from a camera


Class Source

A source of images such as an Avi video sequence

Constructor Source: creates a void Source object

Destructor ~Source: Destructor

Access

Method Append: add a new ASCII file path and name to the current list

Method OpenSequenceFile: open an image sequence file (AVI) given by its ANSI path and name

Method OpenCamera: detects and initialize for grabbing a video camera device

Method Close: close the Avi file

Property Mode: current mode of operation as defined in enum SourceMode; one of Idle, AsciiFiles, UnicodeFiles, Sequence

Frame Reading

Property FrameCount: total number of frames in the stream

Property FrameRate: number of frames by second in the stream

Property FrameIndex: current frame index, in range [0..FrameCount-1]

Method Grab: get an image from the stream

Property Exposure: exposure time, in seconds

Property Gain: sets the analog gain (if supported by the hardware), as a multiplicative factor - not in dB

Property Deinterleave: when true, applies image deinterleaving by lines duplication; reserved

Clipboard

Method CopyToClipboard: transfers an image to the Windows clipboard for pasting elsewhere

Method PasteFromClipboard: transfers from the Windows clipboard an image copied from elsewhere

I/O

Method Input: reads the state of a given digital input line (if supported by the hardware)

Method Output: sets the state of a given digital output line (if supported by the hardware)


Member of the class Source

Constructor Source::Source: creates a void Source object

Source();


Member of the class Source

Destructor Source::~Source: Destructor

~Source();


Member of the class Source - Access

Method Source::Append: add a new ASCII file path and name to the current list

void Append(const char* PathName);

char* PathName: file path and name as an ASCII or UNICODE character string

Method Source::Append: add a new UNICODE file path and name to the current list

void Append(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string


Member of the class Source - Access

Method Source::OpenSequenceFile: open an image sequence file (AVI) given by its ANSI path and name

void OpenSequenceFile(const char* PathName);

char* PathName: file path and name as an ASCII or UNICODE character string

Method Source::OpenSequenceFile: open an image sequence file (AVI) given by its UNICODE path and name

void OpenSequenceFile(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string


Member of the class Source - Access

Method Source::OpenCamera: detects and initialize for grabbing a video camera device

void OpenCamera(int Index = 0);

int Index: zero-based index value to access a list of items


Member of the class Source - Access

Method Source::Close: close the Avi file

void Close();


Member of the class Source - Access

Property SourceMode Source::Mode: current mode of operation as defined in enum SourceMode; one of Idle, AsciiFiles, UnicodeFiles, Sequence


Member of the class Source - Frame Reading

Property int Source::FrameCount: total number of frames in the stream


Member of the class Source - Frame Reading

Property double Source::FrameRate: number of frames by second in the stream


Member of the class Source - Frame Reading

Property int Source::FrameIndex: current frame index, in range [0..FrameCount-1]


Member of the class Source - Frame Reading

Method Source::Grab: get an image from the stream

bool Grab(Image& Dst, enum PixelTypes DstType = Undefined);

returned bool: true when an image was obtained; false at the end of the stream

Image& Dst: the destination image, which is computed by this operation

PixelTypes DstType: pixel type of the destination image; one of Gray, Rgb and Rgba; if Undefined, as by default, the native type in the Avi file is used


Member of the class Source - Frame Reading

Property double Source::Exposure: exposure time, in seconds


Member of the class Source - Frame Reading

Property double Source::Gain: sets the analog gain (if supported by the hardware), as a multiplicative factor - not in dB


Member of the class Source - Frame Reading

Property bool Source::Deinterleave: when true, applies image deinterleaving by lines duplication; reserved


Member of the class Source - Clipboard

Method Source::CopyToClipboard: transfers an image to the Windows clipboard for pasting elsewhere

static void CopyToClipboard(void* hWnd);

void* hWnd: copies the content of the Window to the clipboard

Method Source::CopyToClipboard: transfers an image to the Windows clipboard for pasting elsewhere

static void CopyToClipboard(const Image& Src);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; the Type must be one of Gray, Rgb or Rgba


Member of the class Source - Clipboard

Method Source::PasteFromClipboard: transfers from the Windows clipboard an image copied from elsewhere

static void PasteFromClipboard(Image& Dst);

Image& Dst: transfers from the Windows clipboard an image copied from elsewhere; the Type will be one of Gray (8 bits palettized, converted to grayscale), Rgb (24 bits) or Rgba (32 bits)


Member of the class Source - I/O

Method Source::Input: reads the state of a given digital input line (if supported by the hardware)

bool Input(int Index);

returned bool: current binary value of the selected input line

int Index: zero-based index value to access a list of items


Member of the class Source - I/O

Method Source::Output: sets the state of a given digital output line (if supported by the hardware)

void Output(int Index, bool Value);

int Index: zero-based index value to access a list of items

bool Value: binary value to assign to the selected output line


Class Poly

Open or closed polygon, using floating-point coordinates

Constructor Poly: creates a void Poly object

Poly Data

Method Clear: resets the number of vertices

Method Append: inserts a new vertex at the end

Method ClosestTo: reports the index of the site in the path which is the closest to the given site. This method can be used for site selection with a mouse

Method Vertex: access the vertex at the given index, for reading or modifying

Processing

Method Smooth: make a polygon smoother by discarding vertices that do not deviate much

Method LineFit: adjusts a line segment model over the points of the Poly; the Poly should be opened; requires the Calibration or Gauging license

Method CircleFit: adjusts a circle/arc model over the points of the polygon; requires the Calibration or Gauging license

Method EllipseFit: adjust an ellipse on the points in the polygon

Analysis

Method Box: axis-aligned bounding box of the polygon

Method Rectangle: tightest bounding rectangle, with allowed rotation

Method Circle: tightest bounding circle

Method ConvexHull: builds the convex hull of the given polygon

Property Area: area enclosed by the polygon

Property Perimeter: perimeter length of the polygon

Method Center: coordinates of the gravity center of the outline, assuming mass at the vertices only

Method LineDeviation: estimates the deviation from an ideal straight line, obtained by line fitting

Method CircleDeviation: estimates the deviation from an ideal straight circle, obtained by circle fitting

Method RectangleDeviation: Computes the average distance between a path and the outline of a rectangle

Method EllipseDeviation: Computes the average distance between a path and the outline of an ellipse

Graphics

Method Draw: draws the given polyline. If the Poly object has the Closed property set to true, the polygon is closed

Method ClosestHandle: find the polygon vertex which is closest to the cursor coordinates; the current zoom factor applies

Property Handle: identity of the last handle hit; one of NoHandle or AllHandle

Property HitIndex: index of the last vertex hit, -1 if none

Method PointInPolygon: checks if a given point is inside a polygon or not

Method Overlapping: checks if two polygons overlap or not

Method Drag: drag the last hit vertex to a new position

Method Insert: insert a vertex before or after the given index

Method Delete: remove the closest vertex

Storage

Property Length: number of pixels or samples

Property Buffer: gives direct access to the vertices via a pointer; CAUTION: access at invalid offsets cause unpredictable effets.

Property Closed: when true, the polyline is closed; there is no need to repeat the first vertex

Method Read: load the Poly data from a file (ASCII or UNICODE path and name)

Method Write: save the Poly data to a file (ASCII or UNICODE path and name)


Member of the class Poly

Constructor Poly::Poly: creates a void Poly object

Poly();


Member of the class Poly - Poly Data

Method Poly::Clear: resets the number of vertices

void Clear();


Member of the class Poly - Poly Data

Method Poly::Append: inserts a new vertex at the end

void Append(double X, double Y);

double X: vertex abscissa

double Y: vertex ordinate

Method Poly::Append: inserts a new vertex at the end

void Append(const XY& S);

XY& S: the floating-point (X, Y) coordinates of the vertex


Member of the class Poly - Poly Data

Method Poly::ClosestTo: reports the index of the site in the path which is the closest to the given site. This method can be used for site selection with a mouse

int ClosestTo(XY& S);

returned int: the index of the closest site in the path

XY& S: the targeted vertex


Member of the class Poly - Poly Data

Method Poly::Vertex: access the vertex at the given index, for reading or modifying

XY& Vertex(int I);

returned XY&: the (X, Y) floating-point vertex coordinates

int I: starting index of the pixel or sample


Member of the class Poly - Processing

Method Poly::Smooth: make a polygon smoother by discarding vertices that do not deviate much

void Smooth(Poly& Dst, double Deviation = 3);

Poly& Dst: the destination polygon that receives the smoothed result

double Deviation: deviation tolerance, in pixels


Member of the class Poly - Processing

Method Poly::LineFit: adjusts a line segment model over the points of the Poly; the Poly should be opened; requires the Calibration or Gauging license

bool LineFit(XY& Center, double& Angle, FittingModes Mode = AccurateFit);

returned bool: returns true when the fit succeeded; if false, the point configuration is degenerate

XY& Center: some point on the fitted line

double& Angle: orientation angle of the line, in the current angle unit

FittingModes Mode: fitting mode, as specified by enum FittingModes; for a line segment, AverageFit, FastFit and AccurateFit are synonymous


Member of the class Poly - Processing

Method Poly::CircleFit: adjusts a circle/arc model over the points of the polygon; requires the Calibration or Gauging license

bool CircleFit(XY& Center, double& Radius, FittingModes Mode = AccurateFit);

returned bool: returns true when the fit succeeded; if false, the point configuration is degenerate

XY& Center: coordinates of the fitted circle

double& Radius: radius of the fitted circle

FittingModes Mode: fitting mode, as specified by enum FittingModes


Member of the class Poly - Processing

Method Poly::EllipseFit: adjust an ellipse on the points in the polygon

bool EllipseFit(XY& Center, XY& Axis, double& Angle, FittingModes Mode = AccurateFit);

returned bool: true when fitting has succeeded; otherwise false

XY& Center: ellipse center

XY& Axis: long and short axis lengths

double& Angle: main axis direction angle, in the current angle unit

FittingModes Mode: fitting mode, as specified by enum FittingModes; for an ellipse, AverageFit and FastFit are synonymous


Member of the class Poly - Analysis

Method Poly::Box: axis-aligned bounding box of the polygon

void Box(double& X, double& Y, double& Width, double& Height);

double& X: minmum abscissa

double& Y: minimum ordinate

double& Width: maximum minus minimum abscissa

double& Height: maximum minus minmum ordinate


Member of the class Poly - Analysis

Method Poly::Rectangle: tightest bounding rectangle, with allowed rotation

void Rectangle(double& Xc, double& Yc, double& Width, double& Height, double& Angle, bool Simple = true);

double& Xc: center abscissa

double& Yc: center ordinate

double& Width: shortes dimension

double& Height: largest dimension

double& Angle: rotation angle

bool Simple: use true, as by default, if the polygon is known to be simple; false otherwise


Member of the class Poly - Analysis

Method Poly::Circle: tightest bounding circle

void Circle(double& Xc, double& Yc, double& Radius, bool Simple = true);

double& Xc: center abscissa

double& Yc: center ordinate

double& Radius: radius

bool Simple: use true, as by default, if the polygon is known to be simple; false otherwise


Member of the class Poly - Analysis

Method Poly::ConvexHull: builds the convex hull of the given polygon

void ConvexHull(Poly& Dst, bool Simple = false);

Poly& Dst: hull polygon

bool Simple: false for an arbitrary point set; true if the polygon is known to be clockwise and simple (no self-intersections)


Member of the class Poly - Analysis

Property double Poly::Area(): area enclosed by the polygon


Member of the class Poly - Analysis

Property double Poly::Perimeter(): perimeter length of the polygon


Member of the class Poly - Analysis

Method Poly::Center: coordinates of the gravity center of the outline, assuming mass at the vertices only

void Center(double& X, double& Y);

double& X: computed center abscissa

double& Y: computed center ordinate


Member of the class Poly - Analysis

Method Poly::LineDeviation: estimates the deviation from an ideal straight line, obtained by line fitting

double LineDeviation(XY Center, double Angle, bool RMS = true);

returned double: Mean absolute or RMS deviation from the ideal line

XY Center: known point of line (may be obtained from LineFit)

double Angle: known orientation angle of line (may be obtained from LineFit)

bool RMS: when true, the root-mean-square formula is used; when false, the mean absolute distance


Member of the class Poly - Analysis

Method Poly::CircleDeviation: estimates the deviation from an ideal straight circle, obtained by circle fitting

double CircleDeviation(XY Center, double Radius, bool RMS = true);

returned double: Mean absolute or RMS deviation from the ideal circle

XY Center: known circle center (may be obtained from CircleFit)

double Radius: known circle radius (may be obtained from CircleFit)

bool RMS: when true, the root-mean-square formula is used; when false, the mean absolute distance


Member of the class Poly - Analysis

Method Poly::RectangleDeviation: Computes the average distance between a path and the outline of a rectangle

double RectangleDeviation(XY Center, XY Sides, double Angle, bool RMS = true);

returned double: average distance

XY Center: rectangle center

XY Sides: rectangle width and height

double Angle: orientation angle in the current angle unit; horizontal width is 0

bool RMS: root-mean-square value instead of arithmetic average


Member of the class Poly - Analysis

Method Poly::EllipseDeviation: Computes the average distance between a path and the outline of an ellipse

double EllipseDeviation(XY Center, XY Axis, double Angle, bool RMS = true, int NumIterations = 0);

returned double: average distance

XY Center: ellipse center

XY Axis: ellipse major and minor axis

double Angle: orientation angle of the major axis; horizontal major is 0

bool RMS: root-mean-square value instead of arithmetic average

int NumIterations: an iterative method being used, specify an iteration count between 0 (acceptable) and 3 (very accurate)


Member of the class Poly - Graphics

Method Poly::Draw: draws the given polyline. If the Poly object has the Closed property set to true, the polygon is closed

void Draw(int VertexSize = 0, bool Edges = true);

int VertexSize: size of the dots used to represent the vertices, using the convention in Graph::Dot

bool Edges: if true, as by default, the edges are drawn


Member of the class Poly - Graphics

Method Poly::ClosestHandle: find the polygon vertex which is closest to the cursor coordinates; the current zoom factor applies

int ClosestHandle(int CursorX, int CursorY);

returned int: index of the closest vertex

int CursorX: cursor abscissa, in pixels

int CursorY: cursor ordinate, in pixels


Member of the class Poly - Graphics

Property DraggingHandles Poly::Handle: identity of the last handle hit; one of NoHandle or AllHandle


Member of the class Poly - Graphics

Property int Poly::HitIndex: index of the last vertex hit, -1 if none


Member of the class Poly - Graphics

Method Poly::PointInPolygon: checks if a given point is inside a polygon or not

bool PointInPolygon(const XY& P);

returned bool: true when the point is inside; no particular guarantee is given for points on the outline

XY& P: the test point


Member of the class Poly - Graphics

Method Poly::Overlapping: checks if two polygons overlap or not

bool Overlapping(const Poly& Src);

returned bool: true when there is (partial) overlap

Poly& Src: the second polygon


Member of the class Poly - Graphics

Method Poly::Drag: drag the last hit vertex to a new position

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels


Member of the class Poly - Graphics

Method Poly::Insert: insert a vertex before or after the given index

void Insert(int CursorX, int CursorY, bool Before = true);

int CursorX: cursor abscissa, in pixels

int CursorY: cursor ordinate, in pixels

bool Before: when true, the point is inserted before the last closest handle in the natural order; otherwise, it is inserted after


Member of the class Poly - Graphics

Method Poly::Delete: remove the closest vertex

void Delete();


Member of the class Poly - Storage

Property int Poly::Length: number of pixels or samples


Member of the class Poly - Storage

Property XY* Poly::Buffer(): gives direct access to the vertices via a pointer; CAUTION: access at invalid offsets cause unpredictable effets.


Member of the class Poly - Storage

Property bool Poly::Closed: when true, the polyline is closed; there is no need to repeat the first vertex


Member of the class Poly - Storage

Method Poly::Read: load the Poly data from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .pol extension recommended

Method Poly::Read: load the Poly data from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .pol extension recommended


Member of the class Poly - Storage

Method Poly::Write: save the Poly data to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .pol extension recommended

Method Poly::Write: save the Poly data to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .pol extension recommended


Enumeration

Enum AlphaModes: Rgba images have an Alpha plane representing transparency

Case Opaque: transparency values are ignored

Case Transparent: transparency values are used

Case Premultiplied: transparency values are used with alpha premultiplication


Class Graph

Graphical support class

Display

Property DrawTo: the graphics device to draw to; under Windows, assign a valid device context handle (HDC parameter)

Property Zoom: drawing zoom factor; 1 for true scale, < 1 for reduction, > 1 for magnification

Method Offset: shifts all subsequent drawing by the given vector

Property Resolution: images drawing resolution, in dots per inch; 72 DPI by default

Property TextSize: height of characters, in pixels; the width is set proportionally

Property AlphaRendering: sets the way the Alpha plane of Rgba images is handled for display

Property DrawToDefault: set the property DrawTo to this value to use the application window as the drawing target

Method DrawToImage: draw into the given image rather than a graphics device; this allows to inlay. After drawing, always invoke the ReleaseImage method

Method ReleaseImage: to be called after an image has been modified via DrawToImage

Graphics Attributes

Property DotColor: sets the color of the dots or crosses markers for all subsequent drawing operations

Property LineColor: sets the color of the lines or outlines for all subsequent drawing operations

Property FillColor: sets the color of the filling for subsequent drawing operations; the default is NoColor, no filling is made

Property TextColor: color to use for the text annotations; the color of the text backgounrd is set via FillColor

Property LineThickness: thickness, in pixels

Method TextOrigin: relative location of the origin point of the text, for alignment purposes

Method SetTextFont: select a new font by its name

Property GetTextFont: name of the current text font

Property AutoColor: some of the drawing functions force predefined colors by default using a color code (green=OK, red=NOK); setting the AutoColor flag to false disables this behavior

Property SmoothZoom: when true, as by default, zoomed out images a pre-filtered to avoid aliasing

Graphics Primitives

Method Dot: draws a single point or a small circle using integer coordinates, in the current DotColor

Method Cross: draws a small cross at the given point using integer coordinates, in the current DotColor

Method Line: draws a straight line segment between two points using floating-point coordinates

Method Box: draws an axis aligned rectangle using integer coordinates

Method Rectangle: draws a rotated rectangle in the current LineColor, and fills with the current FillColor

Method Poly: draws a closed polygon or open polyline in the current LineColor, and fills with the current FillColor if closed

Method Circle: draws a circle of given center and radius in the current LineColor, and fills with the current FillColor

Method Arc: draws a circular arc of given center and radius, between two given angles

Method Ellipse: draws an ellipse of arbitrary orientation in the current LineColor, and fills with the current FillColor

Method EllipseArc: draws an ellipse

Method Bezier: draws an arc of Bezier cubic curve

Method Text: draws an ASCII text string using integer coordinates

Method Handle: draws a dragging handle

Method Distance: draw the Euclidean distance between two points (+ overloads)

Method Angle: draw the clockwise angle formed by three points (+ overloads)

Method Color: returns the value of a given predefined color

Method EraseWindow: Fill the current Window with a solid color to erase it

Method ZoomToWindow: adjust the zoom factor so that the given image size fits in the display window

Method WaitClose: block until the graphics window is closed by the GUI


Member of the class Graph - Display

Property void*& Graph::DrawTo(): the graphics device to draw to; under Windows, assign a valid device context handle (HDC parameter)


Member of the class Graph - Display

Property double Graph::Zoom: drawing zoom factor; 1 for true scale, < 1 for reduction, > 1 for magnification


Member of the class Graph - Display

Method Graph::Offset: shifts all subsequent drawing by the given vector

static void Offset(int X, int Y);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

Method Graph::Offset: shifts all subsequent drawing by the given vector

static void Offset(const Site& O);

Site& O: upper left point coordinates, in pixels

Method Graph::Offset: resets shifting

static void Offset();


Member of the class Graph - Display

Property double Graph::Resolution: images drawing resolution, in dots per inch; 72 DPI by default


Member of the class Graph - Display

Property int Graph::TextSize: height of characters, in pixels; the width is set proportionally


Member of the class Graph - Display

Property AlphaModes Graph::AlphaRendering: sets the way the Alpha plane of Rgba images is handled for display


Member of the class Graph - Display

Property void* Graph::DrawToDefault: set the property DrawTo to this value to use the application window as the drawing target


Member of the class Graph - Display

Method Graph::DrawToImage: draw into the given image rather than a graphics device; this allows to inlay. After drawing, always invoke the ReleaseImage method

static void DrawToImage(Image& Dst);

Image& Dst: the destination image, which is computed by this operation


Member of the class Graph - Display

Method Graph::ReleaseImage: to be called after an image has been modified via DrawToImage

static void ReleaseImage(Image& Dst);

Image& Dst: the destination image, which is computed by this operation


Member of the class Graph - Graphics Attributes

Property PredefinedColors Graph::DotColor: sets the color of the dots or crosses markers for all subsequent drawing operations


Member of the class Graph - Graphics Attributes

Property PredefinedColors Graph::LineColor: sets the color of the lines or outlines for all subsequent drawing operations


Member of the class Graph - Graphics Attributes

Property PredefinedColors Graph::FillColor: sets the color of the filling for subsequent drawing operations; the default is NoColor, no filling is made


Member of the class Graph - Graphics Attributes

Property PredefinedColors Graph::TextColor: color to use for the text annotations; the color of the text backgounrd is set via FillColor


Member of the class Graph - Graphics Attributes

Property int Graph::LineThickness: thickness, in pixels


Member of the class Graph - Graphics Attributes

Method Graph::TextOrigin: relative location of the origin point of the text, for alignment purposes

static void TextOrigin(int X, int Y);

int X: -1 for left edge, 0 for horizontal middle, +1 for right edge

int Y: -1 for top edge, 0 for vertical middle, +1 for bottom edge


Member of the class Graph - Graphics Attributes

Method Graph::SetTextFont: select a new font by its name

static void SetTextFont(char* Font);

char* Font: name of the new font


Member of the class Graph - Graphics Attributes

Property char* Graph::GetTextFont(): name of the current text font


Member of the class Graph - Graphics Attributes

Property bool Graph::AutoColor: some of the drawing functions force predefined colors by default using a color code (green=OK, red=NOK); setting the AutoColor flag to false disables this behavior


Member of the class Graph - Graphics Attributes

Property bool Graph::SmoothZoom: when true, as by default, zoomed out images a pre-filtered to avoid aliasing


Member of the class Graph - Graphics Primitives

Method Graph::Dot: draws a single point or a small circle using integer coordinates, in the current DotColor

static void Dot(double X, double Y, int Size = 0);

double X: point abscissa, in pixels

double Y: point ordinate, in pixels, top-down

int Size: half-diameter of the point

Method Graph::Dot: draws a single point or a small circle using floating-point coordinates, in the current DotColor

static void Dot(const Site& S, int Size = 0);

Site& S: point coordinates

int Size: half-diameter of the point

Method Graph::Dot: draws a single point or a small circle using Site integer coordinate pairs, in the current DotColor

static void Dot(const XY& S, int Size = 0);

XY& S: point coordinates

int Size: half-diameter of the point


Member of the class Graph - Graphics Primitives

Method Graph::Cross: draws a small cross at the given point using integer coordinates, in the current DotColor

static void Cross(double X, double Y, int Size = 3);

double X: point abscissa, in pixels

double Y: point ordinate, in pixels, top-down

int Size: half cross diameter

Method Graph::Cross: draws a small cross at the given point using floating-point coordinates, in the current DotColor

static void Cross(const Site& S, int Size = 3);

Site& S: point coordinates

int Size: half cross diameter

Method Graph::Cross: draws a small cross at the given point using Site integer coordinate pairs, in the current DotColor

static void Cross(const XY& S, int Size = 3);

XY& S: point coordinates

int Size: half cross diameter


Member of the class Graph - Graphics Primitives

Method Graph::Line: draws a straight line segment between two points using floating-point coordinates

static void Line(double X0, double Y0, double X1, double Y1, int ArrowHeads = 0);

double X0: starting abscissa

double Y0: starting ordinate

double X1: ending abscissa

double Y1: ending ordinate

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides

Method Graph::Line: draws a straight line segment between two points using floating-point coordinates

static void Line(const Site& S0, const Site& S1, int ArrowHeads = 0);

Site& S0: starting point coordinates

Site& S1: intermediate or ending point coordinates

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides

Method Graph::Line: draws a straight line segment between two points using Site integer coordinate pairs

static void Line(const XY& S0, const XY& S1, int ArrowHeads = 0);

XY& S0: starting point coordinates

XY& S1: intermediate or ending point coordinates

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides

Method Graph::Line: draws a straight line segment between two points using XY floating-point coordinate pairs

static void Line(const Site& S0, const Site& S1, const Site& S2, int ArrowHeads = 0);

Site& S0: starting point coordinates

Site& S1: intermediate or ending point coordinates

Site& S2: intermediate or ending point coordinates

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides

Method Graph::Line: draws a polyline between three points using Site integer coordinate pairs

static void Line(const Site& S0, const Site& S1, const Site& S2, const Site& S3, int ArrowHeads = 0);

Site& S0: starting point coordinates

Site& S1: intermediate or ending point coordinates

Site& S2: intermediate or ending point coordinates

Site& S3: ending point coordinates

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides

Method Graph::Line: draws a polyline between three points using XY floating-point coordinate pairs

static void Line(const XY& S0, const XY& S1, const XY& S2, int ArrowHeads = 0);

XY& S0: starting point coordinates

XY& S1: intermediate or ending point coordinates

XY& S2: intermediate or ending point coordinates

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides

Method Graph::Line: draws a polyline between four points using Site integer coordinate pairs

static void Line(const XY& S0, const XY& S1, const XY& S2, const XY& S3, int ArrowHeads = 0);

XY& S0: starting point coordinates

XY& S1: intermediate or ending point coordinates

XY& S2: intermediate or ending point coordinates

XY& S3: ending point coordinates

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides


Member of the class Graph - Graphics Primitives

Method Graph::Box: draws an axis aligned rectangle using integer coordinates

static void Box(double X, double Y, double Width, double Height);

double X: upper left point abscissa, in pixels

double Y: upper left point ordinate, in pixels, top-down

double Width: number of pixels, horizontally

double Height: number of pixels, vertically

Method Graph::Box: draws an axis aligned rectangle using floating-point coordinates

static void Box(Limits& Box);

Limits& Box: limit coordinates of the box


Member of the class Graph - Graphics Primitives

Method Graph::Rectangle: draws a rotated rectangle in the current LineColor, and fills with the current FillColor

static void Rectangle(double Xc, double Yc, double Width, double Height, double Angle);

double Xc: abscissa of the center

double Yc: ordinate of the center

double Width: width, the horizontal size when the angle is zero

double Height: height, the vertical size when the angle is zero

double Angle: rotation angle, in degrees


Member of the class Graph - Graphics Primitives

Method Graph::Poly: draws a closed polygon or open polyline in the current LineColor, and fills with the current FillColor if closed

static void Poly(Site Vertex[], int N, bool Closed = true);

Site* Vertex: array with the vertices

int N: total number of vertices

bool Closed: when true, the first and last vertices are joined by an edge

Method Graph::Poly: draws a closed polygon or open polyline in the current LineColor, and fills with the current FillColor if closed

static void Poly(XY Vertex[], int N, bool Closed = true);

XY* Vertex: array with the vertices

int N: total number of vertices

bool Closed: when true, the first and last vertices are joined by an edge


Member of the class Graph - Graphics Primitives

Method Graph::Circle: draws a circle of given center and radius in the current LineColor, and fills with the current FillColor

static void Circle(double Xc, double Yc, double Radius);

double Xc: center abscissa

double Yc: center ordinate

double Radius: radius

Method Graph::Circle: draws a circle of given center and radius in the current LineColor, and fills with the current FillColor

static void Circle(const XY& Center, double Radius);

XY& Center: coordinates of the center

double Radius: radius


Member of the class Graph - Graphics Primitives

Method Graph::Arc: draws a circular arc of given center and radius, between two given angles

static void Arc(double Xc, double Yc, double Radius, double Angle0, double Angle1, bool Direct = true, int ArrowHeads = 0);

double Xc: center abscissa

double Yc: center ordinate

double Radius: radius

double Angle0: starting angle

double Angle1: ending angle

bool Direct: when true, the arc is drawn in the clockwise direction, otherwise in the trigonometric direction

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides

Method Graph::Arc: draws a circular arc of given center and radius, between two given angles

static void Arc(const XY& Center, double Radius, double Angle0, double Angle1, bool Direct = true, int ArrowHeads = 0);

XY& Center: coordinates of the center

double Radius: radius

double Angle0: starting angle

double Angle1: ending angle

bool Direct: when true, the arc is drawn in the clockwise direction, otherwise in the trigonometric direction

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides


Member of the class Graph - Graphics Primitives

Method Graph::Ellipse: draws an ellipse of arbitrary orientation in the current LineColor, and fills with the current FillColor

static void Ellipse(double Xc, double Yc, double Width, double Height, double Angle);

double Xc: center abscissa

double Yc: center ordinate

double Width: major semi-axis length

double Height: minor semi-axis length

double Angle: direction angle of the major axis

Method Graph::Ellipse: draws an ellipse of arbitrary orientation in the current LineColor, and fills with the current FillColor

static void Ellipse(const XY& Center, const XY& Axis, double Angle);

XY& Center: coordinates of the center as an XY vector

XY& Axis: lengths of the axis, as an XY vector

double Angle: direction angle of the major axis


Member of the class Graph - Graphics Primitives

Method Graph::EllipseArc: draws an ellipse

static void EllipseArc(double Xc, double Yc, double Width, double Height, double Angle, double Angle0, double Angle1, bool Geometric = true, bool Direct = true, int ArrowHeads = 0);

double Xc: abscissa of the center

double Yc: ordinate of the center

double Width: first semi-axis

double Height: second semi-axis

double Angle: direction angle of the first semi-axis, in degrees

double Angle0: delimiting angle of the start of the arc, in degrees, wrt the first semi-axis

double Angle1: delimiting angle of the end of the arc, in degrees, wrt the first semi-axis

bool Geometric: when true, the angles are the true geometric angles; otherwise they denote the parameter of the standard parametric equation

bool Direct: arc described in the clockwise direction

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides

Method Graph::EllipseArc: draws an elliptic arc

static void EllipseArc(const XY& Center, const XY& Axis, double Angle, double Angle0, double Angle1, bool Geometric = true, bool Direct = true, int ArrowHeads = 0);

XY& Center: coordinates of the center

XY& Axis: lengths of the axis, grouped in a pair

double Angle: direction angle of the first semi-axis, in degrees

double Angle0: delimiting angle of the start of the arc, in degrees, wrt the first semi-axis

double Angle1: delimiting angle of the end of the arc, in degrees, wrt the first semi-axis

bool Geometric: when true, the angles are the true geometric angles; otherwise they denote the parameter of the standard parametric equation

bool Direct: arc described in the clockwise direction

int ArrowHeads: number of arrow heads at endpoints; 0: no arrow, 1: arrow at the end, 2: arrows on both sides


Member of the class Graph - Graphics Primitives

Method Graph::Bezier: draws an arc of Bezier cubic curve

static void Bezier(const XY& O, const XY& P, const XY& Q, const XY& R);

XY& O: first control point

XY& P: second control point

XY& Q: third control point

XY& R: fourth control point


Member of the class Graph - Graphics Primitives

Method Graph::Text: draws an ASCII text string using integer coordinates

static void Text(double X, double Y, const char* Label);

double X: origin point abscissa, in pixels

double Y: origin point ordinate, in pixels, top-down

char* Label: the text string

Method Graph::Text: draws a UNICODE text string using floating-point coordinates

static void Text(const Site& S, const char* Label);

Site& S: origin point coordinates, in pixels

char* Label: the text string

Method Graph::Text: draws an ASCII text string using integer coordinates

static void Text(const XY& S, const char* Label);

XY& S: origin point coordinates, in pixels

char* Label: the text string

Method Graph::Text: draws an ASCII text string using integer coordinates

static void Text(double X, double Y, const wchar_t* Label);

double X: origin point abscissa, in pixels

double Y: origin point ordinate, in pixels, top-down

wchar_t* Label: the text string

Method Graph::Text: draws an ASCII text string using integer coordinates

static void Text(const Site& S, const wchar_t* Label);

Site& S: origin point coordinates, in pixels

wchar_t* Label: the text string

Method Graph::Text: draws an ASCII text string using integer coordinates

static void Text(const XY& S, const wchar_t* Label);

XY& S: origin point coordinates, in pixels

wchar_t* Label: the text string


Member of the class Graph - Graphics Primitives

Method Graph::Handle: draws a dragging handle

static void Handle(double X, double Y, bool Round = true, int Size = 5);

double X: center point abscissa, in pixels

double Y: center point ordinate, in pixels, top-down

bool Round: when true, the handle is round, else it is square

int Size: Size of the handle (radius), in pixels; the default is 5

Method Graph::Handle: draws a dragging handle

static void Handle(const Site& S, bool Round = true, int Size = 5);

Site& S: center point coordinates, in pixels

bool Round: when true, the handle is round, else it is square

int Size: Size of the handle (radius), in pixels; the default is 5

Method Graph::Handle: draws a dragging handle

static void Handle(const XY& S, bool Round = true, int Size = 5);

XY& S: center point coordinates, in pixels

bool Round: when true, the handle is round, else it is square

int Size: Size of the handle (radius), in pixels; the default is 5


Member of the class Graph - Graphics Primitives

Method Graph::Distance: draw the Euclidean distance between two points (+ overloads)

static void Distance(const XY& P, const XY& Q, bool Label = true);

XY& P: the given point

XY& Q: the other point

bool Label: when true, as by default, the arrow is annotated with the numerical value of the distance

Method Graph::Distance: draw the Euclidean distance between a point and a line segment

static void Distance(const XY& P, const XY& Beg, const XY& End, bool Label = true, bool ExtensionLine = true);

XY& P: the given point

XY& Beg: starting point of the given line segment

XY& End: ending point of the given line segment

bool Label: when true, as by default, the arrow is annotated with the numerical value of the distance

bool ExtensionLine: when true, as by default, extension lines are drawn to lengthen the line segment(s) if required

Method Graph::Distance: draw the Euclidean distance between a point and a circle

static void Distance(const XY& P, const XY& Center, double Radius, bool Label = true);

XY& P: the given point

XY& Center: center of the given circle

double Radius: radius of the given circle

bool Label: when true, as by default, the arrow is annotated with the numerical value of the distance

Method Graph::Distance: draw the Euclidean distance between two line segments (average value)

static void Distance(const XY& Beg, const XY& End, const XY& Beg1, const XY& End1, bool Label = true);

XY& Beg: starting point of the given line segment

XY& End: ending point of the given line segment

XY& Beg1: starting point of the other line segment

XY& End1: ending point of the other line segment

bool Label: when true, as by default, the arrow is annotated with the numerical value of the distance

Method Graph::Distance: draw the Euclidean distance between a line segment and a circle

static void Distance(const XY& Beg, const XY& End, const XY& Center, double Radius, bool Label = true, bool ExtensionLine = true);

XY& Beg: starting point of the given line segment

XY& End: ending point of the given line segment

XY& Center: center of the given circle

double Radius: radius of the given circle

bool Label: when true, as by default, the arrow is annotated with the numerical value of the distance

bool ExtensionLine: when true, as by default, extension lines are drawn to lengthen the line segment(s) if required

Method Graph::Distance: draw the Euclidean distance between two circles

static void Distance(const XY& Center, double Radius, const XY& Center1, double Radius1, bool Label = true);

XY& Center: center of the given circle

double Radius: radius of the given circle

XY& Center1: center of the other circle

double Radius1: radius of the other circle

bool Label: when true, as by default, the arrow is annotated with the numerical value of the distance


Member of the class Graph - Graphics Primitives

Method Graph::Angle: draw the clockwise angle formed by three points (+ overloads)

static void Angle(const XY& P, const XY& Q, const XY& R, bool Label = true, bool Sides = true);

XY& P: angle apex

XY& Q: angle side vertex

XY& R: other angle side vertex

bool Label: when true, as by default, the arrow is annotated with the numerical value of the angle

bool Sides: when true, as by default, the angle sides are drawn too

Method Graph::Angle: draw the clockwise angle formed by two line segments

static void Angle(const XY& Beg, const XY& End, const XY& Beg1, const XY& End1, bool Label = true, bool ExtensionLines = true);

XY& Beg: starting point of the given line segment (side of the angle)

XY& End: ending point of the given line segment (side of the angle)

XY& Beg1: starting point of the other line segment (side of the angle)

XY& End1: ending point of the other line segment (side of the angle)

bool Label: when true, as by default, the arrow is annotated with the numerical value of the angle

bool ExtensionLines: when true, as by default, extension lines are drawn to materialize the angle apex


Member of the class Graph - Graphics Primitives

Method Graph::Color: returns the value of a given predefined color

static const RgbPixel Color(int Index);

returned RgbPixel: RGB components of the color

int Index: zero-based index value to access a list of items


Member of the class Graph - Graphics Primitives

Method Graph::EraseWindow: Fill the current Window with a solid color to erase it

static void EraseWindow(PredefinedColors Color = Black);

PredefinedColors Color: filling color; black by default


Member of the class Graph - Graphics Primitives

Method Graph::ZoomToWindow: adjust the zoom factor so that the given image size fits in the display window

static void ZoomToWindow(Site& ImageSize, bool OutOnly = true);

Site& ImageSize: Width and Height of the image to be fitted

bool OutOnly: When true, zoom-in is not performed, i.e. small images are not enlarged, only large ones are shrunk; false by default


Member of the class Graph - Graphics Primitives

Method Graph::WaitClose: block until the graphics window is closed by the GUI

static void WaitClose();


Enumeration

Enum PredefinedBehaviors: action to be taken when an error condition arises

Case IgnoreIt: nothing is done

Case ThrowIt: an exception of type Status is thrown

Case ShowIt: an error message appears in a message box

Case PrintIt: an error message is displayed on the standard output (console)

Case AssertIt: a debugger assertion is triggered

Case BehaviorCount: RESERVED


Enumeration

Enum SIMDLevels: Vector instruction sets

Case NoSIMD: None

Case SIMDMMX: MMX

Case SIMDSSE: SSE

Case SIMDSSE2: SSE2

Case SIMDSSE3: SSE3

Case SIMDSSE4: SSE4

Case SIMDAVX: AXV

Case SIMDAVX2: AVX2

Case SIMDAVX512: AVX512

Case SIMDNEONv7: ARMv7 NEON

Case SIMDNEONv8: ARMv8 NEON


Class Status

The class that handles global features such as the error status, the drawing context, stopwatches...

Error Processing

Property Error: the error code of the last failing operation

Property AsciiError: the verbose error message of the last failing operation

Property UnicodeError: the verbose error message of the last failing operation

Property AsciiFunction: gives the name of the function where the last failure arose

Property UnicodeFunction: gives the name of the function where the last failure arose

Method ErrorBehavior: set the error condition behavior

Property ErrorCallback: when an error condition is raised, this user-definable callback function is invoked

Property ErrorContext: pointer to user-defined context data which is passed to the error handling function

Method Raise: reserved for internal use

Angle Unit

Property AngleUnit: a conversion factor applied to angles, from the desired unit to radians. The FromDegrees and FromRadians predefined factors are available

Property FromDegrees: set the AngleUnit property to work with angles in degrees

Property FromRadians: set the AngleUnit property to work with angles in radians

Property UnitAngle: a reverse conversion factor applied to angles, from radians to the desired unit. The ToDegrees and ToRadians predefined factors are available

Property ToDegrees: conversion factor of radians to degrees

Property ToRadians: conversion factor of radians to radians; reserved for interna use

Timing

Method StartWatch: start a stopwatch

Method ReadWatch: get the elapsed time of a stopwatch

Method Timeout: initiate a timeout sequence

Method Expired: query to test expiry of a timeout delay

Method Wait: suspend the process for the given duration

Property SIMDLevel: Vector instruction set supported by the machine

Keypress

Method Key: return the code of the last key pressed

Versioning

Property UnicodeVersion: the current version of the software (major.minor format), as an UNICODE character string

Property AsciiVersion: the current version of the software (major.minor format), as an ASCII character string

Multithreading

Method AttachThread: forces the creation of thread-related resources; can be called once by each thread of the application

Method ReleaseThread: forces the release of thread-related resources; should be called once by each thread of the application to avoid memory leaks at shutdown

Method EnterSection: enter a critical section for mutual exclusion to ensure thread-safe operation

Method LeaveSection: exits the critical section

Data Storage

Property Shallow: reserved for internal use

Method License: refresh the license status; can be used to test dongle presence

Miscellaneous

Property JpegQuality: quality parameter used for saving images under the JPEG format, in range [0..100]; 85 by default

Property RgbLumaDefault: specifies how conversions from Rgb images to Gray are to be performed, using one of Value_HSV (default), Lightness_HLS or Luma_YUV


Member of the class Status - Error Processing

Property ErrorCodes& Status::Error(): the error code of the last failing operation


Member of the class Status - Error Processing

Property char* Status::AsciiError(): the verbose error message of the last failing operation


Member of the class Status - Error Processing

Property wchar_t* Status::UnicodeError(): the verbose error message of the last failing operation


Member of the class Status - Error Processing

Property char* Status::AsciiFunction(): gives the name of the function where the last failure arose


Member of the class Status - Error Processing

Property wchar_t* Status::UnicodeFunction(): gives the name of the function where the last failure arose


Member of the class Status - Error Processing

Method Status::ErrorBehavior: set the error condition behavior

static void ErrorBehavior(enum PredefinedBehaviors Behavior);

PredefinedBehaviors Behavior: desired behavior, as enumerated in PredefinedBehaviors; ShowIt by default


Member of the class Status - Error Processing

Property Callback Status::ErrorCallback: when an error condition is raised, this user-definable callback function is invoked


Member of the class Status - Error Processing

Property void* Status::ErrorContext: pointer to user-defined context data which is passed to the error handling function


Member of the class Status - Error Processing

Method Status::Raise: reserved for internal use

static bool Raise(enum ErrorCodes Code, const char Function[] = 0);

returned bool: true when there is an error condition

ErrorCodes Code: error condition code from the last failing operation, as enumerated in ErrorCodes

char* Function: name of the calling function


Member of the class Status - Angle Unit

Property double Status::AngleUnit: a conversion factor applied to angles, from the desired unit to radians. The FromDegrees and FromRadians predefined factors are available


Member of the class Status - Angle Unit

Property double Status::FromDegrees: set the AngleUnit property to work with angles in degrees


Member of the class Status - Angle Unit

Property double Status::FromRadians: set the AngleUnit property to work with angles in radians


Member of the class Status - Angle Unit

Property double Status::UnitAngle: a reverse conversion factor applied to angles, from radians to the desired unit. The ToDegrees and ToRadians predefined factors are available


Member of the class Status - Angle Unit

Property double Status::ToDegrees: conversion factor of radians to degrees


Member of the class Status - Angle Unit

Property double Status::ToRadians: conversion factor of radians to radians; reserved for interna use


Member of the class Status - Timing

Method Status::StartWatch: start a stopwatch

static void StartWatch(int Index = 0, bool Accumulate = false);

int Index: index of the desired stopwatch, between 0 and 10 exclusive

bool Accumulate: when true, continues timing from the last stop; otherwise, restarts timing from 0


Member of the class Status - Timing

Method Status::ReadWatch: get the elapsed time of a stopwatch

static int ReadWatch(int Index = 0, bool Current = true);

returned int: the elapsed time since the previous StartWatch call, in microseconds

int Index: index of the desired stopwatch, between 0 and 10 exclusive

bool Current: when true, the current time is used to compute the time lapse; otherwise, the time from the previous ReadWatch call is used


Member of the class Status - Timing

Method Status::Timeout: initiate a timeout sequence

static void Timeout(int Index, int Delay);

int Index: zero-based index value to access a list of items

int Delay: timeout duration, in microseconds


Member of the class Status - Timing

Method Status::Expired: query to test expiry of a timeout delay

static bool Expired(int Index);

returned bool: true when the delay has elapsed

int Index: zero-based index value to access a list of items


Member of the class Status - Timing

Method Status::Wait: suspend the process for the given duration

static void Wait(double Delay);

double Delay: waiting time, in seconds; granularity is system dependent


Member of the class Status - Timing

Property SIMDLevels Status::SIMDLevel: Vector instruction set supported by the machine


Member of the class Status - Keypress

Method Status::Key: return the code of the last key pressed

static int Key(bool Wait = true);

returned int: ASCII key code

bool Wait: when true, the function blocks until a key is pressed; when false, returns immediately with the last key or zero


Member of the class Status - Versioning

Property wchar_t* Status::UnicodeVersion: the current version of the software (major.minor format), as an UNICODE character string


Member of the class Status - Versioning

Property char* Status::AsciiVersion: the current version of the software (major.minor format), as an ASCII character string


Member of the class Status - Multithreading

Method Status::AttachThread: forces the creation of thread-related resources; can be called once by each thread of the application

static void AttachThread();


Member of the class Status - Multithreading

Method Status::ReleaseThread: forces the release of thread-related resources; should be called once by each thread of the application to avoid memory leaks at shutdown

static void ReleaseThread();


Member of the class Status - Multithreading

Method Status::EnterSection: enter a critical section for mutual exclusion to ensure thread-safe operation

static void EnterSection();


Member of the class Status - Multithreading

Method Status::LeaveSection: exits the critical section

static void LeaveSection();


Member of the class Status - Data Storage

Property bool Status::Shallow: reserved for internal use


Member of the class Status - Data Storage

Method Status::License: refresh the license status; can be used to test dongle presence

static bool License(int& Type, int& Version, int& Mask, bool& Temporary);

returned bool: true when some license is granted (plain or temporary)

int& Type: license support; undocumented, contact the Technical Support

int& Version: licensed software version; undocumented, contact the Technical Support

int& Mask: licensed modules; undocumented, contact the Technical Support

bool& Temporary: true when the license is granted temporarily


Member of the class Status - Miscellaneous

Property int Status::JpegQuality: quality parameter used for saving images under the JPEG format, in range [0..100]; 85 by default


Member of the class Status - Miscellaneous

Property ColorComponents Status::RgbLumaDefault: specifies how conversions from Rgb images to Gray are to be performed, using one of Value_HSV (default), Lightness_HLS or Luma_YUV


Enumeration

Enum GrayClipping: arithmetic rule to be used when a pixel value goes out of the representable range

Case Saturate: the value is clamped to the representable range

Case Absolute: negative values are turned to positive

Case Negative: positive values are clamped to zero

Case Rescale: a rescaling of the output range is applied; this rescaling is operation-dependent


Class Quad

A straight or curved rectangle that defines an area of interest, from which pixels can be resampled

Corner/Center Coordinates

Property X: abscissa of the origin or center point of the area of interest

Property Y: ordinate of the origin or center point of the area of interest

Width/Radius, Height

Property W: width or radius of the area of interest, in pixels (straight or curved); for a curved zone, the middle arc is used

Property H: height of the area of interest, in pixels

Angle

Property A: direction angle of the top side of the area of interest, in radians, between 0 and one turn

Bend (0 for straight)

Property B: bending angle the area of interest, in radians, between one negative turn and one positive turn

Attributes

Property Aligned: when true, the area of interest is straight and has horizontal and vertical sides

Property Thin: when true, the area of interest degenerates to a line segment/circular arc, by having a zero height

Property Curved: when true, the area of interest is curved rather than straight

Property FullCircle: when true, the area of interest, if curved, has a bending angle corresponding to a full circle, i.e. minus one turn or plus one turn and the zone is a ring or a disk

Property FullRadius: when true, the smallest arc of the curve degenerates to the center point and the zone is a wedge or a disk

Property Middle: when true, the area of interest can be dragged around its middle edge rather than its top and bottom edges

Property OriginPoint: top-left corner of the area of interest

Property MiddlePoint: meeting point of the medians of the area of interest

Axis-aligned Rectangle

Method Set: locate the area of interest at a given origin point (upper-left corner), with a given size

Rotated Rectangle/Wedge at a Given Corner Point

Method SetOrigin: locate the area of interest at a given origin point (upper-left corner)

Rotated Rectangle/Wedge at a Given Middle Point

Method SetMiddle: locate the area of interest at a given middle point (meeting point of the medians)

Wedge Centered at a Given Point, Size and Aperture

Method SetCenter: locate the area of interest at a given center point (curvature center - pertains to curved zones only)

Wedge Centered at a Given Point, Radii and Delimiting Angles

Method SetWedge: locate the area of interest at a given center point (curvature center - pertains to curved zones only)

Full Circle Centered at a Given Point

Image Sampling

Method Sample: resample the inside of the area of interest, giving a new image

Graphics

Method Draw: draw the outline of the area of interest, possibly decorated with handles and anchors

Property Handle: identity of the last handle/anchor that was hit, as defined by enum DraggingHandles

Property HandleOctant: approximate orientation of the last handle/anchor that was hit; used for selecting a relevant cursor

Method HitHandle: checks if the cursor is placed over a dragging handle or anchor

Method Drag: move or resize the area of interest by pulling the last handle or anchor that was hit


Member of the class Quad - Corner/Center Coordinates

Property double Quad::X: abscissa of the origin or center point of the area of interest


Member of the class Quad - Corner/Center Coordinates

Property double Quad::Y: ordinate of the origin or center point of the area of interest


Member of the class Quad - Width/Radius, Height

Property double Quad::W: width or radius of the area of interest, in pixels (straight or curved); for a curved zone, the middle arc is used


Member of the class Quad - Width/Radius, Height

Property double Quad::H: height of the area of interest, in pixels


Member of the class Quad - Angle

Property double Quad::A: direction angle of the top side of the area of interest, in radians, between 0 and one turn


Member of the class Quad - Bend (0 for straight)

Property double Quad::B: bending angle the area of interest, in radians, between one negative turn and one positive turn


Member of the class Quad - Attributes

Property bool Quad::Aligned: when true, the area of interest is straight and has horizontal and vertical sides


Member of the class Quad - Attributes

Property bool Quad::Thin: when true, the area of interest degenerates to a line segment/circular arc, by having a zero height


Member of the class Quad - Attributes

Property bool Quad::Curved: when true, the area of interest is curved rather than straight


Member of the class Quad - Attributes

Property bool Quad::FullCircle: when true, the area of interest, if curved, has a bending angle corresponding to a full circle, i.e. minus one turn or plus one turn and the zone is a ring or a disk


Member of the class Quad - Attributes

Property bool Quad::FullRadius: when true, the smallest arc of the curve degenerates to the center point and the zone is a wedge or a disk


Member of the class Quad - Attributes

Property bool Quad::Middle: when true, the area of interest can be dragged around its middle edge rather than its top and bottom edges


Member of the class Quad - Attributes

Property XY Quad::OriginPoint(): top-left corner of the area of interest


Member of the class Quad - Attributes

Property XY Quad::MiddlePoint(): meeting point of the medians of the area of interest


Member of the class Quad - Axis-aligned Rectangle

Method Quad::Set: locate the area of interest at a given origin point (upper-left corner), with a given size

void Set(int XLeft, int YTop, int Width, int Height);

int XLeft: abscissa of the origin point

int YTop: ordinate of the origin point

int Width: number of pixels, horizontally

int Height: number of pixels, vertically


Member of the class Quad - Rotated Rectangle/Wedge at a Given Corner Point

Method Quad::SetOrigin: locate the area of interest at a given origin point (upper-left corner)

void SetOrigin(double Xo, double Yo, double Width, double Height, double Angle, double Bend = 0);

double Xo: abscissa of the origin point

double Yo: ordinate of the origin point

double Width: horizontal extent of the area of interest, in pixels; for a curved zone, the middle arc is used

double Height: vertical extent of the area of interest, in pixels

double Angle: direction angle of the top side of the area of interest, in the current angle unit

double Bend: bending angle the area of interest, in the current angle unit


Member of the class Quad - Rotated Rectangle/Wedge at a Given Middle Point

Method Quad::SetMiddle: locate the area of interest at a given middle point (meeting point of the medians)

void SetMiddle(double Xm, double Ym, double Width, double Height, double Angle, double Bend = 0);

double Xm: abscissa of the middle point

double Ym: ordinate of the middle point

double Width: horizontal extent of the area of interest, in pixels; for a curved zone, the middle arc is used

double Height: vertical extent of the area of interest, in pixels

double Angle: direction angle of the top side of the area of interest, in the current angle unit

double Bend: bending angle the area of interest, in the current angle unit


Member of the class Quad - Wedge Centered at a Given Point, Size and Aperture

Method Quad::SetCenter: locate the area of interest at a given center point (curvature center - pertains to curved zones only)

void SetCenter(double Xc, double Yc, double Width, double Height, double Angle, double Bend);

double Xc: abscissa of the center point

double Yc: ordinate of the center point

double Width: horizontal extent of the area of interest, in pixels; for a curved zone, the middle arc is used

double Height: vertical extent of the area of interest, in pixels

double Angle: direction angle of the top side of the area of interest, in the current angle unit

double Bend: bending angle the area of interest, in the current angle unit


Member of the class Quad - Wedge Centered at a Given Point, Radii and Delimiting Angles

Method Quad::SetWedge: locate the area of interest at a given center point (curvature center - pertains to curved zones only)

void SetWedge(double Xc, double Yc, double InnerRadius, double OuterRadius, double BegAngle, double EndAngle);

double Xc: abscissa of the center point

double Yc: ordinate of the origin point

double InnerRadius: inner wedge radius

double OuterRadius: outer wedge radius

double BegAngle: direction angle of the first radial side, in the current angle unit

double EndAngle: direction angle of the second radial side, in the current angle unit


Member of the class Quad - Image Sampling

Method Quad::Sample: resample the inside of the area of interest, giving a new image

void Sample(const Image& Src, Image& Dst, bool Interpolate = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Quad - Graphics

Method Quad::Draw: draw the outline of the area of interest, possibly decorated with handles and anchors

void Draw(bool Anchors = false, bool Handles = false);

bool Anchors: when true, the dragging anchors are drawn too; the allow rotating and bending the area of interest

bool Handles: when true, the dragging handles are drawn too


Member of the class Quad - Graphics

Property DraggingHandles Quad::Handle: identity of the last handle/anchor that was hit, as defined by enum DraggingHandles


Member of the class Quad - Graphics

Property int Quad::HandleOctant: approximate orientation of the last handle/anchor that was hit; used for selecting a relevant cursor


Member of the class Quad - Graphics

Method Quad::HitHandle: checks if the cursor is placed over a dragging handle or anchor

enum DraggingHandles HitHandle(double XCursor, double YCursor, bool Anchors = true);

returned DraggingHandles: identity of the handle/anchor that was hit, as defined by enum DraggingHandles

double XCursor: abscissa of the mouse cursor, in pixels

double YCursor: ordinate of the mouse cursor, in pixels

bool Anchors: when true, the dragging anchors are detected


Member of the class Quad - Graphics

Method Quad::Drag: move or resize the area of interest by pulling the last handle or anchor that was hit

void Drag(double XCursor, double YCursor, int Width = 0, int Height = 0);

double XCursor: abscissa of the mouse cursor, in pixels

double YCursor: ordinate of the mouse cursor, in pixels

int Width: number of pixels, horizontally

int Height: number of pixels, vertically

Method Quad::Drag: move or resize the area of interest by pulling the last handle or anchor that was hit; the limits of the passed image cannot be crossed

void Drag(double XCursor, double YCursor, const Image& Src);

double XCursor: abscissa of the mouse cursor, in pixels

double YCursor: ordinate of the mouse cursor, in pixels

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Enumeration

Enum ColorComponents: colorimetric type of the pixels

Case Red_RGB: red component in the RGB color system

Case Green_RGB: green component in the RGB color system

Case Blue_RGB: blue component in the RGB color system

Case Hue_HLS: hue (tint) of the HLS color system

Case Lightness_HLS: lightness (brightness) of the HLS color system

Case Saturation_HLS: saturation (vividness) of the HSV color system

Case Hue_HSV: hue (tint) of the HSV color system

Case Saturation_HSV: saturation (vividness) of the HLS color system

Case Value_HSV: value (brightness) of the HSV color system

Case Luma_YUV: luminance in the CCIR/ITU.601 YUV color system

Case ChromaU_YUV: U chrominance in the CCIR/ITU.601 color system

Case ChromaV_YUV: V chrominance in the CCIR/ITU.601 color system

Case X_XYZ: X primary in the CIE XYZ color system

Case Y_XYZ: Y primary in the CIE XYZ color system

Case Z_XYZ: Z primary in the CIE XYZ color system

Case xx_XYZ: x chromaticity in the CIE XYZ color system: X / (X+Y+Z)

Case yy_XYZ: y chromaticity in the CIE XYZ color system: Y / (X+Y+Z)

Case zz_XYZ: z chromaticity in the CIE XYZ color system: Z / (X+Y+Z)

Case Alpha: transparency plane in Rgba images


Enumeration

Enum BayerAlignments: colors of the two leftmost pixels of the top row in a Bayer coded image, for synchronization

Case RedGreen: RGRGRG / GBGBGB / RGRGRG / GBGBGB / ...

Case GreenRed: GRGRGR / BGBGBG / GRGRGR / BGBGBG / ...

Case GreenBlue: GBGBGB / RGRGRG / GBGBGB / RGRGRG / ...

Case BlueGreen: BGBGBG / GRGRGR / BGBGBG / GRGRGR / ...


Enumeration

Enum BayerQualities: selection of the demosaicing algorithm, with a tradeoff between quality and running time

Case FastRgb: Rgb output; bilinear interpolation; fast but produces color artefacts along edges; the default

Case SmoothRgb: Rgb output; improved interpolation with reduced color artefacts along edges

Case SharpRgb: Rgb output; improved interpolation with reduced color artefacts along edges and better sharpness

Case SmoothGray: Gray output; improved interpolation

Case SharpGray: Gray output; improved interpolation with better sharpness


Enumeration

Enum Binarization: specifies the rule used to assign the output values to background and foreground pixels

Case Binary: black or white; this performs hard thresholding

Case Means: the average gray-levels of the pixels below and above the threshold; this flattens the background and foreground

Case Soft: a continuous ramp of grays mapped between the background and foreground intensities; this is soft thresholding

Case ToGray1: the output image will be binary, 1 bpp


Class Operator

The Operator class defines arithmetic and logical operations that are performed pixel-by-pixel between images. For instance the sum of two images is an image where every pixel is the sum of the corresponding pixels in two source images. Instead of a source image, a constant value can also be used

Copy

Method Copy: pixel-by-pixel copy of a constant to an image

Method Copy: pixel-by-pixel copy of a constant to an image

Color

Method Invert: negative

Method Convert: pixel-by-pixel copy with color conversion

Method RedBlueSwap: converts between the RGB and BGR image storage formats

Method DeBayer: perform a Bayer demosaicing of the grayscale input, yielding a true color output

Method ColorsLighten: increases the lightness of all pixels of a color image to the maximum value, removing all shading

Method ColorsSaturate: increases the saturation of all pixels of a color image to the maximum value

Method ColorsHueSet: changes the hue of all pixels of a color image

Image Arithmetic

Method Add: pixel-by-pixel addition, constant plus image

Method Subtract: pixel-by-pixel subtraction, constant minus image

Method Multiply: pixel-by-pixel multiplication, constant times image

Method Divide: pixel-by-pixel division, constant over image

Method Maximize: pixel-by-pixel largest value, maximum of constant and image

Method Minimize: pixel-by-pixel smallest value, minimum of constant and image

Method Blend: linearly combines two images using two complementary weights: Alpha . A + (1 - Alpha) . B

Compare

Method EqualTest: pixel-by-pixel bitwise comparison for strict equality, between constant and image

Method GreaterTest: pixel-by-pixel bitwise comparison for greater-than inequality, between constant and image

Method GreaterTest: pixel-by-pixel bitwise comparison for greater-than inequality, between two images

Method GreaterEqualTest: pixel-by-pixel bitwise comparison for greater-or-equal inequality, between constant and image

Method GreaterEqualTest: pixel-by-pixel bitwise comparison for greater-or-equal inequality, between two images

Bitwise

Method And: pixel-by-pixel bitwise constant and image

Method Or: pixel-by-pixel bitwise constant or image

Method Xor: pixel-by-pixel bitwise constant exclusive-or image

Binarize

Method Binarize: turns a grayscale image to a binary one by thresholding

Method Binarize: turns a grayscale image to a binary one by thresholding; the threshold value is computed locally as the average in a sliding window, offset with the Noise value

Correct Shading

Method AddCorrect: corrects the shading of the source image by comparing to a uniform reference, using a one-point additive rule

Method MultiplyCorrect: corrects the shading of the source image by comparing to a uniform reference, using a one-point multiplicative rule

Method Correct: corrects the shading of the source image by comparing to two uniform references, using a two-point linear rule

Scale Grays

Method GainOffset: define a linear transform, i.e. a gain followed by an offset

Method Normalize: applies linear contrast stretching to standardize it to predefined values

Method Equalize: redistributes the gray-levels in an image in such a way that its histogram becomes flat; this is a classical process that greatly improves the visual contrast

Method Transform: applies a pixel-by-pixel grayscale transform such as histogram stretching, defined by means of a lookup-table

Property GrayDepth: tells the actual number of significant bits used with Gray16 images; between 9 and 16 inclusive

Profile Arithmetic

Method Add: sample-by-sample addition, constant plus profile

Method Subtract: sample-by-sample subtraction, profile minus constant

Method Multiply: sample-by-sample multiplication, constant times profile

Method Divide: sample-by-sample division, profile over constant

Method Maximize: sample-by-sample largest value, maximum of constant and profile

Method Minimize: sample-by-sample smallest value, minimum of constant and profile


Member of the class Operator - Copy

Method Operator::Copy: pixel-by-pixel copy of a constant to an image

static void Copy(int Const, Image& Dst);

int Const: a constant value used as the first source argument

Image& Dst: the destination image, which is computed by this operation

Method Operator::Copy: pixel-by-pixel copy the source image to the destination image with type conversion if requested

static void Copy(RgbPixel Const, Image& Dst);

RgbPixel Const: a constant value used as the first source argument

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Copy

Method Operator::Copy: pixel-by-pixel copy of a constant to an image

static void Copy(RgbaPixel Const, Image& Dst);

RgbaPixel Const: a constant value used as the first source argument

Image& Dst: the destination image, which is computed by this operation

Method Operator::Copy: pixel-by-pixel copy of a constant to an image

static void Copy(const Image& Src, Image& Dst, enum PixelTypes DstType = Undefined);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Undefined, Gray, Gray16, Gray32, Rgb, Rgba

Image& Dst: the destination image, which is computed by this operation

PixelTypes DstType: specifies the desired destination image type; if Undefined, the current destination image type is kept


Member of the class Operator - Color

Method Operator::Invert: negative

static void Invert(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Color

Method Operator::Convert: pixel-by-pixel copy with color conversion

static void Convert(const Image& Src, Image& Dst, ColorComponents Component = Red_RGB);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

Image& Dst: the destination image, which is computed by this operation

ColorComponents Component: color plane(s) in the destination image, as enumerated in ColorComponents


Member of the class Operator - Color

Method Operator::RedBlueSwap: converts between the RGB and BGR image storage formats

static void RedBlueSwap(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Color

Method Operator::DeBayer: perform a Bayer demosaicing of the grayscale input, yielding a true color output

static void DeBayer(const Image& Src, Image& Dst, BayerAlignments TopLeft = RedGreen, BayerQualities Quality = SharpRgb);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation; Rgb

BayerAlignments TopLeft: color of the pair of pixels at the top-left corner of the image; RedGreen by default

BayerQualities Quality: demosaicing algorithm and output type


Member of the class Operator - Color

Method Operator::ColorsLighten: increases the lightness of all pixels of a color image to the maximum value, removing all shading

static void ColorsLighten(const Image& Src, Image& Dst, int Black = 10);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

int Black: colors with a lightness under this value are considered black


Member of the class Operator - Color

Method Operator::ColorsSaturate: increases the saturation of all pixels of a color image to the maximum value

static void ColorsSaturate(const Image& Src, Image& Dst, int Black = 10);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

int Black: colors with a lightness under this value are considered black


Member of the class Operator - Color

Method Operator::ColorsHueSet: changes the hue of all pixels of a color image

static void ColorsHueSet(int Hue, const Image& Src, Image& Dst);

int Hue: desired hue value

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Image Arithmetic

Method Operator::Add: pixel-by-pixel addition, constant plus image

static void Add(int Const, const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the sum operator

Method Operator::Add: pixel-by-pixel addition, image plus image

static void Add(const Image& Src, const Image& SrcB, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the sum operator


Member of the class Operator - Image Arithmetic

Method Operator::Subtract: pixel-by-pixel subtraction, constant minus image

static void Subtract(int Const, const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate, Absolute and Rescale for the difference operator

Method Operator::Subtract: pixel-by-pixel subtraction, image minus constant

static void Subtract(const Image& Src, int Const, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

int Const: a constant value used as the first source argument

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate, Absolute and Rescale for the difference operator

Method Operator::Subtract: sample-by-sample subtraction, constant minus profile

static void Subtract(const Image& Src, const Image& SrcB, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate, Absolute and Rescale for the difference operator


Member of the class Operator - Image Arithmetic

Method Operator::Multiply: pixel-by-pixel multiplication, constant times image

static void Multiply(double Const, const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

double Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the product operator

Method Operator::Multiply: pixel-by-pixel multiplication, image times image

static void Multiply(const Image& Src, const Image& SrcB, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the product operator


Member of the class Operator - Image Arithmetic

Method Operator::Divide: pixel-by-pixel division, constant over image

static void Divide(double Const, const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

double Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the quotient operator

Method Operator::Divide: pixel-by-pixel division, image over constant

static void Divide(const Image& Src, double Const, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

double Const: a constant value used as the first source argument

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the quotient operator

Method Operator::Divide: sample-by-sample division, constant over profile

static void Divide(const Image& Src, const Image& SrcB, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the quotient operator


Member of the class Operator - Image Arithmetic

Method Operator::Maximize: pixel-by-pixel largest value, maximum of constant and image

static void Maximize(int Const, const Image& Src, Image& Dst);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

Method Operator::Maximize: pixel-by-pixel largest value, maximum of two images

static void Maximize(const Image& Src, const Image& SrcB, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Image Arithmetic

Method Operator::Minimize: pixel-by-pixel smallest value, minimum of constant and image

static void Minimize(int Const, const Image& Src, Image& Dst);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

Method Operator::Minimize: pixel-by-pixel smallest value, minimum of two images

static void Minimize(const Image& Src, const Image& SrcB, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Image Arithmetic

Method Operator::Blend: linearly combines two images using two complementary weights: Alpha . A + (1 - Alpha) . B

static void Blend(double Alpha, const Image& Src, const Image& SrcB, Image& Dst);

double Alpha: weight applied to the first source image; 1 - Alpha is applied to the second image

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Compare

Method Operator::EqualTest: pixel-by-pixel bitwise comparison for strict equality, between constant and image

static void EqualTest(int Const, const Image& Src, Image& Dst, int Black = 0, int White = ~0);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

int Black: color assigned to false pixels, i.e. those that do not satisfy the equality

int White: color assigned to true pixels, i.e. those that satisfy the equality

Method Operator::EqualTest: pixel-by-pixel bitwise comparison for strict equality, between two images

static void EqualTest(const Image& Src, const Image& SrcB, Image& Dst, int Black = 0, int White = ~0);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

int Black: color assigned to false pixels, i.e. those that do not satisfy the equality

int White: color assigned to true pixels, i.e. those that satisfy the equality


Member of the class Operator - Compare

Method Operator::GreaterTest: pixel-by-pixel bitwise comparison for greater-than inequality, between constant and image

static void GreaterTest(int Const, const Image& Src, Image& Dst, int Black = 0, int White = ~0);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

int Black: color assigned to false pixels, i.e. those that do not satisfy the greater-than condition

int White: color assigned to true pixels, i.e. those that satisfy the greater-than condition

Method Operator::GreaterTest: pixel-by-pixel bitwise comparison for greater-than inequality, between image and constant

static void GreaterTest(const Image& Src, int Const, Image& Dst, int Black = 0, int White = ~0);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

int Const: a constant value used as the first source argument

Image& Dst: the destination image, which is computed by this operation

int Black: color assigned to false pixels, i.e. those that do not satisfy the greater-than condition

int White: color assigned to true pixels, i.e. those that satisfy the greater-than condition


Member of the class Operator - Compare

Method Operator::GreaterTest: pixel-by-pixel bitwise comparison for greater-than inequality, between two images

static void GreaterTest(const Image& Src, const Image& SrcB, Image& Dst, int Black = 0, int White = ~0);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

int Black: color assigned to false pixels, i.e. those that do not satisfy the greater-than condition

int White: color assigned to true pixels, i.e. those that satisfy the greater-than condition


Member of the class Operator - Compare

Method Operator::GreaterEqualTest: pixel-by-pixel bitwise comparison for greater-or-equal inequality, between constant and image

static void GreaterEqualTest(int Const, const Image& Src, Image& Dst, int Black = 0, int White = ~0);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

int Black: color assigned to false pixels, i.e. those that do not meet the condition

int White: color assigned to true pixels, i.e. those that meet the condition

Method Operator::GreaterEqualTest: pixel-by-pixel bitwise comparison for greater-or-equal inequality, between image and constant

static void GreaterEqualTest(const Image& Src, int Const, Image& Dst, int Black = 0, int White = ~0);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

int Const: a constant value used as the first source argument

Image& Dst: the destination image, which is computed by this operation

int Black: color assigned to false pixels, i.e. those that do not meet the condition

int White: color assigned to true pixels, i.e. those that meet the condition


Member of the class Operator - Compare

Method Operator::GreaterEqualTest: pixel-by-pixel bitwise comparison for greater-or-equal inequality, between two images

static void GreaterEqualTest(const Image& Src, const Image& SrcB, Image& Dst, int Black = 0, int White = ~0);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

int Black: color assigned to false pixels, i.e. those that do not meet the condition

int White: color assigned to true pixels, i.e. those that meet the condition


Member of the class Operator - Bitwise

Method Operator::And: pixel-by-pixel bitwise constant and image

static void And(int Const, const Image& Src, Image& Dst);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

Method Operator::And: pixel-by-pixel bitwise image and image

static void And(const Image& Src, const Image& SrcB, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Bitwise

Method Operator::Or: pixel-by-pixel bitwise constant or image

static void Or(int Const, const Image& Src, Image& Dst);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

Method Operator::Or: pixel-by-pixel bitwise image or image

static void Or(const Image& Src, const Image& SrcB, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Bitwise

Method Operator::Xor: pixel-by-pixel bitwise constant exclusive-or image

static void Xor(int Const, const Image& Src, Image& Dst);

int Const: a constant value used as the first source argument

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

Method Operator::Xor: pixel-by-pixel bitwise image exclusive-or constant

static void Xor(const Image& Src, const Image& SrcB, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Binarize

Method Operator::Binarize: turns a grayscale image to a binary one by thresholding

static int Binarize(int Threshold, const Image& Src, Image& Dst, bool Above = true, Binarization Mode = Binary);

returned int: the computed threshold value

int Threshold: the desired threshold value

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

Image& Dst: the destination image, which is computed by this operation

bool Above: when true, the foreground pixels are those with a value above or on that of the threshold

Binarization Mode: specifies how the output values are assigned, as enumerated in Binarization

Method Operator::Binarize: turns a grayscale image to a binary one by thresholding; the threshold value is chosen by using a global optimization rule

static void Binarize(int Size, int Noise, const Image& Src, Image& Dst, bool Above = true);

int Size: Extent of the area that defines the scale of adaptiveness

int Noise: Threshold level corresponding to the noise amplitude; can be positive, null or negative

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

Image& Dst: the destination image, which is computed by this operation

bool Above: when true, the foreground pixels are those with a value above or on that of the threshold


Member of the class Operator - Binarize

Method Operator::Binarize: turns a grayscale image to a binary one by thresholding; the threshold value is computed locally as the average in a sliding window, offset with the Noise value

static void Binarize(GrayPixel Background, GrayPixel Foreground, const Image& Src, Image& Dst, bool Above = true, Binarization Mode = Binary);

GrayPixel Background: reference background gray-level

GrayPixel Foreground: reference foreground gray-level

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

Image& Dst: the destination image, which is computed by this operation

bool Above: when true, the foreground pixels are those with a value above or on that of the threshold

Binarization Mode: specifies how the output values are assigned, as enumerated in Binarization

Method Operator::Binarize: turns a grayscale image to a binary one by thresholding; the threshold value is chosen halfway of two specified shades of gray

static void Binarize(RgbPixel BackColor, RgbPixel ForeColor, const Image& Src, Image& Dst, bool Above = true, Binarization Mode = Binary);

RgbPixel BackColor: reference color that will map to black

RgbPixel ForeColor: reference color that will map to white

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

Image& Dst: the destination image, which is computed by this operation

bool Above: when true, the foreground pixels are those with a value above or on that of the threshold

Binarization Mode: specifies how the output values are assigned, as enumerated in Binarization

Method Operator::Binarize: turns a color image to a binary one by thresholding; the threshold value is chosen halfway of two specified colors

static void Binarize(RgbPixel ForeColor, RgbPixel Tolerance, const Image& Src, Image& Dst, Binarization Mode = Binary, bool Isotropic = false);

RgbPixel ForeColor: reference color that will map to white

RgbPixel Tolerance: tolerances on the color value for the foreground; out of tolerance, the color maps to black

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

Image& Dst: the destination image, which is computed by this operation

Binarization Mode: specifies how the output values are assigned, as enumerated in Binarization

bool Isotropic: when true, the tolerances are handled in a more isotropic way (sphere/ellipse instead of box)

Method Operator::Binarize: turns a grayscale image to a binary one by thresholding

static int Binarize(const Image& Src, Image& Dst, bool Above = true, Binarization Mode = Binary);

returned int: the computed threshold value

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

Image& Dst: the destination image, which is computed by this operation

bool Above: when true, the foreground pixels are those with a value above or on that of the threshold

Binarization Mode: specifies how the output values are assigned, as enumerated in Binarization


Member of the class Operator - Correct Shading

Method Operator::AddCorrect: corrects the shading of the source image by comparing to a uniform reference, using a one-point additive rule

static void AddCorrect(const Image& Src, const Image& SrcWhite, Image& Dst, int White = 0);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb (+ Gray or Rgb reference)

Image& SrcWhite: the reference image, which will map to white after correction; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

int White: white mapping value

Method Operator::AddCorrect: corrects the shading of the source image by comparing to a uniform reference, using a one-point additive rule

static void AddCorrect(const Image& Src, const Image& SrcWhite, Image& Dst, RgbPixel White);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb (+ Gray or Rgb reference)

Image& SrcWhite: the reference image, which will map to white after correction; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

RgbPixel White: white mapping value


Member of the class Operator - Correct Shading

Method Operator::MultiplyCorrect: corrects the shading of the source image by comparing to a uniform reference, using a one-point multiplicative rule

static void MultiplyCorrect(const Image& Src, const Image& SrcWhite, Image& Dst, int White = 255);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb (+ Gray or Rgb reference)

Image& SrcWhite: the reference image, which will map to white after correction; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

int White: white mapping value

Method Operator::MultiplyCorrect: corrects the shading of the source image by comparing to a uniform reference, using a one-point multiplicative rule

static void MultiplyCorrect(const Image& Src, const Image& SrcWhite, Image& Dst, RgbPixel White);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb (+ Gray or Rgb reference)

Image& SrcWhite: the reference image, which will map to white after correction; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

RgbPixel White: white mapping value


Member of the class Operator - Correct Shading

Method Operator::Correct: corrects the shading of the source image by comparing to two uniform references, using a two-point linear rule

static void Correct(const Image& Src, const Image& SrcBlack, const Image& SrcWhite, Image& Dst, int Black = 0, int White = 255);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb (+ Gray or Rgb reference)

Image& SrcBlack: the first reference image, which will map to black after correction; one of Gray, Gray16, Rgb

Image& SrcWhite: the second reference image, which will map to white after correction; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

int Black: black mapping value

int White: white mapping value

Method Operator::Correct: corrects the shading of the source image by comparing to two uniform references, using a two-point linear rule

static void Correct(const Image& Src, const Image& SrcBlack, const Image& SrcWhite, Image& Dst, RgbPixel Black, RgbPixel White);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb (+ Gray or Rgb reference)

Image& SrcBlack: the first reference image, which will map to black after correction; one of Gray, Gray16, Rgb

Image& SrcWhite: the second reference image, which will map to white after correction; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

RgbPixel Black: black mapping value

RgbPixel White: white mapping value


Member of the class Operator - Scale Grays

Method Operator::GainOffset: define a linear transform, i.e. a gain followed by an offset

static void GainOffset(double Gain, double Offset, const Image& Src, Image& Dst);

double Gain: floating-point gain

double Offset: integer offset added after multiplication the gain

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Scale Grays

Method Operator::Normalize: applies linear contrast stretching to standardize it to predefined values

static void Normalize(double Mean, double Variance, const Image& Src, Image& Dst);

double Mean: expected gray mean after stretching

double Variance: expected variance after stretching

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Scale Grays

Method Operator::Equalize: redistributes the gray-levels in an image in such a way that its histogram becomes flat; this is a classical process that greatly improves the visual contrast

static void Equalize(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation

Method Operator::Equalize: redistributes the gray-levels in an image in such a way that its histogram becomes flat; this is a classical process that greatly improves the visual contrast

static void Equalize(int FilterSize, const Image& Src, Image& Dst);

int FilterSize: adaptive version of the filter; it works in a sliding window Size x Size where Size must be odd

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Scale Grays

Method Operator::Transform: applies a pixel-by-pixel grayscale transform such as histogram stretching, defined by means of a lookup-table

static void Transform(Profile& LookupTable, const Image& Src, Image& Dst);

Profile& LookupTable: array of values defining the output grayscale values corresponding to all input grayscale values; Gray only

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Operator - Scale Grays

Property int Operator::GrayDepth: tells the actual number of significant bits used with Gray16 images; between 9 and 16 inclusive


Member of the class Operator - Profile Arithmetic

Method Operator::Add: sample-by-sample addition, constant plus profile

static void Add(int Const, const Profile& Src, Profile& Dst);

int Const: a constant value used as the first source argument

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Profile& Dst: the destination image, which is computed by this operation

Method Operator::Add: sample-by-sample addition, profile plus profile

static void Add(const Profile& Src, const Profile& SrcB, Profile& Dst);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Profile& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Profile& Dst: the destination image, which is computed by this operation


Member of the class Operator - Profile Arithmetic

Method Operator::Subtract: sample-by-sample subtraction, profile minus constant

static void Subtract(int Const, const Profile& Src, Profile& Dst);

int Const: a constant value used as the first source argument

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Profile& Dst: the destination image, which is computed by this operation

Method Operator::Subtract: sample-by-sample subtraction, profile minus profile

static void Subtract(const Profile& Src, int Const, Profile& Dst);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

int Const: a constant value used as the first source argument

Profile& Dst: the destination image, which is computed by this operation

Method Operator::Subtract: pixel-by-pixel subtraction, constant minus image

static void Subtract(const Profile& Src, const Profile& SrcB, Profile& Dst);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Profile& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Profile& Dst: the destination image, which is computed by this operation


Member of the class Operator - Profile Arithmetic

Method Operator::Multiply: sample-by-sample multiplication, constant times profile

static void Multiply(double Const, const Profile& Src, Profile& Dst);

double Const: a constant value used as the first source argument

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& Dst: the destination image, which is computed by this operation

Method Operator::Multiply: sample-by-sample multiplication, profile times profile

static void Multiply(const Profile& Src, const Profile& SrcB, Profile& Dst);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& Dst: the destination image, which is computed by this operation


Member of the class Operator - Profile Arithmetic

Method Operator::Divide: sample-by-sample division, profile over constant

static void Divide(double Const, const Profile& Src, Profile& Dst);

double Const: a constant value used as the first source argument

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& Dst: the destination image, which is computed by this operation

Method Operator::Divide: sample-by-sample division, profile over profile

static void Divide(const Profile& Src, double Const, Profile& Dst);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

double Const: a constant value used as the first source argument

Profile& Dst: the destination image, which is computed by this operation

Method Operator::Divide: pixel-by-pixel division, constant over image

static void Divide(const Profile& Src, const Profile& SrcB, Profile& Dst);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& Dst: the destination image, which is computed by this operation


Member of the class Operator - Profile Arithmetic

Method Operator::Maximize: sample-by-sample largest value, maximum of constant and profile

static void Maximize(int Const, const Profile& Src, Profile& Dst);

int Const: a constant value used as the first source argument

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& Dst: the destination image, which is computed by this operation

Method Operator::Maximize: sample-by-sample largest value, maximum of two images

static void Maximize(const Profile& Src, const Profile& SrcB, Profile& Dst);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& Dst: the destination image, which is computed by this operation


Member of the class Operator - Profile Arithmetic

Method Operator::Minimize: sample-by-sample smallest value, minimum of constant and profile

static void Minimize(int Const, const Profile& Src, Profile& Dst);

int Const: a constant value used as the first source argument

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& Dst: the destination image, which is computed by this operation

Method Operator::Minimize: sample-by-sample smallest value, minimum of two images

static void Minimize(const Profile& Src, const Profile& SrcB, Profile& Dst);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Profile& Dst: the destination image, which is computed by this operation


Enumeration

Enum GradientTypes: formula used to compute the gradient of a grayscale image

Case StandardGradient: simple finite difference on X and Y, i.e. [-1 0 1] weights, or standard morphological gradient

Case PrewittGradient: Prewitt kernel, i.e. [-1 0 1] convolved with weights [1 1 1]

Case SobelGradient: Sobel kernel, i.e. [-1 0 1] convolved with weights [1 2 1]

Case CorrelatedGradient: Correlation with a straight edge

Case Canny1Gradient: Derivative of Gaussian, sigma² = 1

Case Canny15Gradient: Derivative of Gaussian, sigma² = 1.5

Case Canny2Gradient: Derivative of Gaussian, sigma² = 2

Case ExternalGradient: External mophological gradient (dilation minus source)

Case InternalGradient: Internal mophological gradient (source minus erosion)


Class Kernel

The Kernel class handles convolutions filters, i.e. linear combinations of image values in a small sliding neighborhood. A convolution is characterized by a small array of multiplicative coefficients, or convolution weights. A number of predefined convolutions kernels, implementing classical filters, are available

Constructor Kernel: creates a void Kernel object

Gradient Filters

Method Gradient: image gradient magnitude, defined as the maximum of the horizontal and vertical derivatives

Method GradientSum: a variant of the gradient magnitude, defined as the sum of the horizontal and vertical derivatives

Method GradientX: horizontal derivative, computed as the first order symmetric difference

Method GradientY: vertical derivative, computed as the first order symmetric difference

Method Sobel: the classical Sobel magnitude filter, the maximum of horizontal and vertical Sobel derivatives

Method SobelSum: a variant of the Sobel magnitude filter, the sum of horizontal and vertical Sobel derivatives

Method SobelX: horizontal derivative combined with a vertical 1x3 lowpass (binomial) filter

Method SobelY: vertical derivative combined with an horizontal 3x1 lowpass (binomial) filter

Method Prewitt: the classical Prewitt magnitude filter, the maximum of horizontal and vertical Prewitt derivatives

Method PrewittSum: Prewitt magnitude filter, the sum of horizontal and vertical Prewitt derivatives

Method PrewittX: horizontal derivative combined with a vertical 1x3 lowpass (uniform) filter

Method PrewittY: vertical derivative combined with a vertical 1x3 lowpass (uniform) filter

Method Canny: Canny edge filter, modulus

Method CannyPhase: Canny edge filter, argument, scaled to the range [0..255]

Method CorrelatedGradient: image gradient magnitude, defined as the correlation with a straight edge

Method BoxDeviation: an 'activity' filter obtained by computing the standard deviation in a rectangular window around every pixel; the computing time does not depend on the window size

Low-pass Filters

Method Smooth: a low-pass filter that averages all 9 pixels around the kernel center

Method Smooth8: a low-pass filter that averages the 8 pixels around the kernel center

Method Binomial: the 3x3 binomial lowpass filter, an approximation of a Gaussian kernel with a unit standard deviation

Method Binomial5: the 5x5 binomial lowpass filter, an approximation of a Gaussian kernel with standard deviation 1.22

Method Binomial7: the 7x7 binomial lowpass filter, an approximation of a Gaussian kernel with standard deviation 1.5

Method Binomial9: the 9x9 binomial lowpass filter, an approximation of a Gaussian kernel with standard deviation 2

Method BoxLowPass: a uniform filter obtained by averaging in a rectangular window around every pixel; the computing time does not depend on the window size

Method GaussLowPass: an approximation of the Gaussian filter of a desired size; the computing time does not depend on the window size

Method Bilateral: fast bilateral filter approximation

High-pass Filters

Method Sharpen4: a sharpening filter obtained by subtracting a 4-way Laplacian filter from the source image

Method Sharpen8: a sharpening filter obtained by subtracting a 8-way Laplacian filter from the source image

Method Unsharp: lessens the blur by comparison to a further blurred image (unsharp masking)

Method BoxHighPass: a high-pass filter obtained by averaging in a rectangular window around every pixel and subtracting from the original image; the computing time does not depend on the window size

Cornerness

Method Cornerness: strength of the corners as defined by the Harris detector

Storage

Property Width: number of pixels, horizontally

Property Height: number of pixels, vertically

General Convolution

Method Set: adjusts the size of the convolution kernel

Method Coefficient: accesses the value of a given convolution coefficient

Property Clip: value adjustment rule in case of underflow or overflow; one of Saturate, Absolute, Negative

Property Offset: a global offset added to the convolution result

Method Normalize: automatic rescaling of the kernel coefficients so that their sum equals the given gain constant

Method Convolve: applies a convolution to the image, using the user-defined kernel


Member of the class Kernel

Constructor Kernel::Kernel: creates a void Kernel object

Kernel();


Member of the class Kernel - Gradient Filters

Method Kernel::Gradient: image gradient magnitude, defined as the maximum of the horizontal and vertical derivatives

static void Gradient(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Gradient Filters

Method Kernel::GradientSum: a variant of the gradient magnitude, defined as the sum of the horizontal and vertical derivatives

static void GradientSum(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow


Member of the class Kernel - Gradient Filters

Method Kernel::GradientX: horizontal derivative, computed as the first order symmetric difference

static void GradientX(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Gradient Filters

Method Kernel::GradientY: vertical derivative, computed as the first order symmetric difference

static void GradientY(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Gradient Filters

Method Kernel::Sobel: the classical Sobel magnitude filter, the maximum of horizontal and vertical Sobel derivatives

static void Sobel(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the Sobel filter


Member of the class Kernel - Gradient Filters

Method Kernel::SobelSum: a variant of the Sobel magnitude filter, the sum of horizontal and vertical Sobel derivatives

static void SobelSum(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow; allowed values are Saturate and Rescale for the SobelSum filter


Member of the class Kernel - Gradient Filters

Method Kernel::SobelX: horizontal derivative combined with a vertical 1x3 lowpass (binomial) filter

static void SobelX(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow


Member of the class Kernel - Gradient Filters

Method Kernel::SobelY: vertical derivative combined with an horizontal 3x1 lowpass (binomial) filter

static void SobelY(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow


Member of the class Kernel - Gradient Filters

Method Kernel::Prewitt: the classical Prewitt magnitude filter, the maximum of horizontal and vertical Prewitt derivatives

static void Prewitt(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment in case of underflow or overflow


Member of the class Kernel - Gradient Filters

Method Kernel::PrewittSum: Prewitt magnitude filter, the sum of horizontal and vertical Prewitt derivatives

static void PrewittSum(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow


Member of the class Kernel - Gradient Filters

Method Kernel::PrewittX: horizontal derivative combined with a vertical 1x3 lowpass (uniform) filter

static void PrewittX(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow


Member of the class Kernel - Gradient Filters

Method Kernel::PrewittY: vertical derivative combined with a vertical 1x3 lowpass (uniform) filter

static void PrewittY(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow


Member of the class Kernel - Gradient Filters

Method Kernel::Canny: Canny edge filter, modulus

static void Canny(const Image& Src, Image& Dst, enum GradientTypes Type);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

GradientTypes Type: one of Canny1Gradient, Canny15Gradient, Canny2Gradient corresponding to Sigma² = 1, 1.5 and 2


Member of the class Kernel - Gradient Filters

Method Kernel::CannyPhase: Canny edge filter, argument, scaled to the range [0..255]

static void CannyPhase(const Image& Src, Image& Dst, enum GradientTypes Type, bool FullTurn = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

GradientTypes Type: one of Canny1Gradient, Canny15Gradient, Canny2Gradient corresponding to Sigma² = 1, 1.5 and 2

bool FullTurn: when true, the angle is computed over a full turn; otherwise the two half turns are coincident


Member of the class Kernel - Gradient Filters

Method Kernel::CorrelatedGradient: image gradient magnitude, defined as the correlation with a straight edge

static void CorrelatedGradient(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Gradient Filters

Method Kernel::BoxDeviation: an 'activity' filter obtained by computing the standard deviation in a rectangular window around every pixel; the computing time does not depend on the window size

static void BoxDeviation(int FilterWidth, int FilterHeight, const Image& Src, Image& Dst);

int FilterWidth: width of the averaging window; must be an odd integer

int FilterHeight: height of the averaging window; must be an odd integer

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::Smooth: a low-pass filter that averages all 9 pixels around the kernel center

static void Smooth(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::Smooth8: a low-pass filter that averages the 8 pixels around the kernel center

static void Smooth8(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::Binomial: the 3x3 binomial lowpass filter, an approximation of a Gaussian kernel with a unit standard deviation

static void Binomial(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::Binomial5: the 5x5 binomial lowpass filter, an approximation of a Gaussian kernel with standard deviation 1.22

static void Binomial5(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::Binomial7: the 7x7 binomial lowpass filter, an approximation of a Gaussian kernel with standard deviation 1.5

static void Binomial7(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::Binomial9: the 9x9 binomial lowpass filter, an approximation of a Gaussian kernel with standard deviation 2

static void Binomial9(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::BoxLowPass: a uniform filter obtained by averaging in a rectangular window around every pixel; the computing time does not depend on the window size

static void BoxLowPass(int FilterWidth, int FilterHeight, const Image& Src, Image& Dst);

int FilterWidth: width of the averaging window; must be an odd integer

int FilterHeight: height of the averaging window; must be an odd integer

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::GaussLowPass: an approximation of the Gaussian filter of a desired size; the computing time does not depend on the window size

static void GaussLowPass(int FilterWidth, int FilterHeight, const Image& Src, Image& Dst);

int FilterWidth: filter width, in pixels; must be an odd integer

int FilterHeight: filter height, in pixels; must be an odd integer

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - Low-pass Filters

Method Kernel::Bilateral: fast bilateral filter approximation

static void Bilateral(int FilterSize, int GrayRange, const Image& Src, Image& Dst);

int FilterSize: filter size, must be odd

int GrayRange: allowed gray value discrepancy

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - High-pass Filters

Method Kernel::Sharpen4: a sharpening filter obtained by subtracting a 4-way Laplacian filter from the source image

static void Sharpen4(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow


Member of the class Kernel - High-pass Filters

Method Kernel::Sharpen8: a sharpening filter obtained by subtracting a 8-way Laplacian filter from the source image

static void Sharpen8(const Image& Src, Image& Dst, GrayClipping Clip = Saturate);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow


Member of the class Kernel - High-pass Filters

Method Kernel::Unsharp: lessens the blur by comparison to a further blurred image (unsharp masking)

static void Unsharp(double Strength, const Image& Src, Image& Dst);

double Strength: degree to which deblurring is applied

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Kernel - High-pass Filters

Method Kernel::BoxHighPass: a high-pass filter obtained by averaging in a rectangular window around every pixel and subtracting from the original image; the computing time does not depend on the window size

static void BoxHighPass(int FilterWidth, int FilterHeight, const Image& Src, Image& Dst, GrayClipping Clip = Saturate, double Gain = 1);

int FilterWidth: width of the averaging window; must be an odd integer

int FilterHeight: height of the averaging window; must be an odd integer

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GrayClipping Clip: value adjustment rule in case of underflow or overflow

double Gain: multiplicative factor; 1 by default


Member of the class Kernel - Cornerness

Method Kernel::Cornerness: strength of the corners as defined by the Harris detector

static void Cornerness(int FilterSize, const Image& Src, Image& Dst, bool Edges = false);

int FilterSize: filter size in pixels, must be odd

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Edges: when true, the cornerness includes egde information; otherwise, only corners


Member of the class Kernel - Storage

Property int Kernel::Width: number of pixels, horizontally


Member of the class Kernel - Storage

Property int Kernel::Height: number of pixels, vertically


Member of the class Kernel - General Convolution

Method Kernel::Set: adjusts the size of the convolution kernel

void Set(int Width, int Height);

int Width: number of pixels, horizontally

int Height: number of pixels, vertically


Member of the class Kernel - General Convolution

Method Kernel::Coefficient: accesses the value of a given convolution coefficient

double& Coefficient(int X, int Y);

returned double&: coefficient value; can be read or written

int X: column index of the coefficient

int Y: row index of the coefficient


Member of the class Kernel - General Convolution

Property GrayClipping Kernel::Clip: value adjustment rule in case of underflow or overflow; one of Saturate, Absolute, Negative


Member of the class Kernel - General Convolution

Property double Kernel::Offset: a global offset added to the convolution result


Member of the class Kernel - General Convolution

Method Kernel::Normalize: automatic rescaling of the kernel coefficients so that their sum equals the given gain constant

void Normalize(double Gain = 1);

double Gain: global gain value to be applied after normalization of the coefficients


Member of the class Kernel - General Convolution

Method Kernel::Convolve: applies a convolution to the image, using the user-defined kernel

void Convolve(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Class Morpho

Support for the morphological filters

Constructor Morpho: creates a void Morpho object

Structel

Method Set: sets the size and shape of the structuring element

Method Box: defines a rectangular structuring element of the given size

Method Square: defines a square structuring element of the given size

Method Octagon: defines a regular octagonal structuring element of the given size

Method Diamond: defines a diamond structuring element, i.e. a rotated square

Method Horizontal: defines an horizontal structuring element of the given width

Method Vertical: defines a vertical structuring element of the given height

Property Width: number of pixels, horizontally

Property Height: number of pixels, vertically

Property Diagonal: number of corner pixel rows to be removed

Filtering

Method Dilate: replaces every pixel of the image by the largest value in a sliding neighborhood called the structuring element; this filter enlarges the light features

Method Erode: replaces every pixel of the image by the smallest value in a sliding neighborhood called the structuring element; this filter enlarges the dark features

Method Open: an erosion followed by a dilation with the same structuring element; this filter connects the dark features

Method Close: a dilation followed by an erosion with the same structuring element; this filter connects the light features

Method WhiteHat: white top-hat morphological filter; detects the light features that fit in the structuring element shape

Method BlackHat: black top-hat morphological filter; detects the dark features that fit in the structuring element shape

Method Gradient: the difference between the source, dilated or eroded image, used as an edge detection filter

Method MidRange: the average of the dilated and the eroded image, used as a smoothing filter

Method PseudoMedian: the average of the closed and the opened image, used as a smoothing filter

Method Contrast: the difference of the closed and the opened image, used as a contrast assessment filter

Method Median: median filter, for edge-preserving denoising

Method Rank: rank filter for robust feature detection

Method BinaryThin: morphological thinning of a binary image (only black & white pixels)

Method BinaryThick: morphological thickening of a binary image (black & white pixels), i.e. thinning of the background

Segmentation

Method Isophotes: Isophotes are connected curves joining pixels at the same gray-level

Method Watershed: morphological watershed, segments a gradient image, growing regions from local minima

Method RegionalMaxima: detects the (strongest) regional maxima, i.e. the pixels or plateaus brighter than all their neigbors

Method RegionalMinima: detects the (weakest) regional minima, i.e. the pixels or plateaus darker than all their neigbors

Method GraphSegment: segment in uniform regions using a graph-based method

Method AverageRegions: replace all pixels in regions by their average value

Method Distance: topological or Euclidean distance map to the black or to the white pixels; distances are limited to 255

Method KillConnect: erase the pixels with hight connexity


Member of the class Morpho

Constructor Morpho::Morpho: creates a void Morpho object

Morpho();


Member of the class Morpho - Structel

Method Morpho::Set: sets the size and shape of the structuring element

void Set(int Width, int Height, int Diagonal);

int Width: number of pixels, horizontally; must be odd

int Height: number of pixels, vertically; must be odd

int Diagonal: number of corner pixel rows to be removed


Member of the class Morpho - Structel

Method Morpho::Box: defines a rectangular structuring element of the given size

void Box(int Width, int Height);

int Width: number of pixels, horizontally; must be odd

int Height: number of pixels, vertically; must be odd


Member of the class Morpho - Structel

Method Morpho::Square: defines a square structuring element of the given size

void Square(int Size);

int Size: number of pixels, horizontally and vertically; must be odd


Member of the class Morpho - Structel

Method Morpho::Octagon: defines a regular octagonal structuring element of the given size

void Octagon(int Size);

int Size: number of pixels horizontally and vertically; must be odd


Member of the class Morpho - Structel

Method Morpho::Diamond: defines a diamond structuring element, i.e. a rotated square

void Diamond(int Size);

int Size: number of pixels horizontally and vertically; must be odd


Member of the class Morpho - Structel

Method Morpho::Horizontal: defines an horizontal structuring element of the given width

void Horizontal(int Width);

int Width: number of pixels, horizontally; must be an odd number


Member of the class Morpho - Structel

Method Morpho::Vertical: defines a vertical structuring element of the given height

void Vertical(int Height);

int Height: number of pixels, vertically; must be an odd number


Member of the class Morpho - Structel

Property int Morpho::Width: number of pixels, horizontally


Member of the class Morpho - Structel

Property int Morpho::Height: number of pixels, vertically


Member of the class Morpho - Structel

Property int Morpho::Diagonal: number of corner pixel rows to be removed


Member of the class Morpho - Filtering

Method Morpho::Dilate: replaces every pixel of the image by the largest value in a sliding neighborhood called the structuring element; this filter enlarges the light features

void Dilate(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::Erode: replaces every pixel of the image by the smallest value in a sliding neighborhood called the structuring element; this filter enlarges the dark features

void Erode(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::Open: an erosion followed by a dilation with the same structuring element; this filter connects the dark features

void Open(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::Close: a dilation followed by an erosion with the same structuring element; this filter connects the light features

void Close(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::WhiteHat: white top-hat morphological filter; detects the light features that fit in the structuring element shape

void WhiteHat(const Image& Src, Image& Dst, bool Binarize = false);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

bool Binarize: when true, the result of the top-hat filtering is automatically binarized


Member of the class Morpho - Filtering

Method Morpho::BlackHat: black top-hat morphological filter; detects the dark features that fit in the structuring element shape

void BlackHat(const Image& Src, Image& Dst, bool Binarize = false);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

bool Binarize: when true, the result of the top-hat filtering is automatically binarized


Member of the class Morpho - Filtering

Method Morpho::Gradient: the difference between the source, dilated or eroded image, used as an edge detection filter

void Gradient(const Image& Src, Image& Dst, GradientTypes Type = StandardGradient);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation

GradientTypes Type: one of Standard (dilated-Eroded), External (Dilated-Source) or Internal (Source-Eroded)


Member of the class Morpho - Filtering

Method Morpho::MidRange: the average of the dilated and the eroded image, used as a smoothing filter

void MidRange(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::PseudoMedian: the average of the closed and the opened image, used as a smoothing filter

void PseudoMedian(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::Contrast: the difference of the closed and the opened image, used as a contrast assessment filter

void Contrast(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::Median: median filter, for edge-preserving denoising

void Median(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::Rank: rank filter for robust feature detection

void Rank(double Percent, const Image& Src, Image& Dst);

double Percent: the relative rank of the filter, in range [0 1]

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Filtering

Method Morpho::BinaryThin: morphological thinning of a binary image (only black & white pixels)

static int BinaryThin(const Image& Src, Image& Dst, int MaxLayers = Auto, bool KeepEnds = false);

returned int: the number of layers that were removed before convergence, i.e. the maximum thickness

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

int MaxLayers: if Auto, performs normal thinning; if an integer, causes to stop after removal of a number of layers

bool KeepEnds: when true, as by default, the free endpoint edges are kept; otherwise they are erased


Member of the class Morpho - Filtering

Method Morpho::BinaryThick: morphological thickening of a binary image (black & white pixels), i.e. thinning of the background

static int BinaryThick(const Image& Src, Image& Dst, int MaxLayers = Auto, bool KeepEnds = false);

returned int: the number of layers that were removed before convergence, i.e. the maximum thinness

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

int MaxLayers: if Auto, performs normal thickening; if an integer, causes to stop after removal of a number of layers

bool KeepEnds: when true, as by default, the free endpoint edges are kept; otherwise they are erased


Member of the class Morpho - Segmentation

Method Morpho::Isophotes: Isophotes are connected curves joining pixels at the same gray-level

static void Isophotes(int Level, int Step, bool Connexity8, const Image& Src, Image& Dst);

int Level: the desired gray-level

int Step: multiple isophotes are traced, in Step increments

bool Connexity8: when true the contour will be 8-connected; otherwise 4-connected

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Segmentation

Method Morpho::Watershed: morphological watershed, segments a gradient image, growing regions from local minima

static int Watershed(bool Connexity8, const Image& Grd, Image& Dst, int Noise = Auto, bool Binarize = true);

returned int: the computed value of the Noise parameter, if Auto was passed

bool Connexity8: when true the region will be 8-connected (by duality, edges 4-connected); otherwise 4-connected

Image& Grd: the gradient intensity image used to detect the edges (Gradient, Prewitt, Sobel...)

Image& Dst: destination Image or Blobs that hold the results of segmentation)

int Noise: gradients intensities below this threshold cannot form edges; can be Auto

bool Binarize: when false, gradient intensities are preserved on the edges; otherwise, as by default, a binary image is produced

Method Morpho::Watershed: morphological watershed, segments a gradient image, growing regions from local minima

static int Watershed(bool Connexity8, const Image& Grd, const Image& Src, Image& Dst, int Noise = Auto, bool Average = true);

returned int: the computed value of the Noise parameter, if Auto was passed

bool Connexity8: when true the region will be 8-connected (by duality, edges 4-connected); otherwise 4-connected

Image& Grd: the gradient intensity image used to detect the edges (Gradient, Prewitt, Sobel...)

Image& Src: the source image from which the gradient intensity was computed

Image& Dst: destination Image or Blobs that hold the results of segmentation)

int Noise: gradients intensities below this threshold cannot form edges; can be Auto

bool Average: when false, original gray intensities are preserved; otherwise, as by default, the regions are filled with their average gray level

Method Morpho::Watershed: morphological watershed, segments a gradient image, growing regions from local minima

static int Watershed(bool Connexity8, const Image& Grd, Blobs& Dst, int Noise = Auto);

returned int: the computed value of the Noise parameter, if Auto was passed

bool Connexity8: when true the region will be 8-connected (by duality, edges 4-connected); otherwise 4-connected

Image& Grd: the gradient intensity image used to detect the edges (Gradient, Prewitt, Sobel...)

Blobs& Dst: destination Image or Blobs that hold the results of segmentation)

int Noise: gradients intensities below this threshold cannot form edges; can be Auto


Member of the class Morpho - Segmentation

Method Morpho::RegionalMaxima: detects the (strongest) regional maxima, i.e. the pixels or plateaus brighter than all their neigbors

static void RegionalMaxima(int MinGray, int MaxCount, const Image& Src, Path& Dst, bool Connexity8 = true);

int MinGray: maxima below this gray value are ignored

int MaxCount: maximum number of points returned; if zero, all maxima are detected

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Path& Dst: Path object to hold the point coordinates (a single point per region)

bool Connexity8: when true the 8-connected neighbors are considered; otherwise 4-connected


Member of the class Morpho - Segmentation

Method Morpho::RegionalMinima: detects the (weakest) regional minima, i.e. the pixels or plateaus darker than all their neigbors

static void RegionalMinima(int MaxGray, int MaxCount, const Image& Src, Path& Dst, bool Connexity8 = true);

int MaxGray: minima above this gray value are ignored

int MaxCount: maximum number of points returned; if zero, all minima are detected

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Path& Dst: Path object to hold the point coordinates (a single point per region)

bool Connexity8: when true the 8-connected neighbors are considered; otherwise 4-connected


Member of the class Morpho - Segmentation

Method Morpho::GraphSegment: segment in uniform regions using a graph-based method

static void GraphSegment(const Image& Src, Image& Dst, int Filter, double Step, int MinArea, bool Connexity8 = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

int Filter: pre-filtering for denoising; 0 for no filtering, [1..4] for smoothing with increasing strength

double Step: penalty term to control oversegmentation

int MinArea: regions smaller than this area can be merged

bool Connexity8: when true the regions will be 8-connected; otherwise 4-connected


Member of the class Morpho - Segmentation

Method Morpho::AverageRegions: replace all pixels in regions by their average value

static void AverageRegions(const Image& Msk, const Image& Src, Image& Dst);

Image& Msk: region map, black areas surrounded by white edges

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Morpho - Segmentation

Method Morpho::Distance: topological or Euclidean distance map to the black or to the white pixels; distances are limited to 255

static void Distance(const Image& Src, Image& Dst, bool Above = true, bool Euclidean = false, bool Connexity8 = true, bool Large = false);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Above: when true, the distance is computed from the black background, in the white foreground areas; otherwise, the converse

bool Euclidean: when true, the Euclidean map is computed; it is more isotropic

bool Connexity8: when true the contour will be 8-connected; otherwise 4-connected

bool Large: when true, distances larger than 255 are possible and the output is a Gray16 image rather than Gray


Member of the class Morpho - Segmentation

Method Morpho::KillConnect: erase the pixels with hight connexity

static void KillConnect(int MinNeighbors, int MaxNeighbors, const Image& Src, Image& Dst);

int MinNeighbors: pixels with at most that many neighbors are erased

int MaxNeighbors: pixels with at least that many neighbors are erased

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Enumeration

Enum RegistrationModels: geometric models used for calibration, by increasing complexity

Case Translation: pure sub-pixel translation

Case Rotation: translation and planar rotation

Case Mirroring: same as Rotation, viewed from the other side (or counterclockwise frame)

Case Scaling: translation and (anisotropic) scaling

Case Similarity: translation, planar rotation and scaling

Case Reflection: same as Similarity, viewed from the other side (or counterclockwise frame)

Case Affinity: general affine transformation

Case Perspective: perspective transformation

Case Quadratic: affine transformation with deformation

Case General: perspective transformation with deformation

Case Biquadratic: affine transformation with large deformation

Case Rational: perspective transformation with large deformation


Class Geometry

Handles the image transforms that imply a displacement of the pixels, such as translation, rotation, scaling, with possible interpolation

Constructor Geometry: creates a void Geometry object

Simple Transforms

Method Flip: turns the image upside down

Method Mirror: turns the image leftside right

Method Turn: rotates the image in multiples of 90 degrees, keeping the image size

Method DownSample: resample an image to a smaller size, using low-pass filtering to avoid aliasing

Method UpSample: resample an image to a larger size, using interpolation to avoid aliasing

Linear Transforms

Method Rotate: rotation around a center point with a given amplitude angle and a possible scale factor; the angle and scale are provided explicitly

Method Skew: linear transform that maps the reference frame formed by three anchor points in the source image to a corresponding frame in the destination image

Method Affine: applies a generic linear transform of the plane known as an affine transform; an affine transform is defined by six parameters and covers translations, symmetries, rotations, similarities and shears It is important to note that the transform expresses the source image coordinates as a function of the destination image coordinates

Polar Transform

Method Unwind: turns polar coordinates (Argument, Modulus) to Cartesian coordinates (X, Y) to produce a ring unrolling effect; this is handy to process annular objects

Tabulated Transform

Method Transform: applies a general plane mapping function that has been pre-tabulated

Method GridDeform: Maps a points of a deformed image back to the original, using a grid of anchor points

Simple Calibration

Method SimpleCalibration: define the conversion factors used for simple calibration; always isotropic; applies globally

Property ScaleToPixel: scale factor to be applied to calibrated coordinates to convert them to pixels; pixels per length unit (cm, mm, mil...)

Property ScaleFromPixel: scale factor to be applied to uncalibrated coordinates to convert them from pixels; in length unit (cm, mm, mil...) per pixel

Calibration

Method CalibrateTarget: setup calibration coefficients using a regular grid image

Method Calibrate: applies the direct transformation to a point, i.e. turn a point in the source space to the corresponding calibrated coordinates

Method Decalibrate: applies the reverse transformation to a point, i.e. turn calibrated point coordinates to the corresponding pixel in the source space

Image Correction

Method Undistort: applies the direct transformation to an image, i.e. turn all image pixels to an ideal, rectified image, using the current pixel size

Registration

Property Model: geometric model to be used as enumerated in RegistrationModels ; one of Translation, Rotation, Similarity, Affinity, Perspective, Quadratic, General, Biquadratic, Rational

Method PureScaling: define the conversion factors used for pure scaling; not to be confused with SimpleCalibration, applies per instance

Method ModelFit: evaluates the calibration model from the given anchor points

Method Register: applies the direct transformation to a point, i.e. turn a point in the source space to the corresponding point in the destination space

Method ReverseRegister: applies the reverse transformation to a point, i.e. turn a point in the destination space to the corresponding point in the source space

Storage

Method Read: get the transformation parameters from a Geometry model file (ASCII filename)

Method Write: store the transformation parameters to a Geometry model file for later use (ASCII filename)

Anchor Points

Method Clear: remove all stored anchor points

Method Append: add a couple of (Source, Destination) anchor points

Property NumAnchors: current number of pairs of anchor points

Method Src: acces the source anchor point at the given index

Method Dst: acces the destination anchor point at the given index

Graphics

Method DrawAnchors: draws the source or destination anchor points

Method HitHandle: tells if the cursor is over an anchor point

Property Handle: one of AllHandle or NoHandle

Property AnchorIndex: index of the last hit dragging anchor

Method Drag: move the current dragging anchor point


Member of the class Geometry

Constructor Geometry::Geometry: creates a void Geometry object

Geometry();


Member of the class Geometry - Simple Transforms

Method Geometry::Flip: turns the image upside down

static void Flip(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Geometry - Simple Transforms

Method Geometry::Mirror: turns the image leftside right

static void Mirror(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Geometry - Simple Transforms

Method Geometry::Turn: rotates the image in multiples of 90 degrees, keeping the image size

static void Turn(int Quadrant, const Image& Src, Image& Dst);

int Quadrant: rotation angle expressed as a number of quarter turns

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation


Member of the class Geometry - Simple Transforms

Method Geometry::DownSample: resample an image to a smaller size, using low-pass filtering to avoid aliasing

static void DownSample(int Width, int Height, const Image& Src, Image& Dst, bool Filter = true);

int Width: number of pixels after resampling, horizontally

int Height: number of pixels after resampling, vertically

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

bool Filter: when true, as by default, lowpass filtering is applied before resampling, to avoid aliasing


Member of the class Geometry - Simple Transforms

Method Geometry::UpSample: resample an image to a larger size, using interpolation to avoid aliasing

static void UpSample(int Width, int Height, const Image& Src, Image& Dst, bool Interpolate = true);

int Width: number of pixels after resampling, horizontally

int Height: number of pixels after resampling, vertically

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image, which is computed by this operation

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Geometry - Linear Transforms

Method Geometry::Rotate: rotation around a center point with a given amplitude angle and a possible scale factor; the angle and scale are provided explicitly

static bool Rotate(const XY& SrcAnchor, const XY& DstAnchor, double Angle, double Scale, const Image& Src, Image& Dst, bool Interpolate = true);

returned bool: returns true if overshoot of the source image occurred during resampling

XY& SrcAnchor: the center point in the source image (maps to the center point in the destination image)

XY& DstAnchor: the center point in the destination image

double Angle: rotation angle; 0 for no rotation

double Scale: the scaling factor; 1 for no scaling

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation; if the image type is GeoMap, the transform is tabulated for efficient processing

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used

Method Geometry::Rotate: rotation around a center point with a given amplitude angle and a possible scale factor; the angle and scale are specified by dragging a second point

static bool Rotate( const XY& SrcAnchor0, const XY& SrcAnchor1, const XY& DstAnchor0, const XY& DstAnchor1, const Image& Src, Image& Dst, bool Scaling = true, bool Interpolate = true);

returned bool: returns true if overshoot of the source image occurred during resampling

XY& SrcAnchor0: the center point in the source image (maps to the center point in the destination image)

XY& SrcAnchor1: an auxiliary point in the source image (maps to the auxiliary point in the destination image)

XY& DstAnchor0: the center point in the destination image

XY& DstAnchor1: the auxiliary point in the destination image

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation; if the image type is GeoMap, the transform is tabulated for efficient processing

bool Scaling: when true, rescaling is applied so that the auxiliary source point exactly maps to the auxiliary destination point, resulting in a similarity transform; when false, pure rotation around the center point is applied

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Geometry - Linear Transforms

Method Geometry::Skew: linear transform that maps the reference frame formed by three anchor points in the source image to a corresponding frame in the destination image

static bool Skew( const XY& SrcAnchor0, const XY& SrcAnchor1, const XY& SrcAnchor2, const XY& DstAnchor0, const XY& DstAnchor1, const XY& DstAnchor2, const Image& Src, Image& Dst, bool Interpolate = true);

returned bool: returns true if overshoot of the source image occurred during resampling

XY& SrcAnchor0: the anchor point that defines the frame origin in the source image

XY& SrcAnchor1: the anchor point that defines the first semi-axis direction in the source image

XY& SrcAnchor2: the anchor point that defines the second semi-axis direction in the source image

XY& DstAnchor0: the anchor point that defines the frame origin in the destination image

XY& DstAnchor1: the anchor point that defines the first semi-axis direction in the destination image

XY& DstAnchor2: the anchor point that defines the second semi-axis direction in the destination image

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation; if the image type is GeoMap, the transform is tabulated for efficient processing

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Geometry - Linear Transforms

Method Geometry::Affine: applies a generic linear transform of the plane known as an affine transform; an affine transform is defined by six parameters and covers translations, symmetries, rotations, similarities and shears It is important to note that the transform expresses the source image coordinates as a function of the destination image coordinates

static bool Affine( double TXx, double TXy, double TX, double TYx, double TYy, double TY, const Image& Src, Image& Dst, bool Interpolate = true);

returned bool: returns true if overshoot of the source image occurred during resampling

double TXx: Src X/Dst X homogeneous coefficient

double TXy: Src X/Dst Y homogeneous coefficient

double TX: Src X constant term

double TYx: Src Y/Dst X homogeneous coefficient

double TYy: Src Y/Dst Y homogeneous coefficient

double TY: Src Y constant term

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation; if the image type is GeoMap, the transform is tabulated for efficient processing

bool Interpolate: when true, bilinear interpolation is used to resample the pixels


Member of the class Geometry - Polar Transform

Method Geometry::Unwind: turns polar coordinates (Argument, Modulus) to Cartesian coordinates (X, Y) to produce a ring unrolling effect; this is handy to process annular objects

static void Unwind(XY& Center, double BegAngle, double EndAngle, double BegRadius, double EndRadius, const Image& Src, Image& Dst, bool Interpolate = true);

XY& Center: polar center coordinates

double BegAngle: starting angle

double EndAngle: ending angle

double BegRadius: inner radius

double EndRadius: outer radius

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation; if the image type is GeoMap, the transform is tabulated for efficient processing

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Geometry - Tabulated Transform

Method Geometry::Transform: applies a general plane mapping function that has been pre-tabulated

static void Transform(const Image& Map, const Image& Src, Image& Dst, bool Interpolate = true);

Image& Map: the map image that stores the tabulated transform; one of Gray, Gray16, Rgb

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

Image& Dst: the destination image for this operation; is modified by the operation

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Geometry - Tabulated Transform

Method Geometry::GridDeform: Maps a points of a deformed image back to the original, using a grid of anchor points

static void GridDeform(XY F[], int N, int NX, int NY, Image& Src, int X0, int TX, int Y0, int TY, Image& Dst);

XY* F: array with deformed point coordinates

int N: grid stride, i.e. number of elements between the start of two rows (i.e. NX + 1 for an array without padding)

int NX: number of horizontal grid intervals (number of vertices minus one)

int NY: number of vertical grid intervals (number of vertices minus one)

Image& Src: source, deformed image

int X0: abscissa of the top-left vertex in the corrected image

int TX: horizontal grid pitch in the destination image, in pixels

int Y0: abscissa of the top-left vertex in the corrected image

int TY: vertical grid pitch in the destination image, in pixels

Image& Dst: target, correct image


Member of the class Geometry - Simple Calibration

Method Geometry::SimpleCalibration: define the conversion factors used for simple calibration; always isotropic; applies globally

static void SimpleCalibration();

Method Geometry::SimpleCalibration: define the conversion factors used for simple calibration; always isotropic; applies globally

static void SimpleCalibration(double LengthInPixels, double TrueLength);

double LengthInPixels: reference length, expressed in pixels

double TrueLength: reference length, expressed in world units


Member of the class Geometry - Simple Calibration

Property double Geometry::ScaleToPixel: scale factor to be applied to calibrated coordinates to convert them to pixels; pixels per length unit (cm, mm, mil...)


Member of the class Geometry - Simple Calibration

Property double Geometry::ScaleFromPixel: scale factor to be applied to uncalibrated coordinates to convert them from pixels; in length unit (cm, mm, mil...) per pixel


Member of the class Geometry - Calibration

Method Geometry::CalibrateTarget: setup calibration coefficients using a regular grid image

void CalibrateTarget(RegistrationModels Model, const Image& Src, double GridStep, bool WhiteOnBlack = false, bool Chessboard = false, double OriginColumn = 0, double OriginRow = 0);

RegistrationModels Model: geometric model to be used as enumerated in RegistrationModels ; one of Translation, Rotation, Similarity, Affinity, Perspective, Quadratic, General

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

double GridStep: true size of the grid mesh

bool WhiteOnBlack: when true, white dots over a black background are considered; by default, back dots on white

bool Chessboard: when true, a chessboard pattern is assumed; otherwise a dot grid

double OriginColumn: horizontal index of the World origin the anchors of the target

double OriginRow: vertical index of the World origin among the anchors of the target


Member of the class Geometry - Calibration

Method Geometry::Calibrate: applies the direct transformation to a point, i.e. turn a point in the source space to the corresponding calibrated coordinates

XY Calibrate(const XY& Src);

returned XY: the calibrated coordinate pair

XY& Src: the raw, distorted input image


Member of the class Geometry - Calibration

Method Geometry::Decalibrate: applies the reverse transformation to a point, i.e. turn calibrated point coordinates to the corresponding pixel in the source space

XY Decalibrate(const XY& Dst);

returned XY: the pixel coordinates

XY& Dst: the world coordinate pair


Member of the class Geometry - Image Correction

Method Geometry::Undistort: applies the direct transformation to an image, i.e. turn all image pixels to an ideal, rectified image, using the current pixel size

void Undistort(const Image& Src, Image& Dst, bool Interpolate = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Geometry - Registration

Property RegistrationModels Geometry::Model: geometric model to be used as enumerated in RegistrationModels ; one of Translation, Rotation, Similarity, Affinity, Perspective, Quadratic, General, Biquadratic, Rational


Member of the class Geometry - Registration

Method Geometry::PureScaling: define the conversion factors used for pure scaling; not to be confused with SimpleCalibration, applies per instance

void PureScaling(double WidthInPixels, double TrueWidth, double HeightInPixels = 0, double TrueHeight = 0);

double WidthInPixels: reference length (horizontally), expressed in pixels

double TrueWidth: reference length (horizontally), expressed in world units

double HeightInPixels: reference length (vertically), expressed in pixels; when 0, same as the width (isotropic scaling)

double TrueHeight: reference length (vertically), expressed in world units; when 0, same as the width (isotropic scaling)


Member of the class Geometry - Registration

Method Geometry::ModelFit: evaluates the calibration model from the given anchor points

void ModelFit(RegistrationModels Model, const Image& Src);

RegistrationModels Model: the type of calibration model to be used for the fitting and coordinate transforms

Image& Src: image argument required to tell the image size; the image content is irrelevant


Member of the class Geometry - Registration

Method Geometry::Register: applies the direct transformation to a point, i.e. turn a point in the source space to the corresponding point in the destination space

XY Register(const XY& Src);

returned XY: transformed point in the destination space

XY& Src: point/image in the source space

Method Geometry::Register: applies the direct transformation to an image, i.e. turn all image pixels from the source space to the destination space

bool Register(const Image& Src, Image& Dst, bool Interpolate = true);

returned bool: transformed point in the destination space

Image& Src: point/image in the source space

Image& Dst: the destination image, which is computed by this operation

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used

Method Geometry::Register: applies the direct transformation to a point, i.e. turn a point in the source space to the corresponding point in the destination space

bool Register(const Image& Src, Image& Dst, Region& Clip, bool Interpolate = true);

returned bool: transformed point in the destination space

Image& Src: point/image in the source space

Image& Dst: the destination image, which is computed by this operation

Region& Clip: a Region object that will describe the parts of the destination image that were facing the source image

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Geometry - Registration

Method Geometry::ReverseRegister: applies the reverse transformation to a point, i.e. turn a point in the destination space to the corresponding point in the source space

XY ReverseRegister(const XY& Dst);

returned XY: transformed point in the source space

XY& Dst: point/image in the destination space

Method Geometry::ReverseRegister: applies the reverse transformation to an image, i.e. turn all image pixels from the destination space to the source space

bool ReverseRegister(const Image& Src, Image& Dst, bool Interpolate = true);

returned bool: transformed point in the source space

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: point/image in the destination space

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Geometry - Storage

Method Geometry::Read: get the transformation parameters from a Geometry model file (ASCII filename)

void Read(const char* PathName);

char* PathName: file path and name as an ASCII or UNICODE character string; .cal extension recommended

Method Geometry::Read: get the transformation parameters from a Geometry model file (UNICODE filename)

void Read(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string; .cal extension recommended


Member of the class Geometry - Storage

Method Geometry::Write: store the transformation parameters to a Geometry model file for later use (ASCII filename)

void Write(const char* PathName);

char* PathName: file path and name as an ASCII or UNICODE character string; .cal extension recommended

Method Geometry::Write: store the transformation parameters to a Geometry model file for later use (UNICODE filename)

void Write(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string; .cal extension recommended


Member of the class Geometry - Anchor Points

Method Geometry::Clear: remove all stored anchor points

void Clear();


Member of the class Geometry - Anchor Points

Method Geometry::Append: add a couple of (Source, Destination) anchor points

void Append(const XY& Src, const XY& Dst);

XY& Src: source anchor point

XY& Dst: destination anchor point


Member of the class Geometry - Anchor Points

Property int Geometry::NumAnchors: current number of pairs of anchor points


Member of the class Geometry - Anchor Points

Method Geometry::Src: acces the source anchor point at the given index

XY& Src(int AnchorIndex);

returned XY&: (X, Y) floating-point coordinates

int AnchorIndex: desired index in range [0..Length-1]


Member of the class Geometry - Anchor Points

Method Geometry::Dst: acces the destination anchor point at the given index

XY& Dst(int AnchorIndex);

returned XY&: (X, Y) floating-point coordinates

int AnchorIndex: desired index in range [0..Length-1]


Member of the class Geometry - Graphics

Method Geometry::DrawAnchors: draws the source or destination anchor points

void DrawAnchors(bool Handles = false, bool DstAnchors = true, int Size = 3, bool Origin = true);

bool Handles: when true, the dragging handles are drawn too

bool DstAnchors: when true, the destination anchors are used; otherwise the source anchors

int Size: Size of the cross

bool Origin: when true, represent the location of the World origin point


Member of the class Geometry - Graphics

Method Geometry::HitHandle: tells if the cursor is over an anchor point

enum DraggingHandles HitHandle(int CursorX, int CursorY, bool DstAnchors = true);

returned DraggingHandles: one of AllHandle or NoHandle

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down

bool DstAnchors: when true, the destination anchors are used; otherwise the source anchors


Member of the class Geometry - Graphics

Property DraggingHandles Geometry::Handle: one of AllHandle or NoHandle


Member of the class Geometry - Graphics

Property int Geometry::AnchorIndex: index of the last hit dragging anchor


Member of the class Geometry - Graphics

Method Geometry::Drag: move the current dragging anchor point

void Drag(int CursorX, int CursorY, bool DstAnchors = true);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down

bool DstAnchors: when true, the destination anchors are used; otherwise the source anchors

Method Geometry::Drag: move the current dragging anchor point

void Drag(int CursorX, int CursorY, int Width, int Height, bool DstAnchors = true);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down

int Width: width of the underlying image, in pixels

int Height: height of the underlying image, in pixels

bool DstAnchors: when true, the destination anchors are used; otherwise the source anchors


Class Pyramid

A set of stacked images of decreasing resolution

Constructor Pyramid: creates a void Pyramid object

Building

Method Build: create the pyramid from the high-resolution image

Access by Level

Property NumLevels: total number of levels in the pyramid

Method Bitmap: get the image at a given level

Rescaling

Method Double: double the image resolution, with bilinear resampling

Method Halve: halve the image resolution, with averaging (binning)

Tile Statistics

Method TileMean: computes the average gray level, per tile

Method TileMidRange: computes the average of the minimum and maximum gray level, per tile

Method TileDeviation: computes the standard deviation of gray levels, per tile

Method TileRange: computes the difference of the minimum and maximum gray level

Graphics

Method TileWindow: sets the Window of an image to correspond to the tile at column i and row j

Method Draw: draw the images of all levels

Method DrawingOffset: returns the offset that corresponds to a given level, in the non-overlapped arrangement

Method DrawingOffset: returns the offset that corresponds to a given level, in the non-overlapped arrangement


Member of the class Pyramid

Constructor Pyramid::Pyramid: creates a void Pyramid object

Pyramid();


Member of the class Pyramid - Building

Method Pyramid::Build: create the pyramid from the high-resolution image

void Build(const Image& Src, int MinSize = 0, int MaxLevels = 0, bool BaseApart = false, bool Dyadic = true);

Image& Src: the high-resolution image at the base of the pyramid

int MinSize: minimum size of the coarsest image

int MaxLevels: maximum number of levels in the pyramid

bool BaseApart: when false, the high resolution image is copied to the pyramid; otherwise, it needs to be kept aside

bool Dyadic: when true, the pyramid is dyadic, i.e. with a reduction factor of 2; otherwise the reduction factor is 3/2


Member of the class Pyramid - Access by Level

Property int Pyramid::NumLevels: total number of levels in the pyramid


Member of the class Pyramid - Access by Level

Method Pyramid::Bitmap: get the image at a given level

Image& Bitmap(Image& Src, int Level);

returned Image&: the stored image

Image& Src: the image that will be returned for the level 0 (Base apart)

int Level: level to look at, in range 0..NumLevels-1

Method Pyramid::Bitmap: get the image at a given level, or the original base image

Image& Bitmap(int Level);

returned Image&: the stored image

int Level: level to look at, in range 0..NumLevels-1


Member of the class Pyramid - Rescaling

Method Pyramid::Double: double the image resolution, with bilinear resampling

static void Double(const Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Pyramid - Rescaling

Method Pyramid::Halve: halve the image resolution, with averaging (binning)

static void Halve(const Image& Src, Image& Dst, bool Dyadic = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Dyadic: when true, the reduction factor is 2; otherwise it 3/2


Member of the class Pyramid - Tile Statistics

Method Pyramid::TileMean: computes the average gray level, per tile

static void TileMean(int TileSize, const Image& Src, Image& Dst, bool PartialTiles = false);

int TileSize: side of the (square) tiles, in pixels

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool PartialTiles: when false, only whole tiles are processed and remaining pixels on the right and bottom are ignored


Member of the class Pyramid - Tile Statistics

Method Pyramid::TileMidRange: computes the average of the minimum and maximum gray level, per tile

static void TileMidRange(int TileSize, const Image& Src, Image& Dst, bool PartialTiles = false);

int TileSize: side of the (square) tiles, in pixels

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool PartialTiles: when false, only whole tiles are processed and remaining pixels on the right and bottom are ignored


Member of the class Pyramid - Tile Statistics

Method Pyramid::TileDeviation: computes the standard deviation of gray levels, per tile

static void TileDeviation(int TileSize, const Image& Src, Image& Dst, bool PartialTiles = false);

int TileSize: side of the (square) tiles, in pixels

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool PartialTiles: when false, only whole tiles are processed and remaining pixels on the right and bottom are ignored


Member of the class Pyramid - Tile Statistics

Method Pyramid::TileRange: computes the difference of the minimum and maximum gray level

static void TileRange(int TileSize, const Image& Src, Image& Dst, bool PartialTiles = false);

int TileSize: side of the (square) tiles, in pixels

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool PartialTiles: when false, only whole tiles are processed and remaining pixels on the right and bottom are ignored


Member of the class Pyramid - Graphics

Method Pyramid::TileWindow: sets the Window of an image to correspond to the tile at column i and row j

static bool TileWindow(int TileSize, int I, int J, Image& Dst);

returned bool: true when the tile fits entirely in the image, false if it is clipped

int TileSize: side of the (square) tiles, in pixels

int I: horizontal tile index, in range 0..Width / TileSize-1 (the last one may be partial)

int J: horizontal tile index, in range 0..Height / TileSize-1 (the last one may be partial)

Image& Dst: the destination image, which is computed by this operation


Member of the class Pyramid - Graphics

Method Pyramid::Draw: draw the images of all levels

void Draw(const Image& Src, bool Overlapped = false);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Overlapped: when false, as by default, the images are tiled to avoid overlap; when true, they are drawn from their top-left corner


Member of the class Pyramid - Graphics

Method Pyramid::DrawingOffset: returns the offset that corresponds to a given level, in the non-overlapped arrangement

Site DrawingOffset(int Level);

returned Site: offset coordinates, can be passed to Graph::Offset

int Level: level index, in range 0..NumLevels-1


Struct XYZ

Generic 3D point

Members

Property X: abscissa (x)

Property Y: ordinate (y)

Property Z: applicate (z)


Member of the class XYZ - Members

Property union { struct { Scalar XYZ::X: abscissa (x)


Member of the class XYZ - Members

Property union { struct { Scalar XYZ::Y: ordinate (y)


Member of the class XYZ - Members

Property union { struct { Scalar XYZ::Z: applicate (z)


Struct sXYZ

3D points with short coordinates

Default constructor

Constructor sXYZ: creates a void sXYZ object

Initializing constructor; X, Y are the coordinates


Member of the class sXYZ - Default constructor

Constructor sXYZ::sXYZ: creates a void sXYZ object

sXYZ();

Constructor sXYZ::sXYZ: shallow copies a given sXYZ object; reserved for internal use

sXYZ(const XYZ& P);

XYZ < short > & P: short coordinates as a 3-array

Constructor sXYZ::sXYZ: shallow copies a given sXYZ object; reserved for internal use

sXYZ(short X, short Y, short Z);

short X: abscissa (x)

short Y: ordinate (y)

short Z: applicate (z)


Struct iXYZ

3D points with integer coordinates

Default constructor

Constructor iXYZ: creates a void iXYZ object

Initializing constructor; X, Y are the coordinates


Member of the class iXYZ - Default constructor

Constructor iXYZ::iXYZ: creates a void iXYZ object

iXYZ();

Constructor iXYZ::iXYZ: shallow copies a given iXYZ object; reserved for internal use

iXYZ(const XYZ& P);

XYZ < int > & P: integer coordinates as a 3-array

Constructor iXYZ::iXYZ: shallow copies a given iXYZ object; reserved for internal use

iXYZ(int X, int Y, int Z);

int X: abscissa (x)

int Y: ordinate (y)

int Z: applicate (z)


Struct fXYZ

3D points with single precision coordinates

Default constructor

Constructor fXYZ: creates a void fXYZ object

Initializing constructor; X, Y are the coordinates


Member of the class fXYZ - Default constructor

Constructor fXYZ::fXYZ: creates a void fXYZ object

fXYZ();

Constructor fXYZ::fXYZ: shallow copies a given fXYZ object; reserved for internal use

fXYZ(const XYZ& P);

XYZ < float > & P: single-precision coordinates as a 3-array

Constructor fXYZ::fXYZ: shallow copies a given fXYZ object; reserved for internal use

fXYZ(float X, float Y, float Z);

float X: abscissa (x)

float Y: ordinate (y)

float Z: applicate (z)


Struct dXYZ

3D points with double precision coordinates

Default constructor

Constructor dXYZ: creates a void dXYZ object

Initializing constructor; X, Y are the coordinates


Member of the class dXYZ - Default constructor

Constructor dXYZ::dXYZ: creates a void dXYZ object

dXYZ();

Constructor dXYZ::dXYZ: shallow copies a given dXYZ object; reserved for internal use

dXYZ(const XYZ& P);

XYZ < double > & P: double-precision coordinates as a 3-array

Constructor dXYZ::dXYZ: shallow copies a given dXYZ object; reserved for internal use

dXYZ(double X, double Y, double Z);

double X: abscissa (x)

double Y: ordinate (y)

double Z: applicate (z)


Struct BasinData

Reserved; watershed basin descriptor

Property Area: reserved; watershed basin area

Property Sum: reserved; watershed basin gray sum

Property Parent: reserved; watershed basin topology

Property Depth: reserved; watershed basin depth


Member of the class BasinData - Analyze

Property int BasinData::Area: reserved; watershed basin area


Member of the class BasinData - Analyze

Property int BasinData::Sum: reserved; watershed basin gray sum


Member of the class BasinData - Analyze

Property int BasinData::Parent: reserved; watershed basin topology


Member of the class BasinData - Analyze

Property byte BasinData::Depth: reserved; watershed basin depth


Enumeration

Enum Polarities: designates the type of transition that defines an edge

Case Raising: going from dark to light values

Case Falling: going from light to dark values

Case Both: either dark to light or light to dark


Enumeration

Enum BlobSelection: pseudo-index that designates a collection of blobs

Case All: all the blobs that were detected

Case AllSelected: all the blobs that are currently selected

Case AllDeselected: all the blobs that are not currently selected


Class Profile

The class that stores and handles 1D pixel data, for signal processing

Constructor Profile: creates a void Profile object

Sizing

Method Set: adjust the length and pixel type of the profile data explicitly

Method Clear: drop all profile samples

Method Append: add a grayscale sample to the end of a grayscale profile

Sample

Method RowGet: gets the pixel profile along an image row

Method RowAdd: computes a row projection, i.e. a horizontal profile with vertically accumulated pixel values

Method RowVariance: variance or standard deviation per image row

Method RowMaximize: computes row maxima, i.e. an horizontal profile with vertically largest pixel values

Method RowMinimize: computes row minima, i.e. an horizontal profile with vertically smallest pixel values

Method RowRange: computes row minima, i.e. an horizontal profile with vertical difference bewteen largest and smallest pixel values

Method ColumnGet: gets the pixel profile along an image column

Method ColumnAdd: computes a column projection, i.e. a vertical profile with horizontally accumulated pixel values

Method ColumnVariance: variance or standard deviation per image column

Method ColumnMaximize: computes column maxima, i.e. a vertical profile with horizontally largest pixel values

Method ColumnMinimize: computes column minima, i.e. a vertical profile with horizontally smallest pixel values

Method ColumnRange: computes column ranges, i.e. a vertical profile with horizontal difference bewteen largest and smallest pixel values

Method LineGet: gets the pixel profile along an image row

Method LineAdd: computes a projection, i.e. an oblique profile with transversally accumulated pixel values

Method LineVariance: variance or standard deviation per image line

Method LineMaximize: computes maxima, i.e. an oblique profile with transversally largest pixel values

Method LineMinimize: computes minima, i.e. an oblique profile with transversally smallest pixel values

Method LineRange: computes ranges, i.e. an oblique profile with transversal difference between largest and smallest pixel values

Method CurveGet: gets the gray-values from an image along a given path

Interval of Interest

Method Window: restrict the profile to an interval of interest

Property I: starting index of the pixel or sample

Property Length: number of pixels or samples

Property HasWindow: true when a profile window is in use

Statistics

Method Quantile: the value that occurs at the given rank in the set of values

Method Median: the value that splits the values in two disjoint sets of equal size, computed from an existing profile

Method Mean: the arithmetic mean of the sample values, computed from an existing profile

Method TrimmedMean: a robust estimate of the mean, obtained by discarding outliers, computed from the profile samples

Method Range: the range of variation of the grayscale values, computed from the profile samples

Method Variance: the usual average squared deviation to the mean, computed from the profile samples

Filter

Method GaussLowPass: an approximation of the Gaussian blur filter; the computing time does not depend on the filter length

Method BoxLowPass: a uniform filter obtained by averaging in a sliding window around every value; the computing time does not depend on the box size

Method GaussHighPass: a high-pass filter obtained by subtracting the output of a Gaussian blur filter from the profile values; the computing time does not depend on the filter length

Method BoxHighPass: a high-pass filter obtained by averaging in a sliding window around every value and subtracting from the original value; the computing time does not depend on the box size

Method Integrate: computes a simple integral by accumulating the profile values from left to right

Method Derive: estimates the first derivative by a simple central difference formula (factor 2 omitted)

Analyze

Method EdgeDetect: detect significant gray-level changes in a 1D profile

Method LocalExtrema: Detect local minima and/or maxima

Define LUT

Method GainOffset: defines a lookup table to apply a gain followed by an offset

Method Threshold: defines a lookup table to binarize with a threshold

Method BiThreshold: prepares a lookup-table for double thresholding, using threshold and threshold+delta limits

Method Quantize: reduces the number of significant bits

Method Logarithm: define a logarithmic or exponential transform

Method Gamma: define a Gamma (exponent) transform

Method PseudoColor: defined a gamut of colors to be mapped to a grayscale

Sample Data

Method Sample: access the sample at a given index in a grayscale profile

Property Buffer: address of the profile data

Property Pitch: profile sample length, in bytes

Graphics

Method Plot: draw a plot of the profile data in a rectangular area in the current window, as specified by the property Status::DrawTo

Method ToAsciiString: convert the content of the profile to tabular text

Storage

Property Type: image pixel type, an enumerated value in PixelTypes; one of Gray, Gray16, Gray32, Rgb

Property Scale: profile data scaling factor; for internal use only

Property StoreLength: number of pixels or samples of the full profile

Method Read: load the Profile data from a file (ASCII or UNICODE path and name)

Method Write: save the Profile data to a file (ASCII or UNICODE path and name)

Graphics

Method SetWindow: sets the size of the underlying image; needs to be called before drawing

Property X: upper left point abscissa, in pixels

Property Y: upper left point ordinate, in pixels, top-down

Property Width: number of pixels, horizontally

Property Height: number of pixels, vertically

Property Beg: coordinates of the starting point of the line segment

Property End: coordinates of the ending point of the line segment

Property XCol: abscissa of the profile column

Property YRow: ordinate of the profile row

Property Breadth: length of the transverse profiles used for computation

Property IsSum: true for a thick profile, i.e. a sum of rows/columns, false for a thin profile

Property Direction: specifies the direction of the sampling area: NHandle for rows, WHandle for columns, AllHandle for an oblique line

Method Draw: draw a thin or thick line at the profile abscissa or ordinate (column or row)

Method HitHandle: returns the dragging handle under the cursor

Property Handle: returns the last handle that was hit

Method Drag: move the current handle


Member of the class Profile

Constructor Profile::Profile: creates a void Profile object

Profile();


Member of the class Profile - Sizing

Method Profile::Set: adjust the length and pixel type of the profile data explicitly

void Set(const Profile& Src, PixelTypes Type = Undefined);

Profile& Src: use the length and pixel type of this profile, unless explicitly overridden

PixelTypes Type: image pixel type, an enumerated value in PixelTypes

Method Profile::Set: adjust the length and pixel type of the profile data by replicating from another profile

void Set(int Length, PixelTypes Type = Gray, int Store[] = 0, int Pitch = 0);

int Length: number of pixels or samples

PixelTypes Type: image pixel type, an enumerated value in PixelTypes

int* Store: storage space for the data, either allocated internally by the object or passed as an external buffer

int Pitch: optional image row length, in bytes, padding included


Member of the class Profile - Sizing

Method Profile::Clear: drop all profile samples

void Clear();


Member of the class Profile - Sizing

Method Profile::Append: add a grayscale sample to the end of a grayscale profile

void Append(int GrayValue);

int GrayValue: gray-level value of the given pixel

Method Profile::Append: add a color sample to the end of a color profile

void Append(int RedValue, int GreenValue, int BlueValue);

int RedValue: value of the red component of the given pixel

int GreenValue: value of the green component of the given pixel

int BlueValue: value of the blue component of the given pixel

Method Profile::Append: add a grayscale sample to the end of a grayscale profile

void Append(RgbPixel ColorValue);

RgbPixel ColorValue: RgbPixel representing the desired color


Member of the class Profile - Sample

Method Profile::RowGet: gets the pixel profile along an image row

void RowGet(int Y, const Image& Src);

int Y: upper left point ordinate, in pixels, top-down

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb


Member of the class Profile - Sample

Method Profile::RowAdd: computes a row projection, i.e. a horizontal profile with vertically accumulated pixel values

void RowAdd(int Y, int Breadth, const Image& Src, bool Average = true);

int Y: upper left point ordinate, in pixels, top-down

int Breadth: number of pixels, vertically

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

bool Average: when true, averages the accumulated values; otherwise keeps the sum


Member of the class Profile - Sample

Method Profile::RowVariance: variance or standard deviation per image row

void RowVariance(int Y, int Breadth, const Image& Src, bool RMS = true);

int Y: upper left point ordinate, in pixels, top-down

int Breadth: number of pixels, vertically

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool RMS: when true, the standard deviations are returned; otherwise, the variances are


Member of the class Profile - Sample

Method Profile::RowMaximize: computes row maxima, i.e. an horizontal profile with vertically largest pixel values

void RowMaximize(int Y, int Breadth, const Image& Src);

int Y: upper left point ordinate, in pixels, top-down

int Breadth: number of pixels, vertically

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Profile - Sample

Method Profile::RowMinimize: computes row minima, i.e. an horizontal profile with vertically smallest pixel values

void RowMinimize(int Y, int Breadth, const Image& Src);

int Y: upper left point ordinate, in pixels, top-down

int Breadth: number of pixels, vertically

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Profile - Sample

Method Profile::RowRange: computes row minima, i.e. an horizontal profile with vertical difference bewteen largest and smallest pixel values

void RowRange(int Y, int Breadth, const Image& Src);

int Y: upper left point ordinate, in pixels, top-down

int Breadth: number of pixels, vertically

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Profile - Sample

Method Profile::ColumnGet: gets the pixel profile along an image column

void ColumnGet(int X, const Image& Src);

int X: upper left point abscissa, in pixels

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb


Member of the class Profile - Sample

Method Profile::ColumnAdd: computes a column projection, i.e. a vertical profile with horizontally accumulated pixel values

void ColumnAdd(int X, int Breadth, const Image& Src, bool Average = true);

int X: upper left point abscissa, in pixels

int Breadth: number of pixels, horizontally

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

bool Average: when true, the accumulated values are averaged; otherwise, the sum is considered


Member of the class Profile - Sample

Method Profile::ColumnVariance: variance or standard deviation per image column

void ColumnVariance(int X, int Breadth, const Image& Src, bool RMS = true);

int X: upper left point abscissa, in pixels

int Breadth: number of pixels, horizontally

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool RMS: when true, the standard deviations are returned; otherwise, the variances are


Member of the class Profile - Sample

Method Profile::ColumnMaximize: computes column maxima, i.e. a vertical profile with horizontally largest pixel values

void ColumnMaximize(int X, int Breadth, const Image& Src);

int X: upper left point abscissa, in pixels

int Breadth: number of pixels, horizontally

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Profile - Sample

Method Profile::ColumnMinimize: computes column minima, i.e. a vertical profile with horizontally smallest pixel values

void ColumnMinimize(int X, int Breadth, const Image& Src);

int X: upper left point abscissa, in pixels

int Breadth: number of pixels, horizontally

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Profile - Sample

Method Profile::ColumnRange: computes column ranges, i.e. a vertical profile with horizontal difference bewteen largest and smallest pixel values

void ColumnRange(int X, int Breadth, const Image& Src);

int X: upper left point abscissa, in pixels

int Breadth: number of pixels, horizontally

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Profile - Sample

Method Profile::LineGet: gets the pixel profile along an image row

void LineGet(const XY& Beg, const XY& End, const Image& Src, bool Interpolate = true);

XY& Beg: coordinates of the starting point of the line; the first transverse profile starts exactly from this point

XY& End: coordinates of the ending point of the line; the last transverse profile will not pass this point

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Profile - Sample

Method Profile::LineAdd: computes a projection, i.e. an oblique profile with transversally accumulated pixel values

void LineAdd(const XY& Beg, const XY& End, int Breadth, const Image& Src, bool Average = true, bool Interpolate = true);

XY& Beg: coordinates of the starting point of the line; the first transverse profile starts exactly from this point

XY& End: coordinates of the ending point of the line; the last transverse profile will not pass this point

int Breadth: number of pixels, transversally; the transverse profiles are centered on the line

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb

bool Average: when true, averages the accumulated values; otherwise keeps the sum

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Profile - Sample

Method Profile::LineVariance: variance or standard deviation per image line

void LineVariance(const XY& Beg, const XY& End, int Breadth, const Image& Src, bool RMS = true, bool Interpolate = true);

XY& Beg: coordinates of the starting point of the line; the first transverse profile starts exactly from this point

XY& End: coordinates of the ending point of the line; the last transverse profile will not pass this point

int Breadth: number of pixels, transversally; the transverse profiles are centered on the line

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool RMS: when true, the standard deviations are returned; otherwise, the variances are

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Profile - Sample

Method Profile::LineMaximize: computes maxima, i.e. an oblique profile with transversally largest pixel values

void LineMaximize(const XY& Beg, const XY& End, int Breadth, const Image& Src, bool Interpolate = true);

XY& Beg: coordinates of the starting point of the line; the first transverse profile starts exactly from this point

XY& End: coordinates of the ending point of the line; the last transverse profile will not pass this point

int Breadth: number of pixels, transversally; the transverse profiles are centered on the line

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Profile - Sample

Method Profile::LineMinimize: computes minima, i.e. an oblique profile with transversally smallest pixel values

void LineMinimize(const XY& Beg, const XY& End, int Breadth, const Image& Src, bool Interpolate = true);

XY& Beg: coordinates of the starting point of the line; the first transverse profile starts exactly from this point

XY& End: coordinates of the ending point of the line; the last transverse profile will not pass this point

int Breadth: number of pixels, transversally; the transverse profiles are centered on the line

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Profile - Sample

Method Profile::LineRange: computes ranges, i.e. an oblique profile with transversal difference between largest and smallest pixel values

void LineRange(const XY& Beg, const XY& End, int Breadth, const Image& Src, bool Interpolate = true);

XY& Beg: coordinates of the starting point of the line; the first transverse profile starts exactly from this point

XY& End: coordinates of the ending point of the line; the last transverse profile will not pass this point

int Breadth: number of pixels, transversally; the transverse profiles are centered on the line

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Profile - Sample

Method Profile::CurveGet: gets the gray-values from an image along a given path

void CurveGet(const Path& Pathway, const Image& Src);

Path& Pathway: open or closed curve trace on the image

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb


Member of the class Profile - Interval of Interest

Method Profile::Window: restrict the profile to an interval of interest

void Window();

Method Profile::Window: reset the profile to its full extent

void Window(int I, int Length);

int I: starting index of the pixel or sample

int Length: number of pixels or samples


Member of the class Profile - Interval of Interest

Property int Profile::I: starting index of the pixel or sample


Member of the class Profile - Interval of Interest

Property int Profile::Length: number of pixels or samples


Member of the class Profile - Interval of Interest

Property bool Profile::HasWindow(): true when a profile window is in use


Member of the class Profile - Statistics

Method Profile::Quantile: the value that occurs at the given rank in the set of values

int Quantile(double Percent);

returned int: quantile value

double Percent: requested fraction, in the range [0..1]; 0.25, 0.5 and 0.75 for the quartiles


Member of the class Profile - Statistics

Method Profile::Median: the value that splits the values in two disjoint sets of equal size, computed from an existing profile

int Median();

returned int: the median value


Member of the class Profile - Statistics

Method Profile::Mean: the arithmetic mean of the sample values, computed from an existing profile

double Mean();

returned double: the mean value


Member of the class Profile - Statistics

Method Profile::TrimmedMean: a robust estimate of the mean, obtained by discarding outliers, computed from the profile samples

double TrimmedMean(double Percent);

returned double: the estimate of the mean

double Percent: the total amount of outlier values to be discarded


Member of the class Profile - Statistics

Method Profile::Range: the range of variation of the grayscale values, computed from the profile samples

void Range(int& Minimum, int& Maximum);

int& Minimum: the smallest pixel value encountered along the profile

int& Maximum: the largest pixel value encountered along the profile


Member of the class Profile - Statistics

Method Profile::Variance: the usual average squared deviation to the mean, computed from the profile samples

double Variance(double& Mean);

returned double: the variance estimate

double& Mean: the mean estimate, returned as a byproduct


Member of the class Profile - Filter

Method Profile::GaussLowPass: an approximation of the Gaussian blur filter; the computing time does not depend on the filter length

static void GaussLowPass(int FilterLength, const Profile& Src, Profile& Dst);

int FilterLength: length of the smoothing filter; must be an odd integer

Profile& Src: the source profile for this operation - remains unchanged, unless Src = Dst, unless Src=Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Profile - Filter

Method Profile::BoxLowPass: a uniform filter obtained by averaging in a sliding window around every value; the computing time does not depend on the box size

static void BoxLowPass(int FilterLength, const Profile& Src, Profile& Dst);

int FilterLength: length of the averaging box; must be an odd integer

Profile& Src: the source profile for this operation - remains unchanged, unless Src = Dst, unless Src=Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Profile - Filter

Method Profile::GaussHighPass: a high-pass filter obtained by subtracting the output of a Gaussian blur filter from the profile values; the computing time does not depend on the filter length

static void GaussHighPass(int FilterLength, const Profile& Src, Profile& Dst);

int FilterLength: length of the smoothing filter; must be an odd integer

Profile& Src: the source profile for this operation - remains unchanged after the operation

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Profile - Filter

Method Profile::BoxHighPass: a high-pass filter obtained by averaging in a sliding window around every value and subtracting from the original value; the computing time does not depend on the box size

static void BoxHighPass(int FilterLength, const Profile& Src, Profile& Dst);

int FilterLength: length of the averaging box; must be an odd integer

Profile& Src: the source profile for this operation - remains unchanged, unless Src = Dst, unless Src=Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Profile - Filter

Method Profile::Integrate: computes a simple integral by accumulating the profile values from left to right

static void Integrate(const Profile& Src, Profile& Dst);

Profile& Src: the source profile for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Profile - Filter

Method Profile::Derive: estimates the first derivative by a simple central difference formula (factor 2 omitted)

static void Derive(const Profile& Src, Profile& Dst);

Profile& Src: the source profile for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Profile - Analyze

Method Profile::EdgeDetect: detect significant gray-level changes in a 1D profile

void EdgeDetect(int MinimumStep, int Noise, enum Polarities Polarity, Profile& Dst);

int MinimumStep: minimum height of the gray step

int Noise: noise threshold; perturbations of a smaller amplitude are ignored

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both

Profile& Dst: destination profile, to receive the positions of the edges as indexes to the source profile

Method Profile::EdgeDetect: detect significant gray-level changes in a 1D profile

bool EdgeDetect(int MinimumStep, int Noise, enum Polarities Polarity, int Selection, double& X);

returned bool: true if a suitable edge was found; otherwise false

int MinimumStep: minimum height of the gray step

int Noise: noise threshold; perturbations of a smaller amplitude are ignored

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both

int Selection: as defined by the enum EdgeSelection

double& X: subpixel abscissa of the detected edge point


Member of the class Profile - Analyze

Method Profile::LocalExtrema: Detect local minima and/or maxima

void LocalExtrema(enum Polarities Polarity, Profile& Dst);

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Profile - Define LUT

Method Profile::GainOffset: defines a lookup table to apply a gain followed by an offset

void GainOffset(double Gain, double Offset, PixelTypes Type = Gray);

double Gain: floating-point gain

double Offset: offset added after multiplication the gain

PixelTypes Type: one of Gray or Gray16; if Undefined, keep the current profile settings


Member of the class Profile - Define LUT

Method Profile::Threshold: defines a lookup table to binarize with a threshold

void Threshold(int Threshold, int Black = 0, int White = ~0, PixelTypes Type = Gray);

int Threshold: threshold value in the grayscale range

int Black: color assigned to pixelsbelow the threshold

int White: color assigned to pixels above the threshold

PixelTypes Type: one of Gray or Gray16; if Undefined, keep the current profile settings


Member of the class Profile - Define LUT

Method Profile::BiThreshold: prepares a lookup-table for double thresholding, using threshold and threshold+delta limits

void BiThreshold(int Threshold, int Delta, int Black = 0, int MidGray = NotInitialized, int White = ~0, PixelTypes Type = Gray);

int Threshold: lower threshold value

int Delta: added to the threshold to get the upper threshold value

int Black: the grayscale value to be set on pixels below the threshold; black by default

int MidGray: the grayscale value to be set on pixels between the thresholds; intermediate gray by default

int White: the grayscale value to be set on pixels above the threshold plus delta; white by default

PixelTypes Type: image pixel data type


Member of the class Profile - Define LUT

Method Profile::Quantize: reduces the number of significant bits

void Quantize(int Resolution, PixelTypes Type = Gray);

int Resolution: all quantized values are integer multiples of the resolution

PixelTypes Type: one of Gray or Gray16; if Undefined, keep the current profile settings


Member of the class Profile - Define LUT

Method Profile::Logarithm: define a logarithmic or exponential transform

void Logarithm(bool Inverse, PixelTypes Type = Gray);

bool Inverse: when true, the logarithm is applied; else the antilogarithm

PixelTypes Type: image pixel data type


Member of the class Profile - Define LUT

Method Profile::Gamma: define a Gamma (exponent) transform

void Gamma(double Exponent, PixelTypes Type = Gray);

double Exponent: exponent value

PixelTypes Type: image pixel data type


Member of the class Profile - Define LUT

Method Profile::PseudoColor: defined a gamut of colors to be mapped to a grayscale

void PseudoColor(bool Inverse = false);

bool Inverse: when false as by default, maps the increasing gray-levels to a blue-green-red scale (increasing temperature); otherwise red-green-blue


Member of the class Profile - Sample Data

Method Profile::Sample: access the sample at a given index in a grayscale profile

Gray32Pixel& Sample(int I);

returned Gray32Pixel&: the requested sample; can be read of modified

int I: the sample index

Method Profile::Sample: access a component of the sample at a given index in a color profile

Gray32Pixel& Sample(int I, unsigned int Component);

returned Gray32Pixel&: the requested sample; can be read of modified

int I: the sample index

unsigned int Component: the color component (0 for gray or red, 1 for green, 2 for blue, 3 for alpha)


Member of the class Profile - Sample Data

Property int* Profile::Buffer: address of the profile data


Member of the class Profile - Sample Data

Property int Profile::Pitch: profile sample length, in bytes


Member of the class Profile - Graphics

Method Profile::Plot: draw a plot of the profile data in a rectangular area in the current window, as specified by the property Status::DrawTo

void Plot(int X, int Y, int Width, int Height, bool Frame = false, int MinValue = 0, int MaxValue = 0, int Sample[] = 0, int NumSamples = 1);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels, horizontally

int Height: number of pixels, vertically

bool Frame: true if a rectangular frame is drawn around the plot

int MinValue: lower bound of the range of values to be plotted on the vertical axis

int MaxValue: upper bound of the range of values to be plotted on the vertical axis

int* Sample: optional list of sample indexes for which vertical extension lines are drawn

int NumSamples: number of samples for which vertical extension lines are drawn


Member of the class Profile - Graphics

Method Profile::ToAsciiString: convert the content of the profile to tabular text

char* ToAsciiString(int SampleRow = All);

returned char*: ASCII null-terminated string

BlobSelection SampleRow: index of the desired row, in range 0..Length-1, or All


Member of the class Profile - Storage

Property PixelTypes Profile::Type: image pixel type, an enumerated value in PixelTypes; one of Gray, Gray16, Gray32, Rgb


Member of the class Profile - Storage

Property int Profile::Scale: profile data scaling factor; for internal use only


Member of the class Profile - Storage

Property int Profile::StoreLength: number of pixels or samples of the full profile


Member of the class Profile - Storage

Method Profile::Read: load the Profile data from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .prf extension recommended

Method Profile::Read: load the Profile data from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .prf extension recommended


Member of the class Profile - Storage

Method Profile::Write: save the Profile data to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .prf extension recommended

Method Profile::Write: save the Profile data to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .prf extension recommended


Member of the class Profile - Graphics

Method Profile::SetWindow: sets the size of the underlying image; needs to be called before drawing

void SetWindow(const Image& Src);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst


Member of the class Profile - Graphics

Property int Profile::X: upper left point abscissa, in pixels


Member of the class Profile - Graphics

Property int Profile::Y: upper left point ordinate, in pixels, top-down


Member of the class Profile - Graphics

Property int Profile::Width: number of pixels, horizontally


Member of the class Profile - Graphics

Property int Profile::Height: number of pixels, vertically


Member of the class Profile - Graphics

Property XY Profile::Beg: coordinates of the starting point of the line segment


Member of the class Profile - Graphics

Property XY Profile::End: coordinates of the ending point of the line segment


Member of the class Profile - Graphics

Property int Profile::XCol: abscissa of the profile column


Member of the class Profile - Graphics

Property int Profile::YRow: ordinate of the profile row


Member of the class Profile - Graphics

Property int Profile::Breadth: length of the transverse profiles used for computation


Member of the class Profile - Graphics

Property bool Profile::IsSum: true for a thick profile, i.e. a sum of rows/columns, false for a thin profile


Member of the class Profile - Graphics

Property DraggingHandles Profile::Direction: specifies the direction of the sampling area: NHandle for rows, WHandle for columns, AllHandle for an oblique line


Member of the class Profile - Graphics

Method Profile::Draw: draw a thin or thick line at the profile abscissa or ordinate (column or row)

void Draw(bool Handles = false);

bool Handles: when true, the dragging handles are drawn too


Member of the class Profile - Graphics

Method Profile::HitHandle: returns the dragging handle under the cursor

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: handle under the cursor, one of NoHandle, FromHandle or ToHandle

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class Profile - Graphics

Property DraggingHandles Profile::Handle: returns the last handle that was hit


Member of the class Profile - Graphics

Method Profile::Drag: move the current handle

void Drag(int CursorX, int CursorY);

int CursorX: upper left cursor abscissa, in pixels

int CursorY: upper left cursor ordinate, in pixels, top-down


Struct ArcSite

Element of a path with curved segments

Constructor ArcSite: creates a void ArcSite object

Constructor ArcSite: creates a void ArcSite object

Constructor ArcSite: creates a void ArcSite object

Coordinates

Property X: starting point abscissa, in pixels

Property Y: starting point ordinate, in pixels, top-down

Property A: aperture angle; 0 for a line segment


Member of the class ArcSite

Constructor ArcSite::ArcSite: creates a void ArcSite object

ArcSite(Site& S, double A);

Site& S: starting point of the arc

double A: amplitude of the arc between the current site and the next

indent: 2cm">double A: amplitude of the arc between the current site and the next


Member of the class ArcSite - Coordinates

Property short ArcSite::X: starting point abscissa, in pixels


Member of the class ArcSite - Coordinates

Property short ArcSite::Y: starting point ordinate, in pixels, top-down


Member of the class ArcSite - Coordinates

Property double ArcSite::A: aperture angle; 0 for a line segment


Class ArcPath

Reserved for internal use by the EdgeMap class

Constructor ArcPath: creates a void ArcPath object

Path Data

Method Clear: removes all points from the curvilinear path

Method Append: adds a site at the end of the path

Method Vertex: access the site at a given index in a curvilinear path

Graphics

Method Draw: draws the given curviinear path as a polyarc/line. If the path has the Closed property set to true, the polyarc/line is closed

Method HitHandle: identity of the handle under the cursor

Method ClosestHandle: find the path vertex which is closest to the cursor coordinates; the current zoom factor applies

Property Handle: one of NoHandle or AllHandle depedning on the result of the last call to HitHandle

Property HitIndex: index of the last vertex hit, -1 if none

Method Drag: drag the last hit vertex to a new position

Storage

Property Length: number of pixels or samples

Property Closed: true when the path is a closed loop, i.e. the last point is followed by the first one


Member of the class ArcPath

Constructor ArcPath::ArcPath: creates a void ArcPath object

ArcPath();


Member of the class ArcPath - Path Data

Method ArcPath::Clear: removes all points from the curvilinear path

void Clear();


Member of the class ArcPath - Path Data

Method ArcPath::Append: adds a site at the end of the path

void Append(int X, int Y, double A);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

double A: aperture angle of the next arc of this path

Method ArcPath::Append: adds a site at the end of the path

void Append(const ArcSite& S);

ArcSite& S: the site to be appended


Member of the class ArcPath - Path Data

Method ArcPath::Vertex: access the site at a given index in a curvilinear path

ArcSite& Vertex(int I);

returned ArcSite&: coordinates and curvature information

int I: starting index of the pixel or sample


Member of the class ArcPath - Graphics

Method ArcPath::Draw: draws the given curviinear path as a polyarc/line. If the path has the Closed property set to true, the polyarc/line is closed

void Draw(int VertexSize = 0, bool Edges = true);

int VertexSize: size of the dots used to draw the vertices; zero for no vertices

bool Edges: when true, the edges of the path are drawn; otherwise only the vertices


Member of the class ArcPath - Graphics

Method ArcPath::HitHandle: identity of the handle under the cursor

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: one of NoHandle or AllHandle

int CursorX: mouse cursor abscissa

int CursorY: mouse cursor ordinate


Member of the class ArcPath - Graphics

Method ArcPath::ClosestHandle: find the path vertex which is closest to the cursor coordinates; the current zoom factor applies

int ClosestHandle(int CursorX, int CursorY);

returned int: index of the closest vertex

int CursorX: cursor abscissa, in pixels

int CursorY: cursor ordinate, in pixels


Member of the class ArcPath - Graphics

Property DraggingHandles ArcPath::Handle: one of NoHandle or AllHandle depedning on the result of the last call to HitHandle


Member of the class ArcPath - Graphics

Property int ArcPath::HitIndex: index of the last vertex hit, -1 if none


Member of the class ArcPath - Graphics

Method ArcPath::Drag: drag the last hit vertex to a new position

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels


Member of the class ArcPath - Storage

Property int ArcPath::Length: number of pixels or samples


Member of the class ArcPath - Storage

Property bool ArcPath::Closed: true when the path is a closed loop, i.e. the last point is followed by the first one


Enumeration

Enum FittingModes: specifies how the fit is performed (accuracy/time tradeoff)

Case AverageFit: uses simple averaging of the points; CAUTION: only for full, noise-free circles

Case FastFit: uses a fast method

Case AccurateFit: uses an accurate method

Case RobustFit: performs well in the presence of outliers (up to 30%)


Class Path

A path is a sequence of 2D points. It can be used to define a connected contour or a polygon. When the Closed property is set to true, it is assumed that the last point is followed by the first one to form a closed loop

Constructor Path: creates a void Path object

Path Data

Method Clear: removes all points from the path

Method Append: adds a site at the end of the path

Method PolygonToRaster: converts a path containing vertices far apart (polygon) to a continuous path

Method ClosestTo: reports the index of the site in the path which is the closest to the given site. This method can be used for site selection with a mouse

Method Vertex: access the site at a given index in a path

Contouring

Method Follow: follows the contour of a blob from a seed point; the blob is defined by binarizing with a constant threshold value

Processing

Method Smooth: make a path smoother by discarding vertices that do not deviate much

Method LineFit: adjusts a line segment model over the points of the path; requires the Calibration or Gauging license

Method CircleFit: adjusts a circle/arc model over the points of the path; requires the Calibration or Gauging license

Method EllipseFit: adjust an ellipse on the points in the Path; requires the Calibration or Gauging license

Analysis

Method Box: bounding box of the path

Method Rectangle: tightest bounding rectangle, with allowed rotation

Method Parallelogram: tightest bounding parallelogram

Method Circle: tightest bounding circle

Method ConvexHull: builds the convex hull of the given path

Method Area: estmate of the area

Method Perimeter: estimate of the perimeter

Method Center: coordinates of the gravity center of the outline, assuming mass at the vertices only

Method FilledCenter: coordinates of the gravity center of the polygon, assuming uniform density over the area

Method FilledEllipse: the ellipse of inertia of the inside of a path, as defined by the laws of kinematics

Method Mass: the sum of the pixel values along the path

Method Centroid: the average coordinates of the pixels along the path, weighted by their gray value

Method LineDeviation: estimates the deviation from an ideal straight line, obtained by line fitting

Method CircleDeviation: estimates the deviation from an ideal straight circle, obtained by circle fitting

Method RectangleDeviation: Computes the average distance between a path and the outline of a rectangle

Method EllipseDeviation: Computes the average distance between a path and the outline of an ellipse

Method GrayHistogram: the histogram of the gray values of the pixels along the path

Method Vectorize: turns a closed digital path (Freeman moves) in a closed polyline

Graphics

Method Draw: draws the given path as a polyline. If the path has the Closed property set to true, the polyline is closed

Method HitHandle: identity of the handle under the cursor

Method ClosestHandle: find the path vertex which is closest to the cursor coordinates; the current zoom factor applies

Property Handle: identity of the last handle hit; one of NoHandle or AllHandle

Property HitIndex: index of the last vertex hit, -1 if none

Method PointInPath: checks if a point is inside the polygon formed by the path or not

Method Overlapping: checks if the polygons formed by two paths overlap or not

Method Drag: drag the last hit vertex to a new position

Method Insert: insert a vertex before or after the given index

Method Delete: remove the closest vertex

Method ToAsciiString: convert the content of the path to tabular text

Storage

Method Read: load the Path data from a file (ASCII or UNICODE path and name)

Method Write: save the Path data to a file (ASCII or UNICODE path and name)

Property Length: number of sites in the path

Property Buffer: gives direct access to the sites via a pointer; CAUTION: access at invalid offsets cause unpredictable effets.

Property Closed: true when the path is a closed loop, i.e. the last point is followed by the first one


Member of the class Path

Constructor Path::Path: creates a void Path object

Path();


Member of the class Path - Path Data

Method Path::Clear: removes all points from the path

void Clear();


Member of the class Path - Path Data

Method Path::Append: adds a site at the end of the path

void Append(int X, int Y);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

Method Path::Append: adds a site at the end of the path

void Append(const Site& S);

Site& S: the site to be appended


Member of the class Path - Path Data

Method Path::PolygonToRaster: converts a path containing vertices far apart (polygon) to a continuous path

void PolygonToRaster(Path& Dst);

Path& Dst: the destinaiton path that receives the rasterized polygon


Member of the class Path - Path Data

Method Path::ClosestTo: reports the index of the site in the path which is the closest to the given site. This method can be used for site selection with a mouse

int ClosestTo(Site& S);

returned int: the index of the closest site in the path

Site& S: the targeted site


Member of the class Path - Path Data

Method Path::Vertex: access the site at a given index in a path

Site& Vertex(int I);

returned Site&: the requested site; can be read of modified

int I: index of the site in the path


Member of the class Path - Contouring

Method Path::Follow: follows the contour of a blob from a seed point; the blob is defined by binarizing with a constant threshold value

void Follow(Site& Seed, int Threshold, const Image& Src, bool Above = true, bool Connexity8 = true, bool AlwaysClosed = true);

Site& Seed: the starting site, in range [0..Width-1], [0..Height-1]

int Threshold: constant threshold value used for binarization

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool Above: when true, the blob is formed by all pixels above or on the threshold value

bool Connexity8: the contour will be 8-connected

bool AlwaysClosed: defines how the contours of blobs against an image border are handled; when true, the contour follows the border to ensure that it is closed; when false, the contour stops at the outline and remains open


Member of the class Path - Processing

Method Path::Smooth: make a path smoother by discarding vertices that do not deviate much

void Smooth(Path& Dst, double Deviation = 3);

Path& Dst: the destination path that receives the smoothed result

double Deviation: deviation tolerance, in pixels


Member of the class Path - Processing

Method Path::LineFit: adjusts a line segment model over the points of the path; requires the Calibration or Gauging license

bool LineFit(XY& Center, double& Angle, FittingModes Mode = AccurateFit);

returned bool: returns true when the fit succeeded; if false, the point configuration is degenerate

XY& Center: some point on the fitted line

double& Angle: orientation angle of the line, in the current angle unit

FittingModes Mode: fitting mode, as specified by enum FittingModes; for a line segment, AverageFit, FastFit and AccurateFit are synonymous


Member of the class Path - Processing

Method Path::CircleFit: adjusts a circle/arc model over the points of the path; requires the Calibration or Gauging license

bool CircleFit(XY& Center, double& Radius, FittingModes Mode = AccurateFit);

returned bool: returns true when the fit succeeded; if false, the point configuration is degenerate

XY& Center: coordinates of the fitted circle

double& Radius: radius of the fitted circle

FittingModes Mode: fitting mode, as specified by enum FittingModes; for a circle,


Member of the class Path - Processing

Method Path::EllipseFit: adjust an ellipse on the points in the Path; requires the Calibration or Gauging license

bool EllipseFit(XY& Center, XY& Axis, double& Angle, FittingModes Mode = AccurateFit);

returned bool: true when fitting has succeeded; otherwise false

XY& Center: ellipse center

XY& Axis: long and short axis lengths (X and Y components)

double& Angle: main axis direction angle, in the current angle unit

FittingModes Mode: fitting mode, as specified by enum FittingModes; for an ellipse, AverageFit and FastFit are synonymous


Member of the class Path - Analysis

Method Path::Box: bounding box of the path

void Box(int& X, int& Y, int& Width, int& Height);

int& X: leftmost abscissa

int& Y: topmost ordinate

int& Width: number of pixels, horizontally

int& Height: number of pixels, vertically


Member of the class Path - Analysis

Method Path::Rectangle: tightest bounding rectangle, with allowed rotation

void Rectangle(double& Xc, double& Yc, double& Width, double& Height, double& Angle, bool Simple = true);

double& Xc: center abscissa

double& Yc: center ordinate

double& Width: shortes dimension

double& Height: largest dimension

double& Angle: rotation angle

bool Simple: use true, as by default, if the polygon is known to be simple; false otherwise


Member of the class Path - Analysis

Method Path::Parallelogram: tightest bounding parallelogram

void Parallelogram(XY& P, XY& Q, XY& R, bool Simple = true);

XY& P: first vertex

XY& Q: second vertex

XY& R: third vertex; the fourth is obtained by vector addition

bool Simple: use true, as by default, if the polygon is known to be simple; false otherwise


Member of the class Path - Analysis

Method Path::Circle: tightest bounding circle

void Circle(double& Xc, double& Yc, double& Radius, bool Simple = true);

double& Xc: center abscissa

double& Yc: center ordinate

double& Radius: radius

bool Simple: use true, as by default, if the polygon is known to be simple; false otherwise


Member of the class Path - Analysis

Method Path::ConvexHull: builds the convex hull of the given path

void ConvexHull(Path& Dst, bool Simple = false);

Path& Dst: hull polygon

bool Simple: false for an arbitrary point set; true if the polygon is known to be clockwise and simple (no self-intersections)


Member of the class Path - Analysis

Method Path::Area: estmate of the area

int Area();

returned int: polygon area value


Member of the class Path - Analysis

Method Path::Perimeter: estimate of the perimeter

double Perimeter(bool Euclidean = true);

returned double: perimeter value, the sum of lengths

bool Euclidean: when true, the Euclidean distance between vertices is used (L2-norm); otherwise, the total number of pixels per segment is used (L-inf norm)


Member of the class Path - Analysis

Method Path::Center: coordinates of the gravity center of the outline, assuming mass at the vertices only

void Center(double& X, double& Y);

double& X: computed center abscissa

double& Y: computed center ordinate


Member of the class Path - Analysis

Method Path::FilledCenter: coordinates of the gravity center of the polygon, assuming uniform density over the area

bool FilledCenter(int& Area, double& X, double& Y);

returned bool: false when the area was found to be 0

int& Area: area, in pixels

double& X: computed centroid abscissa

double& Y: computed centroid ordinate


Member of the class Path - Analysis

Method Path::FilledEllipse: the ellipse of inertia of the inside of a path, as defined by the laws of kinematics

bool FilledEllipse(int& Area, double& X, double& Y, double& Width, double& Height, double& Angle, double& Eccentricity);

returned bool: false in case the area is null; then no other parameter is computed

int& Area: area, in pixels

double& X: abscissa of the center of inertia

double& Y: ordinate of the center of inertia

double& Width: major ellipse axis

double& Height: minor ellipse axis

double& Angle: direction of the major axis

double& Eccentricity: elongation of the ellipsoid; between 0 for a circle and 1 for a flat ellipse


Member of the class Path - Analysis

Method Path::Mass: the sum of the pixel values along the path

int Mass(const Image& Src);

returned int: the mass value

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Path - Analysis

Method Path::Centroid: the average coordinates of the pixels along the path, weighted by their gray value

bool Centroid(const Image& Src, int& Mass, double& X, double& Y);

returned bool: true if the centroid is defined (nonzero Mass)

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

int& Mass: the mass value

double& X: abscissa of the centroid

double& Y: ordinate of the centroid


Member of the class Path - Analysis

Method Path::LineDeviation: estimates the deviation from an ideal straight line, obtained by line fitting

double LineDeviation(XY Center, double Angle, bool RMS = true);

returned double: Mean absolute or RMS deviation from the ideal line

XY Center: known point of line (may be obtained from LineFit)

double Angle: known orientation angle of line (may be obtained from LineFit)

bool RMS: when true, the root-mean-square formula is used; when false, the mean absolute distance


Member of the class Path - Analysis

Method Path::CircleDeviation: estimates the deviation from an ideal straight circle, obtained by circle fitting

double CircleDeviation(XY Center, double Radius, bool RMS = true);

returned double: Mean absolute or RMS deviation from the ideal circle

XY Center: known circle center (may be obtained from CircleFit)

double Radius: known circle radius (may be obtained from CircleFit)

bool RMS: when true, the root-mean-square formula is used; when false, the mean absolute distance


Member of the class Path - Analysis

Method Path::RectangleDeviation: Computes the average distance between a path and the outline of a rectangle

double RectangleDeviation(XY Center, XY Sides, double Angle, bool RMS = true);

returned double: average distance

XY Center: rectangle center

XY Sides: rectangle width and height

double Angle: orientation angle in the current angle unit; horizontal width is 0

bool RMS: root-mean-square value instead of arithmetic average


Member of the class Path - Analysis

Method Path::EllipseDeviation: Computes the average distance between a path and the outline of an ellipse

double EllipseDeviation(XY Center, XY Axis, double Angle, bool RMS = true, int NumIterations = 0);

returned double: average distance

XY Center: ellipse center

XY Axis: ellipse major and minor axis

double Angle: orientation angle of the major axis; horizontal major is 0

bool RMS: root-mean-square value instead of arithmetic average

int NumIterations: an iterative method being used, specify an iteration count between 0 (acceptable) and 3 (very accurate)


Member of the class Path - Analysis

Method Path::GrayHistogram: the histogram of the gray values of the pixels along the path

void GrayHistogram(const Image& Src, Histogram& Dst, bool Clear = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Histogram& Dst: destination histogram

bool Clear: when true, the previous content of the histogram is reset


Member of the class Path - Analysis

Method Path::Vectorize: turns a closed digital path (Freeman moves) in a closed polyline

void Vectorize(Path& Dst, double Deviation = 0.5);

Path& Dst: the destination path that will containthe polyline

double Deviation: maximum allowed distance between a path and the vectorized polyline, in pixels

Method Path::Vectorize: turns a closed digital path (Freeman moves) in a closed polyline

void Vectorize(ArcPath& Dst, double Deviation = 0.5);

ArcPath& Dst: the destination path that will containthe polyline

double Deviation: maximum allowed distance between a path and the vectorized polyline, in pixels


Member of the class Path - Graphics

Method Path::Draw: draws the given path as a polyline. If the path has the Closed property set to true, the polyline is closed

void Draw(int VertexSize = 0, bool Edges = true);

int VertexSize: size of the dots used to represent the vertices, using the convention in Graph::Dot

bool Edges: when true, as by default, the edges between the vertices are drawn


Member of the class Path - Graphics

Method Path::HitHandle: identity of the handle under the cursor

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: one of NoHandle or AllHandle

int CursorX: mouse cursor abscissa

int CursorY: mouse cursor ordinate


Member of the class Path - Graphics

Method Path::ClosestHandle: find the path vertex which is closest to the cursor coordinates; the current zoom factor applies

int ClosestHandle(int CursorX, int CursorY);

returned int: index of the closest vertex

int CursorX: cursor abscissa, in pixels

int CursorY: cursor ordinate, in pixels


Member of the class Path - Graphics

Property DraggingHandles Path::Handle: identity of the last handle hit; one of NoHandle or AllHandle


Member of the class Path - Graphics

Property int Path::HitIndex: index of the last vertex hit, -1 if none


Member of the class Path - Graphics

Method Path::PointInPath: checks if a point is inside the polygon formed by the path or not

bool PointInPath(const Site& P);

returned bool: true when the point is inside; no particular guarantee is given for points on the outline

Site& P: the test point


Member of the class Path - Graphics

Method Path::Overlapping: checks if the polygons formed by two paths overlap or not

bool Overlapping(const Path& Src);

returned bool: true when there is (partial) overlap

Path& Src: the second path


Member of the class Path - Graphics

Method Path::Drag: drag the last hit vertex to a new position

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels


Member of the class Path - Graphics

Method Path::Insert: insert a vertex before or after the given index

void Insert(int CursorX, int CursorY, bool Before = true);

int CursorX: cursor abscissa, in pixels

int CursorY: cursor ordinate, in pixels

bool Before: when true, the point is inserted before the last closest handle in the natural order; otherwise, it is inserted after


Member of the class Path - Graphics

Method Path::Delete: remove the closest vertex

void Delete();


Member of the class Path - Graphics

Method Path::ToAsciiString: convert the content of the path to tabular text

char* ToAsciiString(int SampleVertex = All);

returned char*: ASCII null-terminated string

BlobSelection SampleVertex: intex of the desired vertex along the path, or All


Member of the class Path - Storage

Method Path::Read: load the Path data from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .pth extension recommended

Method Path::Read: load the Path data from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .pth extension recommended


Member of the class Path - Storage

Method Path::Write: save the Path data to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .pth extension recommended

Method Path::Write: save the Path data to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .pth extension recommended


Member of the class Path - Storage

Property int Path::Length: number of sites in the path


Member of the class Path - Storage

Property Site* Path::Buffer(): gives direct access to the sites via a pointer; CAUTION: access at invalid offsets cause unpredictable effets.


Member of the class Path - Storage

Property bool Path::Closed: true when the path is a closed loop, i.e. the last point is followed by the first one


Struct RunData

Reserved; run descriptor

Property X0: reserved; begin abscissa

Property X1: reserved; end abscissa

Property Y: reserved; ordinate


Member of the class RunData

Property short RunData::X0: reserved; begin abscissa


Member of the class RunData

Property short RunData::X1: reserved; end abscissa


Member of the class RunData

Property short RunData::Y: reserved; ordinate


Class Histogram

A histogram is a statistical measure of the pixel gray value distribution; its counts the number of pixels for every possible gray level and is used for global characterization of the image

Frequency Data

Method Bin: access the bin at a given index in a histogram

Method ClearBins: resets all bins to the zero value

Compute

Method Compute: accumulates the pixel counts for the given image

Method Cumulate: computes the cumulative histogram associated to the given histogram, i.e. the prefix sum of the bin values

Statistics

Method Count: count pixels above or below a given threshold, computed from an existing histogram

Method Mean: the arithmetic mean of the pixel values, computed from an existing histogram

Method Median: the value that splits the histogram area in two equal parts, computed from an existing histogram

Method Mode: the value that has the highest frequency in an histogram

Method TrimmedMean: a robust estimate of the mean, obtained by discarding outliers, computed from an existing histogram

Method Range: the range of variation of the grayscale values, computed from an existing histogram

Method Variance: the usual average squared deviation to the mean, computed from an existing histogram

Method Covariance: Compute the variance/covariance matrix between the RGB components

Method MedianAbsoluteDeviation: average of the absolute deviations between the samples and the histogram median, computed from an existing histogram; this is a robust estimator of the spread of the distribution

Method Quantile: the value that has a given fraction of the histogram area before it, computed from an existing histogram

Method Skewness: measure of the asymmetry of the probability distribution of the histogram

Method Kurtosis: measure of the peakedness of the probability distribution of the histogram

Method Entropy: statistical measure of the information contained in the histogram, as defined by information theory

Method BestThreshold: a suitable threshold value for use in binarization, obtained by analysis of the variance of an existing histogram; when the image essentially contains two shades of gray, this method performs extremely well

Method EntropyThreshold: computes an automatic threshold based on the Maximum Entropy criterion (Kapur & al.); applies to an histogram

Method IsodataThreshold: computes an automatic threshold based on the ISODATA criterion (Ridler & al.); applies to an histogram

Filter

Method GaussLowPass: an approximation of the Gaussian blur filter; the computing time does not depend on the filter length

Method BoxLowPass: a uniform filter obtained by averaging in a sliding window around every bin value; the computing time does not depend on the box size

Method GaussHighPass: a high-pass filter obtained by subtracting the output of a Gaussian blur filter from the frequency values; the computing time does not depend on the filter length

Method BoxHighPass: a high-pass filter obtained by averaging in a sliding window around every bin value and subtracting from the original value; the computing time does not depend on the box size

Method Integrate: computes a simple integral by accumulating the bin values from left to right

Method Derive: estimates the first derivative by a simple central difference formula (factor 2 omitted)

Image Quality

Method Noise: Estimate of the noise level, the standard deviation of the distribution, assuming a Gaussian model

Method ShowNoise: Shows an estimate of the local noise intensity

Method Saturation: indicates the fractions of saturated pixels, allowing to adjust camera gain/offset

Method ShowSaturation: prepares an image for display of the saturated areas, in blue and red

Compare Images

Method CountDifferences: reports the number of different pixels between two images

Method SumAbsoluteDifferences: Sum of Absolute Differences (SAD) between respective pixels in two images

Method SumSquaredDifferences: Sum of Squared Differences (SSD) between respective pixels in two images

Method NormalizedCorrelation: Correlation coefficient between respective pixels in two images

Method Normalize: ajust the second source image to the same dynamics as the first (by average and standard deviation), by linear mapping

Method ShowDifferences: compare two images and enhance the positive [negative] differences in red [blue]

Graphics

Method Plot: draw a plot of the profile data in a rectangular area in the current window, as specified by the property Status::DrawTo

Method ToAsciiString: convert the content of the histogram bins to tabular text


Member of the class Histogram - Frequency Data

Method Histogram::Bin: access the bin at a given index in a histogram

int& Bin(int I);

returned int&: the requested bin value; can be read or modified

int I: index of the bin

Method Histogram::Bin: access the bin at a given index in a histogram

int& Bin(int I, ColorComponents Component);

returned int&: the requested bin value; can be read or modified

int I: index of the bin

ColorComponents Component: the color component (0 for gray or red, 1 for green, 2 for blue)


Member of the class Histogram - Frequency Data

Method Histogram::ClearBins: resets all bins to the zero value

void ClearBins();


Member of the class Histogram - Compute

Method Histogram::Compute: accumulates the pixel counts for the given image

void Compute(const Image& Src, bool Clear = true);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16

bool Clear: when true, as by default, the histogram bins are cleared before computation; when false, the previous bin contents are kept and accumulation continues

Method Histogram::Compute: accumulates the pixel counts for the given image; only pixels spanned by the region are counted

void Compute(const Image& Src, const Region& Mask, bool Clear = true);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16

Region& Mask: the mask to be used to delimit the region of the image to be processed

bool Clear: when true, as by default, the histogram bins are cleared before computation; when false, the previous bin contents are kept and accumulation continues

Method Histogram::Compute: accumulates the pixel counts for the given image

void Compute(const Profile& Src, bool Clear = true);

Profile& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16

bool Clear: when true, as by default, the histogram bins are cleared before computation; when false, the previous bin contents are kept and accumulation continues


Member of the class Histogram - Compute

Method Histogram::Cumulate: computes the cumulative histogram associated to the given histogram, i.e. the prefix sum of the bin values

void Cumulate(const Histogram& Src);

Histogram& Src: the source histogram


Member of the class Histogram - Statistics

Method Histogram::Count: count pixels above or below a given threshold, computed from an existing histogram

int Count(int Threshold, bool Above);

returned int: number of pixels

int Threshold: binarization threshold value

bool Above: when true, consider the pixels with a value lighter than the threshold; otherwise, consider those with a darker value

Method Histogram::Count: count pixels above or below a given threshold, computed from an image

static int Count(int Threshold, bool Above, const Image& Src);

returned int: number of pixels

int Threshold: binarization threshold value

bool Above: when true, consider the pixels with a value lighter than the threshold; otherwise, consider those with a darker value

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Histogram - Statistics

Method Histogram::Mean: the arithmetic mean of the pixel values, computed from an existing histogram

double Mean();

returned double: the mean value

Method Histogram::Mean: the arithmetic mean of all pixel values in an image

static double Mean(const Image& Src);

returned double: the mean value

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

Method Histogram::Mean: the arithmetic mean of the pixel values, computed from an existing histogram

void Mean(double& MeanR, double& MeanG, double& MeanB);

double& MeanR: the red mean estimate

double& MeanG: the green mean estimate

double& MeanB: the blue mean estimate

Method Histogram::Mean: the arithmetic mean of the pixel values, computed from an existing histogram

static void Mean(const Image& Src, double& MeanR, double& MeanG, double& MeanB);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

double& MeanR: the red mean estimate

double& MeanG: the green mean estimate

double& MeanB: the blue mean estimate


Member of the class Histogram - Statistics

Method Histogram::Median: the value that splits the histogram area in two equal parts, computed from an existing histogram

int Median();

returned int: the median value

Method Histogram::Median: the value that splits the histogram area in two equal parts, computed from an image

static int Median(const Image& Src);

returned int: the median value

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16


Member of the class Histogram - Statistics

Method Histogram::Mode: the value that has the highest frequency in an histogram

int Mode();

returned int: histogram mode

Method Histogram::Mode: the pixel value that has the highest frequency in an image

static int Mode(const Image& Src);

returned int: histogram mode

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only


Member of the class Histogram - Statistics

Method Histogram::TrimmedMean: a robust estimate of the mean, obtained by discarding outliers, computed from an existing histogram

double TrimmedMean(double Percent);

returned double: the estimate of the mean

double Percent: the total amount of outlier values to be discarded

Method Histogram::TrimmedMean: a robust estimate of the mean, obtained by discarding outliers, computed from an image

static double TrimmedMean(double Percent, const Image& Src);

returned double: the estimate of the mean

double Percent: the total amount of outlier values to be discarded

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16


Member of the class Histogram - Statistics

Method Histogram::Range: the range of variation of the grayscale values, computed from an existing histogram

void Range(int& Minimum, int& Maximum);

int& Minimum: the smallest pixel value encountered

int& Maximum: the largest pixel value encountered

Method Histogram::Range: the range of variation of the grayscale values of all pixels in an image

static void Range(const Image& Src, int& Minimum, int& Maximum);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

int& Minimum: the smallest pixel value encountered

int& Maximum: the largest pixel value encountered

Method Histogram::Range: the range of variation of the grayscale values, computed from an existing histogram

void Range(RgbPixel& Minimum, RgbPixel& Maximum);

RgbPixel& Minimum: the smallest pixel value encountered

RgbPixel& Maximum: the largest pixel value encountered

Method Histogram::Range: the range of variation of the grayscale values, computed from an existing histogram

static void Range(const Image& Src, RgbPixel& Minimum, RgbPixel& Maximum);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

RgbPixel& Minimum: the smallest pixel value encountered

RgbPixel& Maximum: the largest pixel value encountered


Member of the class Histogram - Statistics

Method Histogram::Variance: the usual average squared deviation to the mean, computed from an existing histogram

double Variance(double& Mean);

returned double: the variance estimate

double& Mean: the mean estimate, returned as a byproduct

Method Histogram::Variance: the usual average squared deviation to the mean, computed from an image

static double Variance(const Image& Src, double& Mean);

returned double: the variance estimate

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

double& Mean: the mean estimate, returned as a byproduct

Method Histogram::Variance: the usual average squared deviation to the mean, computed from an existing histogram

double Variance(double& MeanR, double& MeanG, double& MeanB);

returned double: the variance estimate

double& MeanR: the red mean estimate, returned as a byproduct

double& MeanG: the green mean estimate, returned as a byproduct

double& MeanB: the blue mean estimate, returned as a byproduct

Method Histogram::Variance: the usual average squared deviation to the mean, computed from an existing histogram

static double Variance(const Image& Src, double& MeanR, double& MeanG, double& MeanB);

returned double: the variance estimate

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

double& MeanR: the red mean estimate, returned as a byproduct

double& MeanG: the green mean estimate, returned as a byproduct

double& MeanB: the blue mean estimate, returned as a byproduct


Member of the class Histogram - Statistics

Method Histogram::Covariance: Compute the variance/covariance matrix between the RGB components

static void Covariance(const Image& Src, double& VarianceR, double& VarianceG, double& VarianceB, double& CovarianceRB, double& CovarianceRG, double& CovarianceGB, double& MeanR, double& MeanG, double& MeanB);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

double& VarianceR: variance of the red component

double& VarianceG: variance of the green component

double& VarianceB: variance of the blue component

double& CovarianceRB: covariance of the red and blue components

double& CovarianceRG: covariance of the red and green components

double& CovarianceGB: covariance of the green and blue components

double& MeanR: the Red mean estimate

double& MeanG: the Green mean estimate

double& MeanB: the Blue mean estimate


Member of the class Histogram - Statistics

Method Histogram::MedianAbsoluteDeviation: average of the absolute deviations between the samples and the histogram median, computed from an existing histogram; this is a robust estimator of the spread of the distribution

double MedianAbsoluteDeviation(int& Median);

returned double: estimated MAD value

int& Median: the histogram median, returned as a byproduct

Method Histogram::MedianAbsoluteDeviation: average of the absolute deviations between the samples and the histogram median computed from an image; this is a robust estimator of the spread of the distribution

static double MedianAbsoluteDeviation(const Image& Src, int& Median);

returned double: estimated MAD value

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16

int& Median: the histogram median, returned as a byproduct


Member of the class Histogram - Statistics

Method Histogram::Quantile: the value that has a given fraction of the histogram area before it, computed from an existing histogram

int Quantile(double Percent);

returned int: the quantile value

double Percent: the fraction of the distribution to be considered; 0.25 and 0.75 give the first and third quartiles

Method Histogram::Quantile: the value that has a given fraction of the histogram area before it, computed from an image

static int Quantile(double Percent, const Image& Src);

returned int: the quantile value

double Percent: the fraction of the distribution to be considered; 0.25 and 0.75 give the first and third quartiles

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16


Member of the class Histogram - Statistics

Method Histogram::Skewness: measure of the asymmetry of the probability distribution of the histogram

double Skewness(double& Mean, double& Variance);

returned double: normalized skewness, the ratio of the centered moments of the third and second order

double& Mean: mean of the distribution

double& Variance: variance of the distribution

Method Histogram::Skewness: measure of the asymmetry of the probability distribution of pixel values in an image

static double Skewness(const Image& Src, double& Mean, double& Variance);

returned double: normalized skewness, the ratio of the centered moments of the third and second order

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

double& Mean: mean of the distribution

double& Variance: variance of the distribution


Member of the class Histogram - Statistics

Method Histogram::Kurtosis: measure of the peakedness of the probability distribution of the histogram

double Kurtosis(double& Mean, double& Variance);

returned double: normalized kurtosis, the ratio of the centered moments of the fourth and second order

double& Mean: mean of the distribution

double& Variance: variance of the distribution

Method Histogram::Kurtosis: measure of the peakedness of the probability distribution of pixel values in an image

static double Kurtosis(const Image& Src, double& Mean, double& Variance);

returned double: normalized kurtosis, the ratio of the centered moments of the fourth and second order

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

double& Mean: mean of the distribution

double& Variance: variance of the distribution


Member of the class Histogram - Statistics

Method Histogram::Entropy: statistical measure of the information contained in the histogram, as defined by information theory

double Entropy();

returned double: number of bits of information

Method Histogram::Entropy: statistical measure of the information contained in the image histogram, as defined by information theory

static double Entropy(const Image& Src);

returned double: number of bits of information

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only


Member of the class Histogram - Statistics

Method Histogram::BestThreshold: a suitable threshold value for use in binarization, obtained by analysis of the variance of an existing histogram; when the image essentially contains two shades of gray, this method performs extremely well

int BestThreshold();

returned int: the binarization threshold

Method Histogram::BestThreshold: a suitable threshold value for use in binarization, obtained by analysis of the variance of the pixel values in an image; when the image essentially contains two shades of gray, this method performs extremely well

static int BestThreshold(const Image& Src);

returned int: the binarization threshold

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only


Member of the class Histogram - Statistics

Method Histogram::EntropyThreshold: computes an automatic threshold based on the Maximum Entropy criterion (Kapur & al.); applies to an histogram

int EntropyThreshold();

returned int: the threshold value

Method Histogram::EntropyThreshold: computes an automatic threshold based on the Maximum Entropy criterion (Kapur & al.); applies to an image

static int EntropyThreshold(const Image& Src);

returned int: the threshold value

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Histogram - Statistics

Method Histogram::IsodataThreshold: computes an automatic threshold based on the ISODATA criterion (Ridler & al.); applies to an histogram

int IsodataThreshold();

returned int: the threshold value

Method Histogram::IsodataThreshold: computes an automatic threshold based on the ISODATA criterion (Ridler & al.); applies to an image

static int IsodataThreshold(const Image& Src);

returned int: the threshold value

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Histogram - Filter

Method Histogram::GaussLowPass: an approximation of the Gaussian blur filter; the computing time does not depend on the filter length

static void GaussLowPass(int FilterLength, const Profile& Src, Profile& Dst);

int FilterLength: length of the smoothing filter; must be an odd integer

Profile& Src: the source profile for this operation - remains unchanged, unless Src = Dst, unless Src=Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Histogram - Filter

Method Histogram::BoxLowPass: a uniform filter obtained by averaging in a sliding window around every bin value; the computing time does not depend on the box size

static void BoxLowPass(int FilterLength, const Profile& Src, Profile& Dst);

int FilterLength: length of the averaging box; must be an odd integer

Profile& Src: the source profile for this operation - remains unchanged, unless Src = Dst, unless Src=Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Histogram - Filter

Method Histogram::GaussHighPass: a high-pass filter obtained by subtracting the output of a Gaussian blur filter from the frequency values; the computing time does not depend on the filter length

static void GaussHighPass(int FilterLength, const Profile& Src, Profile& Dst);

int FilterLength: length of the smoothing filter; must be an odd integer

Profile& Src: the source profile for this operation - remains unchanged after the operation

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Histogram - Filter

Method Histogram::BoxHighPass: a high-pass filter obtained by averaging in a sliding window around every bin value and subtracting from the original value; the computing time does not depend on the box size

static void BoxHighPass(int FilterLength, const Profile& Src, Profile& Dst);

int FilterLength: length of the averaging box; must be an odd integer

Profile& Src: the source profile for this operation - remains unchanged, unless Src = Dst, unless Src=Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Histogram - Filter

Method Histogram::Integrate: computes a simple integral by accumulating the bin values from left to right

static void Integrate(const Profile& Src, Profile& Dst);

Profile& Src: the source histogram for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination histogram, which is computed by this operation


Member of the class Histogram - Filter

Method Histogram::Derive: estimates the first derivative by a simple central difference formula (factor 2 omitted)

static void Derive(const Profile& Src, Profile& Dst);

Profile& Src: the source histogram for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Gray32, Rgb

Profile& Dst: the destination profile, which is computed by this operation


Member of the class Histogram - Image Quality

Method Histogram::Noise: Estimate of the noise level, the standard deviation of the distribution, assuming a Gaussian model

static double Noise(const Image& Src, bool Large = false);

returned double: Noise level value

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Large: when true, a 5x5 filter is used for evaluation; otherwise, as by default, 3x3


Member of the class Histogram - Image Quality

Method Histogram::ShowNoise: Shows an estimate of the local noise intensity

static void ShowNoise(const Image& Src, Image& Dst, bool Large = false);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Large: when true, a 5x5 filter is used for evaluation; otherwise, as by default, 3x3


Member of the class Histogram - Image Quality

Method Histogram::Saturation: indicates the fractions of saturated pixels, allowing to adjust camera gain/offset

static void Saturation(const Image& Src, int& Darkest, int& Lightest, double& BlackFraction, double& WhiteFraction);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

int& Darkest: gray level of the darkest pixel (component); usually 0

int& Lightest: gray level of the lightest pixel (component); usually 255

double& BlackFraction: proportion of pixels saturated towards black

double& WhiteFraction: proportion of pixels saturated towards white


Member of the class Histogram - Image Quality

Method Histogram::ShowSaturation: prepares an image for display of the saturated areas, in blue and red

static void ShowSaturation(const Image& Src, Image& Dst, int Dark = NotInitialized, int Light = NotInitialized);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

int Dark: the pixels darker than this threshold are rendered in blue; by default, the darkest pixels

int Light: the pixels lighter than this threshold are rendered in red; by default, the lightest pixels


Member of the class Histogram - Compare Images

Method Histogram::CountDifferences: reports the number of different pixels between two images

static int CountDifferences(const Image& Src, const Image& SrcB);

returned int: difference count; 0 in case of twice the same image

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& SrcB: the second source image for this operation - remains unchanged, unless Src = Dst


Member of the class Histogram - Compare Images

Method Histogram::SumAbsoluteDifferences: Sum of Absolute Differences (SAD) between respective pixels in two images

static double SumAbsoluteDifferences(const Image& Src, const Image& SrcB, bool Average = true);

returned double: the total or average difference

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& SrcB: the second source image for this operation - remains unchanged after the operation

bool Average: when true, averages the accumulated values; otherwise keeps the sum


Member of the class Histogram - Compare Images

Method Histogram::SumSquaredDifferences: Sum of Squared Differences (SSD) between respective pixels in two images

static double SumSquaredDifferences(const Image& Src, const Image& SrcB, bool RMS = true);

returned double: the total or RMS (square root of the average) difference

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& SrcB: the second source image for this operation - remains unchanged after the operation

bool RMS: when true, the square root of the average of the squared differences is returned; otherwise the sum of squared differences is


Member of the class Histogram - Compare Images

Method Histogram::NormalizedCorrelation: Correlation coefficient between respective pixels in two images

static double NormalizedCorrelation(const Image& Src, const Image& SrcB);

returned double: the correlation value, in range [-1..+1]

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& SrcB: the second source image for this operation - remains unchanged after the operation


Member of the class Histogram - Compare Images

Method Histogram::Normalize: ajust the second source image to the same dynamics as the first (by average and standard deviation), by linear mapping

static void Normalize(double Mean, double Variance, const Image& Src, Image& Dst, double& Gain, double& Offset);

double Mean: image mean to be achieved by the normalization

double Variance: image variance to be achived by the normalization

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

double& Gain: computed gain used to perform the adjustment (Gain * value + Offset)

double& Offset: computed offset used to perform the adjustment (Gain * value + Offset)

Method Histogram::Normalize: ajust the second source image to the same dynamics as the first (by average and standard deviation), by linear mapping

static void Normalize(double MeanR, double MeanG, double MeanB, double Variance, const Image& Src, Image& Dst, double& Gain, double& OffsetR, double& OffsetG, double& OffsetB);

double MeanR: image mean to be achieved in the Red channel by the normalization

double MeanG: image mean to be achieved in the Green channelby the normalization

double MeanB: image mean to be achieved by the Blue channel normalization

double Variance: image variance to be achived by the normalization

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

double& Gain: computed gain used to perform the adjustment (Gain * value + Offset)

double& OffsetR: computed offset used to perform the adjustment in the red channel (Gain * value + Offset)

double& OffsetG: computed offset used to perform the adjustment in the Green channel(Gain * value + Offset)

double& OffsetB: computed offset used to perform the adjustment in the BLue channel (Gain * value + Offset)

Method Histogram::Normalize: ajust the second source image to the same dynamics as the first (by average and standard deviation), by linear mapping

static void Normalize(const Image& Src, const Image& SrcB, Image& Dst, double& Gain, double& Offset);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& SrcB: the second source image for this operation - remains unchanged after the operation

Image& Dst: the destination image, which is computed by this operation

double& Gain: computed gain used to perform the adjustment (Gain * value + Offset)

double& Offset: computed offset used to perform the adjustment (Gain * value + Offset)


Member of the class Histogram - Compare Images

Method Histogram::ShowDifferences: compare two images and enhance the positive [negative] differences in red [blue]

static void ShowDifferences(const Image& Src, const Image& SrcB, Image& Dst, int Threshold = 16, bool Normalize = false);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& SrcB: the second source image for this operation - remains unchanged after the operation

Image& Dst: the destination image, which is computed by this operation

int Threshold: detection threshold, in the usual gray range

bool Normalize: if true, the second image is normalized (by average and standard deviation) before the comparisons


Member of the class Histogram - Graphics

Method Histogram::Plot: draw a plot of the profile data in a rectangular area in the current window, as specified by the property Status::DrawTo

void Plot(int X, int Y, int Width, int Height, bool Frame = false, int MinValue = 0, int MaxValue = 0, int Bin[] = 0, int NumBins = 1);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels of the plot area, horizontally

int Height: number of pixels of the plot area, vertically

bool Frame: true if a rectangular frame is drawn around the plot

int MinValue: lower bound of the range of values to be plotted on the vertical axis; when Min=Max, the range is automatically adjusted

int MaxValue: upper bound of the range of values to be plotted on the vertical axis; when Min=Max, the range is automatically adjusted

int* Bin: optional list of bin indexes for which vertical extension lines are drawn

int NumBins: number of bins for which vertical extension lines are drawn


Member of the class Histogram - Graphics

Method Histogram::ToAsciiString: convert the content of the histogram bins to tabular text

char* ToAsciiString(int SampleRow = All);

returned char*: ASCII null-terminated string

BlobSelection SampleRow: index of the desired bin, in range 0..Length-1, or All


Struct LabeledRun

A run is a contiguous row of pixels of the same class; used for internal purposes by the Blobs class

Constructor LabeledRun: creates a void LabeledRun object

Constructor LabeledRun: creates a void LabeledRun object

Coordinates

Property X0: starting abscissa

Property X1: ending abscissa

Property Y: ordinate

Label

Property Label: component label


Member of the class LabeledRun

Constructor LabeledRun::LabeledRun: creates a void LabeledRun object

LabeledRun(short X0, short X1, short Y, int Label= 0);

short X0: abscissa of the leftmost pixel

short X1: abscissa of the after-rightmost pixel

short Y: common ordinate of the pixels

int Label: arbitrary numerical identifier


Member of the class LabeledRun - Coordinates

Property short LabeledRun::X0: starting abscissa


Member of the class LabeledRun - Coordinates

Property short LabeledRun::X1: ending abscissa


Member of the class LabeledRun - Coordinates

Property short LabeledRun::Y: ordinate


Member of the class LabeledRun - Label

Property int LabeledRun::Label: component label


Enumeration

Enum Features: predefined features that can be used by a feature table

Case BlobClass: class identifier

Case BlobArea: number of pixels in a blob, Int

Case BlobWorldArea: true area, in calibrated units, Float

Case BlobPerimeter: number of pixels on the outline of a blob, Int

Case BlobFullPerimeter: number of pixels on the outline of a blob, including holes, Int

Case BlobPerimetricRatio: normalized ratio of the area and the squared perimeter to assess circularity; 1 for a perfect circle

Case BlobFilledArea: area of the blobs after hole filling, in pixels

Case BlobFillingRatio: ratio of the area over the filled ares; maximum 100% when there are no holes

Case BlobConvexArea: area of the convex hull of the blob, in pixels, Int

Case BlobConvexAreaRatio: ratio of the area of the convex hull over the area of the outline

Case BlobConvexPerimeter: length of the convex hull, in pixels

Case BlobConvexPerimeterRatio: ratio of the length of the convex hull over the lenght of the outline

Case BlobCenterX: abscissa of the gravity center of a blob, Float

Case BlobCenterY: ordinate of the gravity center of a blob, Float

Case BlobEllipseWidth: major axis of the ellipse of inertia of a blob, Float

Case BlobEllipseHeight: minor axis of the ellipse of inertia of a blob, Float

Case BlobEllipseAngle: angle of the major axis of the ellipse of inertia of a blob, Float

Case BlobEccentricity: rating of the elongation of the ellipse; between 0 for a circle and 1 for a flat ellipse, Float

Case BlobMass: sum of the gray levels of all pixels in the blob, Int

Case BlobAverage: average gray-level of the pixels covered by a blob in the target image, Float

Case BlobDeviation: the standard deviation of the grayscale values of the blob pixels in the given image

Case BlobMedian: the median grayscale value of the blob pixels in the given image

Case BlobMinimum: the lowest grayscale value of the blob pixels in the given image

Case BlobMaximum: the highest grayscale value of the blob pixels in the given image

Case BlobCentroidX: abscissa of the centroid of a blob, Float

Case BlobCentroidY: ordinate of the centroid of a blob, Float

Case BlobEllipsoidWidth: major axis of the ellipsoid of inertia of a blob, Float

Case BlobEllipsoidHeight: minor axis of the ellipsoid of inertia of a blob, Float

Case BlobEllipsoidAngle: angle of the major axis of the ellipsoid of inertia of a blob, Float

Case BlobEllipsoidEccentricity: rating of the elongation of the ellipsoid; between 0 for a circle and 1 for a flat ellipse, Float

Case BlobBoxX: abscissa of the top left corner of the bounding box of a blob, Int

Case BlobBoxY: ordinate of the top left corner of the bounding box of a blob, Int

Case BlobBoxWidth: width of the bounding box of a blob, Int

Case BlobBoxHeight: height of the bounding box of a blob, Int

Case BlobWorldBoxX: abscissa of the top left corner of the bounding box of a blob in world coordinates, Float

Case BlobWorldBoxY: ordinate of the top left corner of the bounding box of a blob in world coordinates, Float

Case BlobWorldBoxWidth: width of the bounding box of a blob in world coordinates, Float

Case BlobWorldBoxHeight: height of the bounding box of a blob in world coordinates, Float

Case BlobAspectRatio: ratio of the height over the width of the bounding box, Float

Case BlobFeretCenterX: abscissa of the center of the Feret bounding box of a blob, Float

Case BlobFeretCenterY: ordinate of the center of the Feret bounding box of a blob, Float

Case BlobFeretWidth: longest side of the Feret bounding box of a blob, Float

Case BlobFeretHeight: shortest side of the Feret bounding box of a blob, also called its shortest diameter, Float

Case BlobFeretAngle: angle of the Feret bounding box of a blob, Float

Case BlobFeretRatio: ratio of the Height over the Width of the Feret bounding box

Case BlobDiametralCenterX: abscissa of the center of the Feret bounding box of a blob, Float

Case BlobDiametralCenterY: ordinate of the center of the Feret bounding box of a blob, Float

Case BlobDiametralWidth: longest side of the Feret bounding box of a blob, also called its diameter, Float

Case BlobDiametralHeight: shortest side of the Feret bounding box of a blob, Float

Case BlobDiametralAngle: angle of the Feret bounding box of a blob, Float

Case BlobDiametralRatio: ratio of the Height over the Width of the diametral bounding box

Case BlobMatchingScore: matching Score after matching by the ShapeMatcher

Case BlobMatchingX: abscissa of the center after matching by the ShapeMatcher

Case BlobMatchingY: ordinate of the center after matching by the ShapeMatcher

Case BlobMatchingScale: relative scale of the shape after matching by the ShapeMatcher

Case BlobMatchingAngle: rotation angle of the shape after matching by the ShapeMatcher

Case FeatureCount: reserved for internal use

Case BlobCenter: gravity center of a blob, group

Case BlobEllipse: ellipse of inertia of a blob, group

Case BlobCentroid: centroid of a blob, i.e. the weighted average center when the pixel gray-levels are taken for weights, group

Case BlobEllipsoid: (weighted) ellipsoid of inertia of a blob, group

Case BlobBox: bounding box of a blob, group

Case BlobWorldBox: bounding box of a blob, in calibrated units, Float

Case BlobFeretBox: Feret rectangle of a blob, i.e. the tightest oblique bounding box, group

Case BlobDiametralBox: diametral rectangle of a blob, i.e. the largest oblique bounding box, group

Case BlobOutline: path around the blob

Case BlobVector: vectorized path around the blob

Case BlobOutlineBeg: Reserved for blob shape recognition

Case BlobOutlineEnd: Reserved for blob shape recognition

Case BlobVectorBeg: Reserved for blob shape recognition

Case BlobVectorEnd: Reserved for blob shape recognition

Case ReservedFeatureCount: Reserved use; feature limit


Enumeration

Enum SelectionMode: designate the way to update the current selection of objects

Case Add: insert the given items into the selected list, keeping the other ones

Case Remove: remove the given items from the selected list, keeping the other ones

Case Select: insert the given items into the selected list, discarding all the other ones

Case Deselect: remove the given items from the selected list, inserting the other ones


Enumeration

Enum RangeMode: tells how the selection bounds are interpreted

Case Inside: the feature value lies between the specified bounds (or the bounding box is wholly inside the window)

Case Outside: the feature value does not lie between the specified bounds (or the bounding box is wholly outside the window)

Case Onside: the bounding box intersects the window (SelectWindowBlob only)

Case Over: the bounding box wholly covers the window (SelectWindowBlob only)


Class FeatureTable

A class that organizes the storage of an arbitrary number of objects described by an arbitrary number of numerical features; this device allows selection, sorting and classification of the objects, based on those features

Constructor FeatureTable: creates a void feature table object

Sizing

Method ClearFeatures: forget all stored features

Method ClearSamples: forget all stored objects

Method AppendIntFeature: add room for a new numerical feature of a discrete type

Method AppendFloatFeature: add room for a new numerical feature of a continuous type

Method AppendSample: add room for a new object

Property NumFeatures: the number of different features that are stored

Property NumSamples: the number of different objects that are stored

Sample Data

Method Type: get the type of a numerical features, i.e. a discrete or a continuous value

Method IntFeature: get the value of a discrete object feature

Method FloatFeature: get the value of a continuous feature value

Selection by Features

Method IsSelected: test the selection state of an object

Method SampleSelect: change the selection state of the given object

Method SamplesSelect: selects or deselects samples based on a range of accepted/rejected discrete feature values

Property NumSelectedSamples: the number of different objects that are stored and in the selected state

Sorting by Features

Method SamplesFirst: finds the first sample in the sorted order (smallest or largest value)

Method SamplesSort: sorts the objects according to a specified feature value


Member of the class FeatureTable

Constructor FeatureTable::FeatureTable: creates a void feature table object

FeatureTable();


Member of the class FeatureTable - Sizing

Method FeatureTable::ClearFeatures: forget all stored features

void ClearFeatures();


Member of the class FeatureTable - Sizing

Method FeatureTable::ClearSamples: forget all stored objects

void ClearSamples();


Member of the class FeatureTable - Sizing

Method FeatureTable::AppendIntFeature: add room for a new numerical feature of a discrete type

int AppendIntFeature();

returned int: storage index of the appended feature


Member of the class FeatureTable - Sizing

Method FeatureTable::AppendFloatFeature: add room for a new numerical feature of a continuous type

int AppendFloatFeature();

returned int: storage index of the appended feature


Member of the class FeatureTable - Sizing

Method FeatureTable::AppendSample: add room for a new object

int AppendSample();

returned int: storage index of the appended sample


Member of the class FeatureTable - Sizing

Property int FeatureTable::NumFeatures: the number of different features that are stored


Member of the class FeatureTable - Sizing

Property int FeatureTable::NumSamples: the number of different objects that are stored


Member of the class FeatureTable - Sample Data

Method FeatureTable::Type: get the type of a numerical features, i.e. a discrete or a continuous value

enum PixelTypes& Type(int FeatureIndex);

returned PixelTypes&: one of Int and Float

int FeatureIndex: integer number in range [0..NumFeatures-1]


Member of the class FeatureTable - Sample Data

Method FeatureTable::IntFeature: get the value of a discrete object feature

int& IntFeature(int SampleIndex, int FeatureIndex);

returned int&: the feature value

BlobSelection SampleIndex: index of the desired object

int FeatureIndex: integer number in range [0..NumFeatures-1]


Member of the class FeatureTable - Sample Data

Method FeatureTable::FloatFeature: get the value of a continuous feature value

float& FloatFeature(int SampleIndex, int FeatureIndex);

returned float&: the feature value

BlobSelection SampleIndex: index of the desired object

int FeatureIndex: integer number in range [0..NumFeatures-1]


Member of the class FeatureTable - Selection by Features

Method FeatureTable::IsSelected: test the selection state of an object

bool IsSelected(int SampleIndex);

returned bool: true if this object is currently selected

BlobSelection SampleIndex: index of the desired object


Member of the class FeatureTable - Selection by Features

Method FeatureTable::SampleSelect: change the selection state of the given object

void SampleSelect(int SampleIndex, enum SelectionMode Mode = Select);

BlobSelection SampleIndex: index of the desired object

SelectionMode Mode: the rule to update the selected objects list, an enumerated value in SelectionMode


Member of the class FeatureTable - Selection by Features

Method FeatureTable::SamplesSelect: selects or deselects samples based on a range of accepted/rejected discrete feature values

void SamplesSelect(int FeatureIndex, int Minimum = MinInt, int Maximum = MaxInt, enum SelectionMode Selection = Select, enum RangeMode Range = Inside);

int FeatureIndex: integer number in range [0..NumFeatures-1]

int Minimum: lower bound for comparison; can be MinFloat

int Maximum: upper bound for comparison; can be MaxFloat

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode

RangeMode Range: the rule to compare the feature value to the selection range

Method FeatureTable::SamplesSelect: selects or deselects samples based on a range of accepted/rejected continuous feature values

void SamplesSelect(int FeatureIndex, float Minimum = MinFloat, float Maximum = MaxFloat, enum SelectionMode Selection = Select, enum RangeMode Range = Inside);

int FeatureIndex: integer number in range [0..NumFeatures-1]

float Minimum: lower bound for comparison; can be MinFloat

float Maximum: upper bound for comparison; can be MaxFloat

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode

RangeMode Range: the rule to compare the feature value to the selection range


Member of the class FeatureTable - Selection by Features

Property int FeatureTable::NumSelectedSamples: the number of different objects that are stored and in the selected state


Member of the class FeatureTable - Sorting by Features

Method FeatureTable::SamplesFirst: finds the first sample in the sorted order (smallest or largest value)

int SamplesFirst(int FeatureIndex, bool Increasing = true);

returned int: index of the sample

int FeatureIndex: integer number in range [0..NumFeatures-1]

bool Increasing: true for increasing order, i.e. smallest first, false for largest first


Member of the class FeatureTable - Sorting by Features

Method FeatureTable::SamplesSort: sorts the objects according to a specified feature value

void SamplesSort(int FeatureIndex, bool Increasing = true);

int FeatureIndex: integer number in range [0..NumFeatures-1]

bool Increasing: true to sort by increasing values, false otherwise


Class Region

Compact representation of an arbitrarily shaped region allowing to distinguish between active and don't care pixels

Constructor Region: creates a void Region object

Property NumRuns: number of runs (horizontal stretches of pixels) in the region

Sizing

Method Clear: reset the region definition to a void one

Method Append: append a run (horizontal line segment) to the end of the region definition

Method Box: computes the axis-aligned bounding box of a region, with an optional margin

Generate

Method Binarize: generate a region from an image, by automatic thresholding

Add a Region

Method BoxAppend: add the inside of a box

Method ImageAppend: add the frame of an image, or its current Window

Method RegionAppend: add the inside of another region

Method BlobAppend: add the shape of a blob to the given region; the previous region content is preserved

Method PathAppend: add the shape of the inside of a path to the given region; the previous region content is preserved

Method QuadAppend: add the shape of the inside of a quad to the given region; the previous region content is preserved

Method EllipseAppend: add the inside of an ellipse

Region Arithmetic

Method Invert: invert the region with respect to a rectangle

Method Unite: form the union of the source regions

Method Intersect: form the intersection of the source regions

Method Subtract: form the difference of the source regions

Method Containment: analyses the containment relation between the region and another

Region Reshaping

Method Erode: apply a morphological erosion to the region

Method Dilate: apply a morphological dilation to the region

Method Gradient: apply a morphological gradient to the region

Method Convexify: modifies the region to replace it by its convex hull

Method ConvexHull: the tightest convex polygon that contains the whole Region

Filling

Method Fill: fills the destination image with a value or source image, only inside a region; the source and destination images are not overshooted

Method SeedFill: fill a connected image region in-place with the given value, starting from the given seed pixel

Outlining

Method Follow: traces the outline of the region as a path

Features

Method Area: number of pixels spanned by the region

Method Center: gravity center of the region, assuming uniform density

Method Rectangle: fits the tightest rotatable rectangle around the region

Method Circle: fits the tightest circle around the region

Method Mean: average gray-level value in the image, over the region

Method Variance: population variance of the gray-level values in the image, over the region

Storage

Method Read: load the Region data from a file (ASCII or UNICODE path and name)

Method Write: save the Profile data to a file (ASCII or UNICODE path and name)

Graphics

Method Run: coordinates of the run with the desired index, in range [0..NumRuns-1]

Method Draw: draws the region as an overlay on the current drawing window; make sure to set FillColor

Method DrawOutlines: draw all outlines of the region (external and holes) as an overlay on the current drawing window; make sure to set FillColor


Member of the class Region

Constructor Region::Region: creates a void Region object

Region();


Member of the class Region

Property int Region::NumRuns: number of runs (horizontal stretches of pixels) in the region


Member of the class Region - Sizing

Method Region::Clear: reset the region definition to a void one

void Clear();


Member of the class Region - Sizing

Method Region::Append: append a run (horizontal line segment) to the end of the region definition

void Append(const LabeledRun& Run);

LabeledRun& Run: the new run, contained in a LabeledRun structure


Member of the class Region - Sizing

Method Region::Box: computes the axis-aligned bounding box of a region, with an optional margin

Limits Box(int Margin = 0);

returned Limits: bounding box coordinates

int Margin: extra margin aroung the regions, in pixels


Member of the class Region - Generate

Method Region::Binarize: generate a region from an image, by automatic thresholding

int Binarize(int Threshold, const Image& Src, bool Above = true, int Label = 0);

returned int: value of the threshold used for binarization

int Threshold: binarization threshold value

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool Above: true if the active region pixels are taken above the threshold level

int Label: label to be assigned to all runs; reserved for later use

Method Region::Binarize: generate a region from an image, by explicit thresholding

void Binarize(GrayPixel Background, GrayPixel Foreground, const Image& Src, bool Above = true, int Label = 0);

GrayPixel Background: grayscale value of the background pixels

GrayPixel Foreground: grayscale value of the background pixels

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool Above: true if the active region pixels are taken above the threshold level

int Label: label to be assigned to all runs; reserved for later use

Method Region::Binarize: generate a region from an image, by thresholding; the threshold is taken halfway of a background and a foreground gray

int Binarize(const Image& Src, bool Above = true);

returned int: value of the threshold used for binarization

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool Above: true if the active region pixels are taken above the threshold level


Member of the class Region - Add a Region

Method Region::BoxAppend: add the inside of a box

void BoxAppend(const Limits& Src, int Label = 0);

Limits& Src: X, Y, Width, Height coordinates

int Label: label to be assigned to all runs; reserved for later use


Member of the class Region - Add a Region

Method Region::ImageAppend: add the frame of an image, or its current Window

void ImageAppend(const Image& Src, int Label = 0);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

int Label: label to be assigned to all runs; reserved for later use


Member of the class Region - Add a Region

Method Region::RegionAppend: add the inside of another region

void RegionAppend(const Region& Src);

Region& Src: region to be appended


Member of the class Region - Add a Region

Method Region::BlobAppend: add the shape of a blob to the given region; the previous region content is preserved

void BlobAppend(const Blobs& Src, int BlobIndex = All);

Blobs& Src: blobs object providing the input blob shapes

BlobSelection BlobIndex: zero-based index of the desired blob


Member of the class Region - Add a Region

Method Region::PathAppend: add the shape of the inside of a path to the given region; the previous region content is preserved

void PathAppend(const Path& Src, int Label = 0);

Path& Src: source path to be filled

int Label: label to be assigned to all runs; reserved for later use


Member of the class Region - Add a Region

Method Region::QuadAppend: add the shape of the inside of a quad to the given region; the previous region content is preserved

void QuadAppend(const Quad& Src, int Label = 0);

Quad& Src: source curvilinear quadrilateral (Quad) object

int Label: label to be assigned to all runs; reserved for later use


Member of the class Region - Add a Region

Method Region::EllipseAppend: add the inside of an ellipse

void EllipseAppend(XY Center, XY Axis, double Angle, int Label = 0);

XY Center: ellipse center coordinates

XY Axis: ellipse semi-axis lengths

double Angle: rotation an gle of the main axis, in the current angle unit

int Label: label to be assigned to all runs; reserved for later use


Member of the class Region - Region Arithmetic

Method Region::Invert: invert the region with respect to a rectangle

void Invert(int X, int Y, int Width, int Height, Region& Src, const Image& DummyOver);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: Width of the enclosing region

int Height: Height of the enclosing region

Region& Src: source region

Image& DummyOver: RESERVED


Member of the class Region - Region Arithmetic

Method Region::Unite: form the union of the source regions

void Unite(Region& SrcA, Region& SrcB, const Image& DummyOver);

Region& SrcA: first region

Region& SrcB: second region

Image& DummyOver: image on which the region is applied; currently unused


Member of the class Region - Region Arithmetic

Method Region::Intersect: form the intersection of the source regions

void Intersect(Region& SrcA, Region& SrcB, const Image& DummyOver);

Region& SrcA: first region

Region& SrcB: second region

Image& DummyOver: image on which the region is applied; currently unused


Member of the class Region - Region Arithmetic

Method Region::Subtract: form the difference of the source regions

void Subtract(Region& SrcA, Region& SrcB, const Image& DummyOver);

Region& SrcA: first region

Region& SrcB: second region

Image& DummyOver: image on which the region is applied; currently unused


Member of the class Region - Region Arithmetic

Method Region::Containment: analyses the containment relation between the region and another

RangeMode Containment(const Region& Src);

returned RangeMode: one of Inside, Outside, Over and Onside, as define by enum RangeMode

Region& Src: the region to compare to


Member of the class Region - Region Reshaping

Method Region::Erode: apply a morphological erosion to the region

void Erode(Region& Src, Morpho& Structel, const Image& DummyOver);

Region& Src: the Region to be eroded

Morpho& Structel: the structuring element, a Morpho object

Image& DummyOver: image on which the region is applied; currently unused


Member of the class Region - Region Reshaping

Method Region::Dilate: apply a morphological dilation to the region

void Dilate(Region& Src, Morpho& Structel, const Image& DummyOver);

Region& Src: the Region to be dilated

Morpho& Structel: the structuring element, a Morpho object

Image& DummyOver: image on which the region is applied; currently unused


Member of the class Region - Region Reshaping

Method Region::Gradient: apply a morphological gradient to the region

void Gradient(Region& Src, Morpho& Structel, GradientTypes Type = StandardGradient, const Image& DummyOver);

Region& Src: the Region for which the morphological gradient is desired

Morpho& Structel: the structuring element, a Morpho object

GradientTypes Type: one of StandardGradient, ExternalGradient or InternalGradient

Image& DummyOver: image on which the region is applied; currently unused


Member of the class Region - Region Reshaping

Method Region::Convexify: modifies the region to replace it by its convex hull

void Convexify(const Image& DummyOver);

Image& DummyOver: image on which the region is applied; currently unused


Member of the class Region - Region Reshaping

Method Region::ConvexHull: the tightest convex polygon that contains the whole Region

void ConvexHull(Path& Hull);

Path& Hull: hull path built around the Region


Member of the class Region - Filling

Method Region::Fill: fills the destination image with a value or source image, only inside a region; the source and destination images are not overshooted

void Fill(int Value, Image& Dst);

int Value: grayscale or color value to fill with

Image& Dst: image to copy the pixels to

Method Region::Fill: fills the destination image with a value or source image, only inside a region; the source and destination images are not overshooted

void Fill(RgbPixel Value, Image& Dst);

RgbPixel Value: grayscale or color value to fill with

Image& Dst: image to copy the pixels to

Method Region::Fill: fills the destination image with a value or source image, only inside a region; the source and destination images are not overshooted

void Fill(const Image& Src, Image& Dst, int SrcX = 0, int SrcY = 0);

Image& Src: source image to copy the pixels from

Image& Dst: image to copy the pixels to

int SrcX: abscissa of the top-left corner of Src when overlaid on Dst; by default the corners coincide

int SrcY: ordinate of the top-left corner of Src when overlaid on Dst; by default the corners coincide


Member of the class Region - Filling

Method Region::SeedFill: fill a connected image region in-place with the given value, starting from the given seed pixel

static void SeedFill(Site& Seed, GrayPixel Value, Image& Src, bool Connexity8 = true, int Tolerance = 0);

Site& Seed: the starting site, [0..Height-1]

GrayPixel Value: grayscale value to fill with

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Connexity8: true if 8 connexity is used, false for 4 connexity

int Tolerance: +/- tolerance on the pixel values to be filled


Member of the class Region - Outlining

Method Region::Follow: traces the outline of the region as a path

void Follow(Path& Outline);

Path& Outline: the destination path


Member of the class Region - Features

Method Region::Area: number of pixels spanned by the region

int Area();

returned int: region area


Member of the class Region - Features

Method Region::Center: gravity center of the region, assuming uniform density

XY Center(int& Area);

returned XY: center coordinates

int& Area: region area obtained as a by-product


Member of the class Region - Features

Method Region::Rectangle: fits the tightest rotatable rectangle around the region

void Rectangle(double& Xc, double& Yc, double& Width, double& Height, double& Angle);

double& Xc: abscissa of the center

double& Yc: ordinate of the center

double& Width: largest rectangle dimension

double& Height: smallest rectangle dimension

double& Angle: rotation angle, in the current angle unit


Member of the class Region - Features

Method Region::Circle: fits the tightest circle around the region

void Circle(double& Xc, double& Yc, double& Radius);

double& Xc: abscissa of the center

double& Yc: ordinate of the center

double& Radius: radius


Member of the class Region - Features

Method Region::Mean: average gray-level value in the image, over the region

double Mean(const Image& Src, int& Area);

returned double: average value

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

int& Area: area of the region, computed as a byproduct


Member of the class Region - Features

Method Region::Variance: population variance of the gray-level values in the image, over the region

double Variance(const Image& Src, double& Mean, int& Area);

returned double: variance value

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

double& Mean: gray-level average, computed as a byproduct

int& Area: area of the region, computed as a byproduct


Member of the class Region - Storage

Method Region::Read: load the Region data from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .rgn extension recommended

Method Region::Read: load the Region data from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .rgn extension recommended


Member of the class Region - Storage

Method Region::Write: save the Profile data to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .rgn extension recommended

Method Region::Write: save the Profile data to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .rgn extension recommended


Member of the class Region - Graphics

Method Region::Run: coordinates of the run with the desired index, in range [0..NumRuns-1]

void Run(int Index, LabeledRun& Run);

int Index: zero-based index value to access a list of items

LabeledRun& Run: LabeledRun structure with the run coordinates (X0, X1, Y)

Method Region::Run: coordinates of the run with the desired index, in range [0..NumRuns-1]

void Run(int Index, int& X0, int& X1, int& Y);

int Index: zero-based index value to access a list of items

int& X0: abscissa of the leftmost pixel

int& X1: abscissa of the after-rightmost pixel

int& Y: common ordinate of the pixels


Member of the class Region - Graphics

Method Region::Draw: draws the region as an overlay on the current drawing window; make sure to set FillColor

void Draw();


Member of the class Region - Graphics

Method Region::DrawOutlines: draw all outlines of the region (external and holes) as an overlay on the current drawing window; make sure to set FillColor

void DrawOutlines(bool Connexity8= true);

bool Connexity8: true for eight-connected outlines (touching by an edge or a corner), false for four-connected (touching by an edge)


Class Blobs

The main object for blob analysis. It holds a description of all blobs segmented from the image and computes features from them

Constructor Blobs: creates a void Blobs object

Segment Image

Property NumBlobs: the number of blobs detected

Property DefaultClass: Class number to be assigned to the segmented blobs

Method Segment: decompose an image in blobs by uniform thresholding; the threshold value is chosen automatically by an optimization rule

Segment in Mask

Method Segment: decompose an image in blobs by uniform thresholding; the threshold value is chosen automatically by an optimization rule

Binary Blob Features

Method Area: surface of a blob, i.e. the number of pixels it comprises

Method WorldArea: surface of a blob, in calibrated units

Method FilledArea: compute the blob area (after holes have been filled), in pixels

Method ConvexArea: area of the tightest convex polygon that contains the blob

Method Box: the X-Y bounding box of a blob

Method WorldBox: the X-Y bounding box of a blob, in world coordinates

Method TiltedBox: the rectangular bounding box of a blob with a given tilt angle

Method Border: test if the given blob touches the image border; if this is the case, the blob might be incomplete

Method Center: the gravity center of a blob, i.e. the average coordinates

Method Ellipse: the ellipse of inertia of a blob, as defined by the laws of kinematics

Method FeretBox: Feret rectangle of a blob, i.e. the tightest oblique bounding box

Method DiametralBox: diametral rectangle of a blob, i.e. the widest oblique bounding box

Method Perimeter: length of a blob outline

Method FullPerimeter: length of a blob outline, including holes; for the external outline only, use Perimeter

Method WindowBlob: checks the containment relation of the blob to the specified rectangular window

Method RegionBlob: checks the containment relation of the blob to the specified region

Weighted Blob Features

Method Average: the average value of the blob pixels in the given grayscale image

Method Deviation: compute the standard deviation of the grayscale values of the blob pixels in the given image

Method Median: compute the median grayscale value of the blob pixels in the given image

Method Minimum: compute the lowest grayscale value of the blob pixels in the given image

Method Maximum: compute the highest grayscale value of the blob pixels in the given image

Method Mass: sum of the gray levels of all pixels in the blob

Method Centroid: the coordinates of the blob centroid, i.e. the weighted average of the blob pixel positions, where the weights are the corresponding gray-level values in the given grayscale image

Method Ellipsoid: the (weighted) ellipsoid of inertia of a blob, as defined by the laws of kinematics

Calibrated Features

Method WorldArea: surface of a blob, in calibrated units

Method Centroid: the coordinates of the blob centroid, i.e. the weighted average of the blob pixel positions, where the weights are the corresponding gray-level values in the given grayscale image

Method Ellipsoid: the (weighted) ellipsoid of inertia of a blob, as defined by the laws of kinematics

Non-scalar Features

Method PixelHistogram: computes the histogram of all the pixels spanned by one or more blobs

Method Outline: path formed by the pixels on the external outline of the given blob(s)

Method ConvexHull: the tightest convex polygon that contains the blob

Evaluate Features

Method Evaluate: evaluates the given feature for the desired blobs

Select by Feature

Method ByFeatureSelect: select blobs by checking inclusion in a range of values of a discrete feature

Method BorderSelect: selects the blobs that touch the image edges and are probably incomplete

Method BoxInWindowSelect: select blobs by checking the relation of their bounding box to a rectangular window

Method BlobInWindowSelect: select blobs by checking the relation to a rectangular window

Method BlobInRegionSelect: select blobs by checking the relation to an arbitrary region

Property NumSelectedBlobs: number of blobs currently selected

Sort by Feature

Method ByFeatureFirst: finds the first blob with the smallest or largest value of a desired feature

Method ByFeatureSort: sort the selected blobs on the value of the given feature

Transform Blobs

Method Convexify: modifies the designated blobs to replace them by their convex hulls

Features Data

Method AppendUserFeature: add room for a new feature that is defined and computed by the user

Method Type: type of the given feature

Method UnicodeName: name of the given feature

Method IsComputed: tells if a given feature has been computed for a given blob

Method IntFeature: get the value of a discrete feature of a selected object

Method FloatFeature: get the value of a continuous feature of a selected object

Method StraightIndex: raw blob index for use in the individual blob operations; reserved use

Method ClearBlobs: discards all blobs

Method AppendBlob: add a new blob to the list, defined by a Region object

Features Distribution

Method FeatureAverage: compute the average value of a feature over a set of blobs

Method FeatureDeviation: compute the standard deviation value of a feature over a set of blobs

Method FeatureMinimum: compute the minimum value of a feature over a set of blobs

Method FeatureMaximum: compute the maximum value of a feature over a set of blobs

Method FeatureQuantile: compute the quantile value of a feature over a set of blobs

Method FeatureCovariance: Compute the covariance and correlation values between two features over a set of blobs

Method FeatureMode: the mode of the distribution of the feature values

Method FeatureMinimumIndex: index of the blob that minimizes the specified feature

Method FeatureMaximumIndex: index of the blob that minimizes the specified feature

Graphics

Method DrawBlob: draws the desired blob(s) to the current drawing context

Method DrawBox: draws the bounding box around the desired blob(s)

Method DrawTiltedBox: draws the rectangular bounding box with a given tilt angle around the desired blob(s)

Method DrawCenter: draws the gravity center of the desired blob(s) as a cross

Method DrawEllipse: draws the ellipse of inertia of the desired blob(s)

Method DrawHull: draw the convex hull of the desired blob(s)

Method DrawCentroid: draws the gravity center of the desired blob(s) as a cross

Method DrawEllipsoid: draws the ellipse of inertia of the desired blob(s)

Method DrawFeretBox: drawn the Feret rectangle around the desired blob(s)

Method DrawDiametralBox: drawn the diametral rectangle around the desired blob(s)

Method DrawOutline: draw the outline of the given blob(s)

Method HitBlob: index of the blob at given cursor coordinates

Method Point: returns a top-left point of the blob; this is intended to help place labels

Method NumBlobRuns: number of runs for this blob

Method BlobRun: get the run coordinates for a run in a blob

Property HitBlobIndex: index of the blob that was last hit, or -1

Method ToImage: draws a blob into an image, filling with a constant gray value

Method WhichFeature: tells the feature identifier at a given position in the feature array; reserved for internal use

Method CopyToClipboard: copy the feature values in tabular form to the clipboard


Member of the class Blobs

Constructor Blobs::Blobs: creates a void Blobs object

Blobs();


Member of the class Blobs - Segment Image

Property int Blobs::NumBlobs: the number of blobs detected


Member of the class Blobs - Segment Image

Property int Blobs::DefaultClass: Class number to be assigned to the segmented blobs


Member of the class Blobs - Segment in Mask

Method Blobs::Segment: decompose an image in blobs by uniform thresholding; the threshold value is chosen automatically by an optimization rule

int Segment(int Threshold, const Region& Mask, const Image& Src, bool Above = true, bool Connexity8 = true, int MinimumArea = 5, int MaximumArea = MaxInt);

returned int: computed binarization threshold value

int Threshold: binarization threshold value

Region& Mask: a region from which pixels are taken, acts as a mask

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

bool Above: when true, consider the pixels with a value lighter than the threshold; otherwise, consider those with a darker value

bool Connexity8: Number of connected neighbors (8 or 4)

int MinimumArea: area threshold under which blobs are completely undetected; by default 5 pixels

int MaximumArea: area threshold above which blobs are completely undetected; by default IntMax, meaning that all large blobs are kept

Method Blobs::Segment: decompose an image in blobs by uniform thresholding

void Segment(int Size, int Noise, const Region& Mask, const Image& Src, bool Above = true, bool Connexity8 = true, int MinimumArea = 5, int MaximumArea = MaxInt);

int Size: Extent of the area that defines the scale of adaptiveness

int Noise: Threshold level corresponding to the noise amplitude; can be positive, null or negative

Region& Mask: a region from which pixels are taken, acts as a mask

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

bool Above: when true, consider the pixels with a value lighter than the threshold; otherwise, consider those with a darker value

bool Connexity8: Number of connected neighbors (8 or 4)

int MinimumArea: area threshold under which blobs are completely undetected; by default 5 pixels

int MaximumArea: area threshold above which blobs are completely undetected; by default IntMax, meaning that all large blobs are kept

Method Blobs::Segment: decompose an image in blobs by adaptive thresholding; the threshold value is anoffset to the local mean

void Segment(GrayPixel Background, GrayPixel Foreground, const Region& Mask, const Image& Src, bool Above = true, bool Connexity8 = true, int MinimumArea = 5, int MaximumArea = MaxInt);

GrayPixel Background: reference gray-value for the background

GrayPixel Foreground: reference gray-value for the foreground

Region& Mask: a region from which pixels are taken, acts as a mask

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

bool Above: when true, consider the pixels with a value lighter than the threshold; otherwise, consider those with a darker value

bool Connexity8: Number of connected neighbors (8 or 4)

int MinimumArea: area threshold under which blobs are completely undetected; by default 5 pixels

int MaximumArea: area threshold above which blobs are completely undetected; by default IntMax, meaning that all large blobs are kept

Method Blobs::Segment: decompose an image in blobs by uniform thresholding; the threshold value is chosen midway of two specified shades of gray

void Segment(RgbPixel BackColor, RgbPixel ForeColor, const Region& Mask, const Image& Src, bool Above = true, bool Connexity8 = true, int MinimumArea = 5, int MaximumArea = MaxInt);

RgbPixel BackColor: reference color value for the background

RgbPixel ForeColor: reference color value for the foreground

Region& Mask: a region from which pixels are taken, acts as a mask

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

bool Above: when true, consider the pixels with a value lighter than the threshold; otherwise, consider those with a darker value

bool Connexity8: Number of connected neighbors (8 or 4)

int MinimumArea: area threshold under which blobs are completely undetected; by default 5 pixels

int MaximumArea: area threshold above which blobs are completely undetected; by default IntMax, meaning that all large blobs are kept

Method Blobs::Segment: decompose an image in blobs by uniform thresholding; the threshold value is chosen midway of two specified colors

int Segment(const Region& Mask, const Image& Src, bool Above = true, bool Connexity8 = true, int MinimumArea = 5, int MaximumArea = MaxInt);

returned int: computed binarization threshold value

Region& Mask: a region from which pixels are taken, acts as a mask

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

bool Above: when true, consider the pixels with a value lighter than the threshold; otherwise, consider those with a darker value

bool Connexity8: Number of connected neighbors (8 or 4)

int MinimumArea: area threshold under which blobs are completely undetected; by default 5 pixels

int MaximumArea: area threshold above which blobs are completely undetected; by default IntMax, meaning that all large blobs are kept

Method Blobs::Segment: decompose a region of an image in blobs by uniform thresholding; the threshold value is chosen automatically by an optimization rule

void Segment(const Region& Mask, const Image& Src, int BelowThreshold, int AboveThreshold, bool Connexity8 = true, int MinimumArea = 5, int MaximumArea = MaxInt, bool SameClass = true);

Region& Mask: a region from which pixels are taken, acts as a mask

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Rgb only

int BelowThreshold: low threshold for double thresholding; if Below < Above, accept between, otherwise beyond

int AboveThreshold: high threshold for double thresholding; if Below < Above, accept between otherwise beyond

bool Connexity8: Number of connected neighbors (8 or 4)

int MinimumArea: area threshold under which blobs are completely undetected; by default 5 pixels

int MaximumArea: area threshold above which blobs are completely undetected; by default IntMax, meaning that all large blobs are kept

bool SameClass: when true, the results of thresholding are gathered in the same class; otherwise above and below are kept separate


Member of the class Blobs - Binary Blob Features

Method Blobs::Area: surface of a blob, i.e. the number of pixels it comprises

int Area(int BlobIndex);

returned int: the blob area, i.e. the number of pixels

int BlobIndex: zero-based index of the desired blob


Member of the class Blobs - Calibrated Features

Method Blobs::WorldArea: surface of a blob, in calibrated units

double WorldArea(const Geometry& Calibrator, int BlobIndex);

returned double: the blob area, in squared units

Geometry& Calibrator: geometry object used for calibration (if absent, simple calibration is used)

int BlobIndex: zero-based index of the desired blob


Member of the class Blobs - Binary Blob Features

Method Blobs::FilledArea: compute the blob area (after holes have been filled), in pixels

int FilledArea(int BlobIndex);

returned int: computed filled area

int BlobIndex: zero-based index of a blob in range [0..NumBlobs-1]


Member of the class Blobs - Binary Blob Features

Method Blobs::ConvexArea: area of the tightest convex polygon that contains the blob

int ConvexArea(int BlobIndex);

returned int: area value, in (squares) pixels

int BlobIndex: zero-based index of the desired blob


Member of the class Blobs - Binary Blob Features

Method Blobs::Box: the X-Y bounding box of a blob

void Box(int BlobIndex, int& X, int& Y, int& Width, int& Height);

int BlobIndex: zero-based index of the desired blob

int& X: top-left corner abscissa, in pixels

int& Y: top-left corner ordinate, in pixels

int& Width: box width, in pixels

int& Height: box height, in pixels


Member of the class Blobs - Binary Blob Features

Method Blobs::WorldBox: the X-Y bounding box of a blob, in world coordinates

void WorldBox(int BlobIndex, double& X, double& Y, double& Width, double& Height);

int BlobIndex: zero-based index of the desired blob

double& X: top-left corner abscissa, in world units

double& Y: top-left corner ordinate, in world units

double& Width: box width, in world units

double& Height: box height, in world units


Member of the class Blobs - Binary Blob Features

Method Blobs::TiltedBox: the rectangular bounding box of a blob with a given tilt angle

void TiltedBox(int BlobIndex, double Angle, double& X, double& Y, double& Width, double& Height);

int BlobIndex: zero-based index of the desired blob

double Angle: rotation angle

double& X: top-left corner abscissa

double& Y: top-left corner ordinate

double& Width: box width, in pixels

double& Height: box height, in pixels


Member of the class Blobs - Binary Blob Features

Method Blobs::Border: test if the given blob touches the image border; if this is the case, the blob might be incomplete

bool Border(int BlobIndex, const Image& Src);

returned bool: true when the blob touches the border

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst


Member of the class Blobs - Binary Blob Features

Method Blobs::Center: the gravity center of a blob, i.e. the average coordinates

void Center(int BlobIndex, int& Area, double& X, double& Y);

int BlobIndex: zero-based index of the desired blob

int& Area: blob area, i.e. pixel count

double& X: average abscissa, in pixels

double& Y: average ordinate, in pixels


Member of the class Blobs - Binary Blob Features

Method Blobs::Ellipse: the ellipse of inertia of a blob, as defined by the laws of kinematics

void Ellipse(int BlobIndex, int& Area, double& X, double& Y, double& Width, double& Height, double& Angle, double& Eccentricity);

int BlobIndex: zero-based index of the desired blob

int& Area: blob area, i.e. pixel count

double& X: abscissa of the center of inertia

double& Y: ordinate of the center of inertia

double& Width: major ellipse axis

double& Height: minor ellipse axis

double& Angle: direction of the major axis

double& Eccentricity: elongation of the ellipse; between 0 for a circle and 1 for a flat ellipse


Member of the class Blobs - Binary Blob Features

Method Blobs::FeretBox: Feret rectangle of a blob, i.e. the tightest oblique bounding box

void FeretBox(int BlobIndex, double& X, double& Y, double& Width, double& Height, double& Angle);

int BlobIndex: zero-based index of the desired blob

double& X: abscissa of the center of the rectangle

double& Y: ordinate of the center of the rectangle

double& Width: longest side of the rectangle

double& Height: shortest side of the rectangle, also known as the shortest diameter

double& Angle: direction angle of the longest side


Member of the class Blobs - Binary Blob Features

Method Blobs::DiametralBox: diametral rectangle of a blob, i.e. the widest oblique bounding box

void DiametralBox(int BlobIndex, double& X, double& Y, double& Width, double& Height, double& Angle);

int BlobIndex: zero-based index of the desired blob

double& X: abscissa of the center of the rectangle

double& Y: ordinate of the center of the rectangle

double& Width: longest side of the rectangle, also known as the diameter

double& Height: shortest side of the rectangle

double& Angle: direction angle of the longest side


Member of the class Blobs - Binary Blob Features

Method Blobs::Perimeter: length of a blob outline

int Perimeter(int BlobIndex, bool Connexity8 = true);

returned int: pixel count of the blob outline; to include the hole outlines, use FullPerimeter

int BlobIndex: zero-based index of the desired blob

bool Connexity8: the contour will be 8-connected


Member of the class Blobs - Binary Blob Features

Method Blobs::FullPerimeter: length of a blob outline, including holes; for the external outline only, use Perimeter

int FullPerimeter(int BlobIndex, bool Connexity8 = true);

returned int: pixel count of the blob outline, including holes

int BlobIndex: zero-based index of the desired blob

bool Connexity8: if true the contour will be 8-connected; otherwise 4-connected


Member of the class Blobs - Binary Blob Features

Method Blobs::WindowBlob: checks the containment relation of the blob to the specified rectangular window

enum RangeMode WindowBlob(int BlobIndex, int X, int Y, int Width, int Height);

returned RangeMode: configuration type as enumerated in RangeMode, one of Inside, Outside, Onside or Over

int BlobIndex: zero-based index of the desired blob

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels, horizontally

int Height: number of pixels, vertically


Member of the class Blobs - Binary Blob Features

Method Blobs::RegionBlob: checks the containment relation of the blob to the specified region

enum RangeMode RegionBlob(int BlobIndex, const Region& Src);

returned RangeMode: tests the geometric relation of a blob and a region

int BlobIndex: zero-based index of the desired blob

Region& Src: the test region


Member of the class Blobs - Weighted Blob Features

Method Blobs::Average: the average value of the blob pixels in the given grayscale image

double Average(int BlobIndex, const Image& Src, int& Area);

returned double: the average value

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

int& Area: number of pixels in the blob


Member of the class Blobs - Weighted Blob Features

Method Blobs::Deviation: compute the standard deviation of the grayscale values of the blob pixels in the given image

double Deviation(int BlobIndex, const Image& Src, double& Average, int& Area);

returned double: the standard deviation value

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

double& Average: the average value

int& Area: the number of pixels


Member of the class Blobs - Weighted Blob Features

Method Blobs::Median: compute the median grayscale value of the blob pixels in the given image

int Median(int BlobIndex, const Image& Src);

returned int: the median value

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Blobs - Weighted Blob Features

Method Blobs::Minimum: compute the lowest grayscale value of the blob pixels in the given image

int Minimum(int BlobIndex, const Image& Src);

returned int: the minimum value

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Blobs - Weighted Blob Features

Method Blobs::Maximum: compute the highest grayscale value of the blob pixels in the given image

int Maximum(int BlobIndex, const Image& Src);

returned int: the maximum value

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Blobs - Weighted Blob Features

Method Blobs::Mass: sum of the gray levels of all pixels in the blob

int Mass(int BlobIndex, const Image& Src);

returned int: blob mass

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst


Member of the class Blobs - Calibrated Features

Method Blobs::Centroid: the coordinates of the blob centroid, i.e. the weighted average of the blob pixel positions, where the weights are the corresponding gray-level values in the given grayscale image

bool Centroid(const Geometry& Calibrator, int BlobIndex, const Image& Src, int& Mass, double& X, double& Y);

returned bool: true if the centroid is defined (nonzero Mass)

Geometry& Calibrator: geometry object used for calibration (if absent, simple calibration is used)

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

int& Mass: blob mass

double& X: the abscissa of the centroid

double& Y: the ordinate of the centroid


Member of the class Blobs - Calibrated Features

Method Blobs::Ellipsoid: the (weighted) ellipsoid of inertia of a blob, as defined by the laws of kinematics

bool Ellipsoid(const Geometry& Calibrator, int BlobIndex, const Image& Src, int& Mass, double& X, double& Y, double& Width, double& Height, double& Angle, double& Eccentricity);

returned bool: true if the ellipsoid is defined (nonzero Mass)

Geometry& Calibrator: geometry object used for calibration (if absent, simple calibration is used)

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

int& Mass: blob mass, i.e. sul of the pixel values

double& X: abscissa of the centroid

double& Y: ordinate of the centroid

double& Width: major ellipsoid axis

double& Height: minor ellipsoid axis

double& Angle: direction of the major axis

double& Eccentricity: elongation of the ellipsoid; between 0 for a circle and 1 for a flat ellipse


Member of the class Blobs - Non-scalar Features

Method Blobs::PixelHistogram: computes the histogram of all the pixels spanned by one or more blobs

void PixelHistogram(int BlobIndex, const Image& Src, Histogram& Dst, bool Clear = true);

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Histogram& Dst: the destination histogram

bool Clear: when true, as by default, the histogram bins are cleared before computation; when false, the previous bin contents are kept and accumulation continues


Member of the class Blobs - Non-scalar Features

Method Blobs::Outline: path formed by the pixels on the external outline of the given blob(s)

void Outline(int BlobIndex, const Image& Src, Path& Dst);

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Path& Dst: the destination path that will receive the sequence of outline coordinates


Member of the class Blobs - Non-scalar Features

Method Blobs::ConvexHull: the tightest convex polygon that contains the blob

void ConvexHull(int BlobIndex, const Image& Src, Path& Dst);

int BlobIndex: zero-based index of the desired blob

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Path& Dst: computed convex polygon around the given shape


Member of the class Blobs - Evaluate Features

Method Blobs::Evaluate: evaluates the given feature for the desired blobs

void Evaluate(enum Features Feature, const Image& Src, int BlobIndex = AllSelected);

Features Feature: feature identifier, as enumerated in Features

Image& Src: the source image for this operation; the pixel values are taken as the weights - remains unchanged, unless Src = Dst

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

Method Blobs::Evaluate: evaluates the given weighted feature for the desired blobs

void Evaluate(const Geometry& Calibrator, enum Features Feature, const Image& Src, int BlobIndex = AllSelected);

Geometry& Calibrator: geometry object used for calibration (if absent, simple calibration is used)

Features Feature: feature identifier, as enumerated in Features

Image& Src: the source image for this operation; the pixel values are taken as the weights - remains unchanged, unless Src = Dst

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected


Member of the class Blobs - Select by Feature

Method Blobs::ByFeatureSelect: select blobs by checking inclusion in a range of values of a discrete feature

void ByFeatureSelect(enum Features Feature, const Image& Src, int Minimum = MinInt, int Maximum = MaxInt, enum SelectionMode Selection = Select, enum RangeMode Range = Inside);

Features Feature: feature identifier, as enumerated in Features

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

int Minimum: lower bound of the accepted range

int Maximum: upper bound of the accepted range

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode; one of Add, Select, Remove, Deselect

RangeMode Range: the rule to compare the feature value to the selection rang, an enumerated value in RangeMode; one of Inside, Outside

Method Blobs::ByFeatureSelect: select blobs by checking inclusion in a range of values of a continuous feature

void ByFeatureSelect(enum Features Feature, const Image& Src, float Minimum = MinFloat, float Maximum = MaxFloat, enum SelectionMode Selection = Select, enum RangeMode Range = Inside);

Features Feature: feature identifier, as enumerated in Features

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

float Minimum: lower bound of the accepted range

float Maximum: upper bound of the accepted range

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode; one of Add, Select, Remove, Deselect

RangeMode Range: the rule to compare the feature value to the selection rang, an enumerated value in RangeMode; one of Inside, Outside


Member of the class Blobs - Select by Feature

Method Blobs::BorderSelect: selects the blobs that touch the image edges and are probably incomplete

void BorderSelect(const Image& Src, enum SelectionMode Selection = Remove);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode; one of Add, Select, Remove, Deselect

Method Blobs::BorderSelect: selects the blobs that touch the image edges and are probably incomplete

void BorderSelect(Region& Src, bool Connexity8, enum SelectionMode Selection = Remove);

Region& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool Connexity8: true for an eight-connected region outline (touching by an edge or a corner), false for four-connected (touching by an edge)

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode; one of Add, Select, Remove, Deselect


Member of the class Blobs - Select by Feature

Method Blobs::BoxInWindowSelect: select blobs by checking the relation of their bounding box to a rectangular window

void BoxInWindowSelect(int X, int Y, int Width, int Height, enum SelectionMode Selection = Remove, enum RangeMode Range = Inside);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels, horizontally

int Height: number of pixels, vertically

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode; one of Add, Select, Remove, Deselect

RangeMode Range: the rule to compare the feature value to the selection rang, an enumerated value in RangeMode; one of Inside, Outside


Member of the class Blobs - Select by Feature

Method Blobs::BlobInWindowSelect: select blobs by checking the relation to a rectangular window

void BlobInWindowSelect(int X, int Y, int Width, int Height, enum SelectionMode Selection = Remove, enum RangeMode Range = Inside);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels, horizontally

int Height: number of pixels, vertically

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode; one of Add, Select, Remove, Deselect

RangeMode Range: the rule to compare the feature value to the selection rang, an enumerated value in RangeMode; one of Inside, Outside


Member of the class Blobs - Select by Feature

Method Blobs::BlobInRegionSelect: select blobs by checking the relation to an arbitrary region

void BlobInRegionSelect(const Region& Src, enum SelectionMode Selection = Remove, enum RangeMode Range = Inside);

Region& Src: the target region

SelectionMode Selection: one of Add, Select, Remove, Deselect, as defined by enum SelectionMode

RangeMode Range: one of Inside, Outside, Onside, Over, as defined by enum RangeMode


Member of the class Blobs - Select by Feature

Property int Blobs::NumSelectedBlobs: number of blobs currently selected


Member of the class Blobs - Sort by Feature

Method Blobs::ByFeatureFirst: finds the first blob with the smallest or largest value of a desired feature

int ByFeatureFirst(enum Features Feature, const Image& Src, bool Increasing = true);

returned int: index of the first blob

Features Feature: feature identifier, as enumerated in Features

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Increasing: true for increasing order, i.e. smallest first, false for largest first


Member of the class Blobs - Sort by Feature

Method Blobs::ByFeatureSort: sort the selected blobs on the value of the given feature

void ByFeatureSort(enum Features Feature, const Image& Src, bool Increasing = true);

Features Feature: feature identifier, as enumerated in Features

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool Increasing: true when the sorting is by increasing feature values


Member of the class Blobs - Transform Blobs

Method Blobs::Convexify: modifies the designated blobs to replace them by their convex hulls

void Convexify(int BlobIndex = AllSelected);

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected


Member of the class Blobs - Features Data

Method Blobs::AppendUserFeature: add room for a new feature that is defined and computed by the user

enum Features AppendUserFeature(enum PixelTypes Type);

returned Features: access index of the allocated feature; keep it for later reference

PixelTypes Type: one of Int or Float to specify the type


Member of the class Blobs - Features Data

Method Blobs::Type: type of the given feature

enum PixelTypes Type(enum Features Feature);

returned PixelTypes: one of Int (discrete) or Float (continuous)

Features Feature: feature identifier, as defined by the enumeration Features


Member of the class Blobs - Features Data

Method Blobs::UnicodeName: name of the given feature

const wchar_t* UnicodeName(enum Features Feature);

returned wchar_t*: UNICODE character string

Features Feature: feature identifier, as defined by the enumeration Features


Member of the class Blobs - Features Data

Method Blobs::IsComputed: tells if a given feature has been computed for a given blob

bool IsComputed(int Index, enum Features Feature);

returned bool: true when the feature has been computed

int Index: zero-based index value to access a list of items

Features Feature: feature identifier, as enumerated in Features


Member of the class Blobs - Features Data

Method Blobs::IntFeature: get the value of a discrete feature of a selected object

int& IntFeature(int Index, enum Features Feature);

returned int&: the discrete feature value

int Index: zero-based index value to access a list of items

Features Feature: feature identifier, as enumerated in Features


Member of the class Blobs - Features Data

Method Blobs::FloatFeature: get the value of a continuous feature of a selected object

float& FloatFeature(int Index, enum Features Feature);

returned float&: the continuous feature value

int Index: zero-based index value to access a list of items

Features Feature: feature identifier, as enumerated in Features


Member of the class Blobs - Features Data

Method Blobs::StraightIndex: raw blob index for use in the individual blob operations; reserved use

int StraightIndex(int BlobIndex);

returned int: raw blob index in range [0..NumBlobs-1]

int BlobIndex: zero-based index of the desired blob


Member of the class Blobs - Features Data

Method Blobs::ClearBlobs: discards all blobs

void ClearBlobs();


Member of the class Blobs - Features Data

Method Blobs::AppendBlob: add a new blob to the list, defined by a Region object

void AppendBlob(const Region& Src);

Region& Src: the Region that describes the new blob


Member of the class Blobs - Features Distribution

Method Blobs::FeatureAverage: compute the average value of a feature over a set of blobs

double FeatureAverage(enum Features Feature, const Image& Src, int Index = AllSelected, bool Average= true);

returned double: The average or sum value

Features Feature: enumerated feature name

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

BlobSelection Index: zero-based index value to access a list of items

bool Average: when true, the function computes the average; otherwise returns the sum of the features


Member of the class Blobs - Features Distribution

Method Blobs::FeatureDeviation: compute the standard deviation value of a feature over a set of blobs

double FeatureDeviation(enum Features Feature, const Image& Src, int Index = AllSelected);

returned double: The (biased) standard deviation

Features Feature: enumerated feature name

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

BlobSelection Index: zero-based index value to access a list of items


Member of the class Blobs - Features Distribution

Method Blobs::FeatureMinimum: compute the minimum value of a feature over a set of blobs

double FeatureMinimum(enum Features Feature, const Image& Src, int Index = AllSelected);

returned double: The minimum value

Features Feature: enumerated feature name

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

BlobSelection Index: zero-based index value to access a list of items


Member of the class Blobs - Features Distribution

Method Blobs::FeatureMaximum: compute the maximum value of a feature over a set of blobs

double FeatureMaximum(enum Features Feature, const Image& Src, int Index = AllSelected);

returned double: The maximum value

Features Feature: enumerated feature name

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

BlobSelection Index: zero-based index value to access a list of items


Member of the class Blobs - Features Distribution

Method Blobs::FeatureQuantile: compute the quantile value of a feature over a set of blobs

double FeatureQuantile(enum Features Feature, const Image& Src, double Percent = 0.5, int Index = AllSelected);

returned double: the feature value

Features Feature: enumerated feature name

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

double Percent: requested percentile fraction, in the range [0..1]; 0.25, 0.5 and 0.75 for the quartiles

BlobSelection Index: zero-based index value to access a list of items


Member of the class Blobs - Features Distribution

Method Blobs::FeatureCovariance: Compute the covariance and correlation values between two features over a set of blobs

double FeatureCovariance(enum Features Feature, enum Features FeatureB, double& Correlation, const Image& Src, int Index = AllSelected);

returned double: the covariancevalue

Features Feature: enumerated feature name

Features FeatureB: other enumerated feature name

double& Correlation: the correlation, i.e. covariance over the product of standard deviations

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

BlobSelection Index: zero-based index value to access a list of items


Member of the class Blobs - Features Distribution

Method Blobs::FeatureMode: the mode of the distribution of the feature values

double FeatureMode(enum Features Feature, const Image& Src, int Index = AllSelected);

returned double: the value of the mode

Features Feature: enumerated feature name

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

BlobSelection Index: zero-based index value to access a list of items


Member of the class Blobs - Features Distribution

Method Blobs::FeatureMinimumIndex: index of the blob that minimizes the specified feature

int FeatureMinimumIndex(enum Features Feature, const Image& Src, int Index = AllSelected);

returned int: blob index

Features Feature: feature identifier, as enumerated in Features

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

BlobSelection Index: zero-based index value to access a list of items


Member of the class Blobs - Features Distribution

Method Blobs::FeatureMaximumIndex: index of the blob that minimizes the specified feature

int FeatureMaximumIndex(enum Features Feature, const Image& Src, int Index = AllSelected);

returned int: blob index

Features Feature: feature identifier, as enumerated in Features

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

BlobSelection Index: zero-based index value to access a list of items


Member of the class Blobs - Graphics

Method Blobs::DrawBlob: draws the desired blob(s) to the current drawing context

void DrawBlob(int BlobIndex = All, bool Label = false, bool Class = false);

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

bool Label: when true the index of each blob is shown over it

bool Class: when true, the blob class is displayed instead of the blob index


Member of the class Blobs - Graphics

Method Blobs::DrawBox: draws the bounding box around the desired blob(s)

void DrawBox(int BlobIndex = All, bool Centers = false);

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

bool Centers: when true, the box centers are drawn too as a cross


Member of the class Blobs - Graphics

Method Blobs::DrawTiltedBox: draws the rectangular bounding box with a given tilt angle around the desired blob(s)

void DrawTiltedBox(double Angle, int BlobIndex = All, bool Centers = false);

double Angle: rotation angle

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

bool Centers: when true, the box centers are drawn too as a cross


Member of the class Blobs - Graphics

Method Blobs::DrawCenter: draws the gravity center of the desired blob(s) as a cross

void DrawCenter(int BlobIndex = All);

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected


Member of the class Blobs - Graphics

Method Blobs::DrawEllipse: draws the ellipse of inertia of the desired blob(s)

void DrawEllipse(int BlobIndex = All, bool Centers = false);

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

bool Centers: when true, the ellipse centers are drawn too as a cross


Member of the class Blobs - Graphics

Method Blobs::DrawHull: draw the convex hull of the desired blob(s)

void DrawHull(int BlobIndex = All);

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected


Member of the class Blobs - Graphics

Method Blobs::DrawCentroid: draws the gravity center of the desired blob(s) as a cross

void DrawCentroid(const Image& Src, int BlobIndex = All);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected


Member of the class Blobs - Graphics

Method Blobs::DrawEllipsoid: draws the ellipse of inertia of the desired blob(s)

void DrawEllipsoid(const Image& Src, int BlobIndex = All, bool Centers = false);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

bool Centers: when true, the ellipse centers are drawn too as a cross


Member of the class Blobs - Graphics

Method Blobs::DrawFeretBox: drawn the Feret rectangle around the desired blob(s)

void DrawFeretBox(int BlobIndex = All, bool Centers = false);

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

bool Centers: when true, a cross is drawn at the center points


Member of the class Blobs - Graphics

Method Blobs::DrawDiametralBox: drawn the diametral rectangle around the desired blob(s)

void DrawDiametralBox(int BlobIndex = All, bool Centers = false);

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

bool Centers: when true, a cross is drawn at the center points


Member of the class Blobs - Graphics

Method Blobs::DrawOutline: draw the outline of the given blob(s)

void DrawOutline(int BlobIndex = All, bool Label = false);

BlobSelection BlobIndex: zero-based index of the desired blob

bool Label: when true the index of each blob is shown over it


Member of the class Blobs - Graphics

Method Blobs::HitBlob: index of the blob at given cursor coordinates

int HitBlob(int X, int Y, int BlobIndex = All);

returned int: blob index or NotInitialized

int X: abscissa of any point inside the blob, in pixels

int Y: ordinate of any point inside the blob, in pixels, top-down

BlobSelection BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected


Member of the class Blobs - Graphics

Method Blobs::Point: returns a top-left point of the blob; this is intended to help place labels

Site Point(int BlobIndex);

returned Site: top-left point coordinates

int BlobIndex: zero-based index of the desired blob, in range [0..NumBlobs-1]


Member of the class Blobs - Graphics

Method Blobs::NumBlobRuns: number of runs for this blob

int NumBlobRuns(int BlobIndex);

returned int: number of runs

int BlobIndex: index of the desired blob, in range [0..NumBlobs-1]


Member of the class Blobs - Graphics

Method Blobs::BlobRun: get the run coordinates for a run in a blob

void BlobRun(int BlobIndex, int RunIndex, int& X0, int& X1, int& Y);

int BlobIndex: index of the desired blob, in range [0..NumBlobs-1]

int RunIndex: index of the desired run, in range [0..NumBlobRuns-1]

int& X0: abscissa of the leftmost pixel

int& X1: ordinate of the after-rightmost pixel

int& Y: common ordinate of the pixels


Member of the class Blobs - Graphics

Property int Blobs::HitBlobIndex: index of the blob that was last hit, or -1


Member of the class Blobs - Graphics

Method Blobs::ToImage: draws a blob into an image, filling with a constant gray value

void ToImage(int BlobIndex, GrayPixel Const, Image& Dst);

int BlobIndex: zero-based index of a blob in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected

GrayPixel Const: the value used for filling

Image& Dst: the destination image, which is computed by this operation


Member of the class Blobs - Graphics

Method Blobs::WhichFeature: tells the feature identifier at a given position in the feature array; reserved for internal use

enum Features WhichFeature(int Index);

returned Features: feature identifier, as enumerated in Features

int Index: zero-based feature index in the features array


Member of the class Blobs - Graphics

Method Blobs::CopyToClipboard: copy the feature values in tabular form to the clipboard

void CopyToClipboard(int FeatureColumn = All, int SampleRow = All);

BlobSelection FeatureColumn: specifies the column index (specific feature) or All, as by default

BlobSelection SampleRow: specifies the row index (specific blob) or All, as by default


Struct SubArcPath

Reserved for internal use by the EdgeMap class

Vertex Delimiting

Property BegVertex: starting pixel index; reserved for internal use

Property EndVertex: ending pixel index; reserved for internal use

Property Closed: true if the path is closed; reserved for internal use

Arc Delimiting

Property BegArc: starting curve index; reserved for internal use

Property EndArc: ending curve index; reserved for internal use

Assessment

Property Strength: path strength, a measure of contrast; reserved for internal use


Member of the class SubArcPath - Vertex Delimiting

Property int SubArcPath::BegVertex: starting pixel index; reserved for internal use


Member of the class SubArcPath - Vertex Delimiting

Property int SubArcPath::EndVertex: ending pixel index; reserved for internal use


Member of the class SubArcPath - Vertex Delimiting

Property bool SubArcPath::Closed: true if the path is closed; reserved for internal use


Member of the class SubArcPath - Arc Delimiting

Property int SubArcPath::BegArc: starting curve index; reserved for internal use


Member of the class SubArcPath - Arc Delimiting

Property int SubArcPath::EndArc: ending curve index; reserved for internal use


Member of the class SubArcPath - Assessment

Property int SubArcPath::Strength: path strength, a measure of contrast; reserved for internal use


Enumeration

Enum Directions: indicates a discrete direction in which profiles are taken

Case HorizontalDirection: horizontal (W-E)

Case VerticalDirection: vertical (N-S)

Case BothDirections: horizontal or vertical


Class EdgeMap

Vectorized representation of an edge map

Constructor EdgeMap: creates a void EdgeMap object

Raster Map

Method GradientVector: gradient filter, computing a vector image with x and y components in range [-255..+255] (standard), [-767..+767] (Prewitt) or [-1023..+1023] (Sobel)

Method GradientMaxima: applies non-maxima suppression to a gradient vector image, producing a scalar image

Method StrongEdges: binarizes an edge map image with hysteresis thresholding; weak pixels that are connected to strong pixels are kept

Method StepEdges: find significant steps along profiles, considered as edges

Vector Map

Method Follow: turn a pixel representation to a linked representation of the edge map

Method IsoCurves: detect edges as isocurves of the high-pass filtered image

Method Vectorize: turn a pixel representation to a vector representation of the edge map

Property NumPaths: number of distinct paths in the vectorized map

Graphics

Method Draw: draws the edge map

Method ClosestTo: reports the vertex closest to the cursor

Method Clear: remove all content of the edge map

Vertex/Arc/Path Data

Method NumVertexes: number of distinct edge pixels in the specified path

Method Vertex: returns a given pixel in a path of the edge map

Method GetPath: returns a single edge path, given its index

Method NumArcs: number of distinct arcs in the specified path

Method Arc: returns a given piece of line/curve in a path of the vectorized edge map


Member of the class EdgeMap

Constructor EdgeMap::EdgeMap: creates a void EdgeMap object

EdgeMap();


Member of the class EdgeMap - Raster Map

Method EdgeMap::GradientVector: gradient filter, computing a vector image with x and y components in range [-255..+255] (standard), [-767..+767] (Prewitt) or [-1023..+1023] (Sobel)

static void GradientVector(const Image& Src, Image& Dst, enum GradientTypes Type = PrewittGradient);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

GradientTypes Type: selects the type of gradient vector as defined by enum GradientTypes; Prewitt by default


Member of the class EdgeMap - Raster Map

Method EdgeMap::GradientMaxima: applies non-maxima suppression to a gradient vector image, producing a scalar image

static int GradientMaxima(int Noise, const Image& Src, Image& Dst, bool Binarize = false, enum GradientTypes Type = PrewittGradient, int UpperLimit = MaxInt);

returned int: the computed value of the Noise parameter, if Auto was passed

int Noise: gradient magnitude under which pixels are always suppressed; can be Auto

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Binarize: when false, as by default, gray intensities are preserved; otherwise, a binary image is produced by global thresholding

GradientTypes Type: selectes the type of gradient vector as defined by enum GradientTypes; Prewitt by default

int UpperLimit: gradient magnitude above which edge pixels are suppressed (high threshold)


Member of the class EdgeMap - Raster Map

Method EdgeMap::StrongEdges: binarizes an edge map image with hysteresis thresholding; weak pixels that are connected to strong pixels are kept

static int StrongEdges(int Noise, int EdgeStrength, const Image& Src, Image& Dst, enum GradientTypes Type = PrewittGradient, int UpperLimit = MaxInt);

returned int: the computed value of the Noise parameter, if Auto was passed

int Noise: gradient magnitude under which pixels are always suppressed (low threshold); can be Auto

int EdgeStrength: gradient magnitude under which whole edges are suppressed (high threshold)

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

GradientTypes Type: selects the type of gradient vector as defined by enum GradientTypes; Prewitt by default

int UpperLimit: gradient magnitude above which edge pixels are suppressed (high threshold)


Member of the class EdgeMap - Raster Map

Method EdgeMap::StepEdges: find significant steps along profiles, considered as edges

static void StepEdges(int MinimumStep, int Noise, const Image& Src, Image& Dst, Polarities Polarity = Both, Directions Directions = BothDirections, bool ShowPolarity = false);

int MinimumStep: minimum height of the step

int Noise: allowed tolerance to deal with profiles being non-monotonic because of noise

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both

Directions Directions: directions used to detect the steps

bool ShowPolarity: if false, as by default, all edges are show white; otherwise raising in white, falling in black


Member of the class EdgeMap - Vector Map

Method EdgeMap::Follow: turn a pixel representation to a linked representation of the edge map

int Follow(int Noise, int MinAverageGray, int MinLength, const Image& Src, GradientTypes Type = PrewittGradient);

returned int: the computed value of the Noise parameter, if Auto was passed

int Noise: per-pixel edge strength threshold; can be Auto

int MinAverageGray: per-path edge strength threshold

int MinLength: path length threshold

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

GradientTypes Type: formula used to compute the gradient of the image


Member of the class EdgeMap - Vector Map

Method EdgeMap::IsoCurves: detect edges as isocurves of the high-pass filtered image

void IsoCurves(const Image& Src, int FilterSize, int Noise, int IntegrationLength, int MinLength, int EdgeStrength);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

int FilterSize: filter size; must be odd

int Noise: noise immunity threshold used in highpass filtering; a signed value

int IntegrationLength: length on which the strength is averaged

int MinLength: minimum length of the detected curves

int EdgeStrength: minimum average edge strength, in range 0..255


Member of the class EdgeMap - Vector Map

Method EdgeMap::Vectorize: turn a pixel representation to a vector representation of the edge map

int Vectorize(int Noise, int MinAverageGray, int MinLength, const Image& Src, bool Curved = false, double Deviation = 1, GradientTypes Type = PrewittGradient);

returned int: the computed value of the Noise parameter, if Auto was passed

int Noise: per-pixel edge strength threshold; can be Auto

int MinAverageGray: per-path edge strength threshold

int MinLength: path length threshold

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; Gray only

bool Curved: when true, circular arcs are used in addition to line segments

double Deviation: maximum allowed distance between a path and the vectorized polyline, in pixels

GradientTypes Type: formula used to compute the gradient of the image


Member of the class EdgeMap - Vector Map

Property int EdgeMap::NumPaths: number of distinct paths in the vectorized map


Member of the class EdgeMap - Graphics

Method EdgeMap::Draw: draws the edge map

void Draw(int EndpointSize = 0);

int EndpointSize: size of the dot used to draw the vertices; zero for no vertices


Member of the class EdgeMap - Graphics

Method EdgeMap::ClosestTo: reports the vertex closest to the cursor

int ClosestTo(Site& S);

returned int: closest vertex index

Site& S: cursor coordinates


Member of the class EdgeMap - Graphics

Method EdgeMap::Clear: remove all content of the edge map

void Clear();


Member of the class EdgeMap - Vertex/Arc/Path Data

Method EdgeMap::NumVertexes: number of distinct edge pixels in the specified path

int NumVertexes(int PathIndex);

returned int: path length, as a number of pixels

int PathIndex: path index, in range [0..NumPaths-1]


Member of the class EdgeMap - Vertex/Arc/Path Data

Method EdgeMap::Vertex: returns a given pixel in a path of the edge map

Site& Vertex(int PathIndex, int VertexIndex);

returned Site&: vertex coordinates

int PathIndex: path index, in range [0..NumPaths-1]

int VertexIndex: vertex index in range [0..NumVertexes(PathIndex)-1]


Member of the class EdgeMap - Vertex/Arc/Path Data

Method EdgeMap::GetPath: returns a single edge path, given its index

void GetPath(int PathIndex, Path& Dst);

int PathIndex: index og the path, in range [0..NumPaths-1]

Path& Dst: destination object to receive the edge path


Member of the class EdgeMap - Vertex/Arc/Path Data

Method EdgeMap::NumArcs: number of distinct arcs in the specified path

int NumArcs(int PathIndex);

returned int: path length, as a number of line segments/circular arcs

int PathIndex: path index, in range [0..NumPaths-1]


Member of the class EdgeMap - Vertex/Arc/Path Data

Method EdgeMap::Arc: returns a given piece of line/curve in a path of the vectorized edge map

ArcSite& Arc(int PathIndex, int ArcIndex);

returned ArcSite&: line/curve descriptor

int PathIndex: path index, in range [0..NumPaths-1]

int ArcIndex: vertex index in range [0..NumArcs(PathIndex)-1]


Class TableStore

General-purpose storage for tabular data and classification by feature vectors

Constructor TableStore: creates a void TableStore object

Destructor ~TableStore: destroys the object

Features Management

Method AppendFeature: add a feature column

Property NumFeatures: number of columns stored in the table

Method Type: image pixel data type

Method Name: get the name of a feature

Method ClearFeatures: removes all feature columns

Samples Management

Method AppendSample: add a sample row

Property NumSamples: number of rows stored in the table

Property NumSelectedSamples: number of rows currently selected among the NumSamples stored ones

Method ClearSamples: removes all sample rows

Value Access

Method BoolValue: accessor to a Boolean feature

Method GrayValue: accessor to a feature of type Gray

Method Gray16Value: accessor to a feature of type Gray16

Method RgbValue: accessor to an RGB color feature

Method IntValue: accessor to an integer feature

Method FloatValue: accessor to a single precision feature

Method DbleValue: accessor to a double precision feature

Storage

Method Read: loads the trained feature description and sample values to initialize the classifier from a file (ASCII path and name)

Method Write: saves the trained feature description and sample values for later reuse to a file (ASCII path and name)

Text Input/Output

Method ToAsciiString: convert the content of the table to tabular text

Method ToUnicodeString: convert the content of the table to tabular text

Method FromAsciiString: input table rows from a tabular text representation

Method FromUnicodeString: input table rows from a tabular text representation

Clipboard

Method CopyToClipboard: copy the table to the clipboard, as tabular text

Method PasteFromClipboard: paste table rows from the clipboard, using a tabular text representation; the column titles must match


Member of the class TableStore

Constructor TableStore::TableStore: creates a void TableStore object

TableStore();


Member of the class TableStore

Destructor TableStore::~TableStore: destroys the object

~TableStore();


Member of the class TableStore - Features Management

Method TableStore::AppendFeature: add a feature column

void AppendFeature(PixelTypes Type, wchar_t* Name = EmptyString);

PixelTypes Type: image pixel data type

wchar_t* Name: name of the feature


Member of the class TableStore - Features Management

Property int TableStore::NumFeatures: number of columns stored in the table


Member of the class TableStore - Features Management

Method TableStore::Type: image pixel data type

PixelTypes Type(int FeatureColumn);

returned PixelTypes: the feature type, as enumerated in PixelTypes

int FeatureColumn: column index, in range 0..NumFeatures-1


Member of the class TableStore - Features Management

Method TableStore::Name: get the name of a feature

wchar_t* Name(int FeatureColumn);

returned wchar_t*: the feature name, a null-terminated string

int FeatureColumn: column index of the feature


Member of the class TableStore - Features Management

Method TableStore::ClearFeatures: removes all feature columns

void ClearFeatures();


Member of the class TableStore - Samples Management

Method TableStore::AppendSample: add a sample row

void AppendSample(int Count = 1);

int Count: number of rows to be added; 1 by default


Member of the class TableStore - Samples Management

Property int TableStore::NumSamples: number of rows stored in the table


Member of the class TableStore - Samples Management

Property int TableStore::NumSelectedSamples: number of rows currently selected among the NumSamples stored ones


Member of the class TableStore - Samples Management

Method TableStore::ClearSamples: removes all sample rows

void ClearSamples();


Member of the class TableStore - Value Access

Method TableStore::BoolValue: accessor to a Boolean feature

bool& BoolValue(int FeatureColumn, int SampleRow = -1);

returned bool&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class TableStore - Value Access

Method TableStore::GrayValue: accessor to a feature of type Gray

GrayPixel& GrayValue(int FeatureColumn, int SampleRow = -1);

returned GrayPixel&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class TableStore - Value Access

Method TableStore::Gray16Value: accessor to a feature of type Gray16

Gray16Pixel& Gray16Value(int FeatureColumn, int SampleRow = -1);

returned Gray16Pixel&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class TableStore - Value Access

Method TableStore::RgbValue: accessor to an RGB color feature

RgbPixel& RgbValue(int FeatureColumn, int SampleRow = -1);

returned RgbPixel&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class TableStore - Value Access

Method TableStore::IntValue: accessor to an integer feature

int& IntValue(int FeatureColumn, int SampleRow = -1);

returned int&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class TableStore - Value Access

Method TableStore::FloatValue: accessor to a single precision feature

float& FloatValue(int FeatureColumn, int SampleRow = -1);

returned float&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class TableStore - Value Access

Method TableStore::DbleValue: accessor to a double precision feature

double& DbleValue(int FeatureColumn, int SampleRow = -1);

returned double&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class TableStore - Storage

Method TableStore::Read: loads the trained feature description and sample values to initialize the classifier from a file (ASCII path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .cls extension recommended

Method TableStore::Read: loads the trained feature description and sample values to initialize the classifier from a file (UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .cls extension recommended


Member of the class TableStore - Storage

Method TableStore::Write: saves the trained feature description and sample values for later reuse to a file (ASCII path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .cls extension recommended

Method TableStore::Write: saves the trained feature description and sample values for later reuse to a file (UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .cls extension recommended


Member of the class TableStore - Text Input/Output

Method TableStore::ToAsciiString: convert the content of the table to tabular text

char* ToAsciiString(int FeatureColumn = All, int SampleRow = All);

returned char*: the text string

BlobSelection FeatureColumn: column index, in range 0..NumFeatures-1 or All

BlobSelection SampleRow: row index, in range 0..NumSamples-1, or All


Member of the class TableStore - Text Input/Output

Method TableStore::ToUnicodeString: convert the content of the table to tabular text

wchar_t* ToUnicodeString(int FeatureColumn = All, int SampleRow = All);

returned wchar_t*: the Unicode text string

BlobSelection FeatureColumn: column index, in range 0..NumFeatures-1, or All

BlobSelection SampleRow: row index, in range 0..NumSamples-1, or All


Member of the class TableStore - Text Input/Output

Method TableStore::FromAsciiString: input table rows from a tabular text representation

void FromAsciiString(char* Text);

char* Text: the Ascii text string


Member of the class TableStore - Text Input/Output

Method TableStore::FromUnicodeString: input table rows from a tabular text representation

void FromUnicodeString(wchar_t* Text);

wchar_t* Text: the Unicode text string


Member of the class TableStore - Clipboard

Method TableStore::CopyToClipboard: copy the table to the clipboard, as tabular text

void CopyToClipboard(int FeatureColumn = All, int SampleRow = All);

BlobSelection FeatureColumn: column index, in range 0..NumFeatures-1, or All

BlobSelection SampleRow: index of the row to be copied, or All


Member of the class TableStore - Clipboard

Method TableStore::PasteFromClipboard: paste table rows from the clipboard, using a tabular text representation; the column titles must match

void PasteFromClipboard();


Enumeration

Enum Metrics: formula used to compute the distances; choose after the homogeneity of the data

Case StraightDistance: the usual Euclidean distance, i.e. the sum of squared differences

Case ScaledDistance: the Euclidean distance with terms weighted by the inverses of the variances, for more isotropy

Case MahalanobisDistance: the Euclidean distance after inverse transform by the variance/covariance matrix, for whitening


Class Classifier

General-purpose storage for tabular data and classification by feature vectors

Constructor Classifier: creates a void Classifier object

Destructor ~Classifier: destroys the object

Features Management

Method AppendFeature: add a feature column

Method Type: image pixel data type

Method Name: get the name of a feature

Method ClearFeatures: removes all feature columns

Samples Management

Method AppendSample: add a sample row

Method ClearSamples: removes all sample rows

Value Access

Method BoolValue: accessor to a Boolean feature

Method GrayValue: accessor to a feature of type Gray

Method Gray16Value: accessor to a feature of type Gray16

Method RgbValue: accessor to an RGB color feature

Method IntValue: accessor to an integer feature

Method FloatValue: accessor to a single precision feature

Method DbleValue: accessor to a double precision feature

Training

Method TrainClusters: computes the centers and extents (covariance matrix) of the feature vectors, per class

Method TrainNeighbors: prepares the sample set for efficient comparison

Method ClusterCenter: compute the center of cluster, obtained as the average of feature values

Method ClusterCovariance: compute the variance or covariance in a cluster

Matching

Property Mode: Way to compute the distance between the samples, as defined by enum Metrics

Method SlowNearestNeighbor: less optimized version of the NearestNeighbor method

Method SlowNearestNeighbors: less optimized version of the NearestNeighbors method

Method NearestNeighbor: finds the trained sample the most similar to the given one

Method NearestNeighbors: finds the trained samples the most similar to the given one

Method NearestCenter: find the nearest class center, in the Euclidean sense

Method NearestCluster: find the nearest class cluster, using the current per-cluster metric

Performance Assessment

Method InterDistance: distance between to class centers

Method CrossValidateClusters: evaluates the performance of a training by counting the correct classifications in a validation set, using the nearest cluster method

Method CrossValidateNeighbors: evaluates the performance of a training by counting the correct classifications in a validation set, using the K-nearest neighbors method

Storage

Method Read: loads the trained feature description and sample values to initialize the classifier from a file (ASCII path and name)

Method Write: saves the trained feature description and sample values for later reuse to a file (ASCII path and name)

Graphics

Method PlotY: plot a diagram (I, Y) from a feature; multiple Y are also possible

Method PlotXY: plot a 2D diagram (X, Y) from a pair of features; multiple Y are also possible

Clipboard

Method CopyToClipboard: copy the table to the clipboard, as tabular text

Method PasteFromClipboard: paste table rows from the clipboard, using a tabular text representation; the column titles must match


Member of the class Classifier

Constructor Classifier::Classifier: creates a void Classifier object

Classifier();


Member of the class Classifier

Destructor Classifier::~Classifier: destroys the object

~Classifier();


Member of the class Classifier - Features Management

Method Classifier::AppendFeature: add a feature column

void AppendFeature(PixelTypes Type, wchar_t* Name = EmptyString);

PixelTypes Type: image pixel data type

wchar_t* Name: name of the feature


Member of the class Classifier - Features Management

Method Classifier::Type: image pixel data type

PixelTypes Type(int FeatureColumn);

returned PixelTypes: the feature type, as enumerated in PixelTypes

int FeatureColumn: column index, in range 0..NumFeatures-1


Member of the class Classifier - Features Management

Method Classifier::Name: get the name of a feature

wchar_t* Name(int FeatureColumn);

returned wchar_t*: the feature name, a null-terminated string

int FeatureColumn: column index of the feature


Member of the class Classifier - Features Management

Method Classifier::ClearFeatures: removes all feature columns

void ClearFeatures();


Member of the class Classifier - Samples Management

Method Classifier::AppendSample: add a sample row

void AppendSample(int Count = 1);

int Count: number of rows to be added; 1 by default


Member of the class Classifier - Samples Management

Method Classifier::ClearSamples: removes all sample rows

void ClearSamples();


Member of the class Classifier - Value Access

Method Classifier::BoolValue: accessor to a Boolean feature

bool& BoolValue(int FeatureColumn, int SampleRow = -1);

returned bool&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Value Access

Method Classifier::GrayValue: accessor to a feature of type Gray

GrayPixel& GrayValue(int FeatureColumn, int SampleRow = -1);

returned GrayPixel&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Value Access

Method Classifier::Gray16Value: accessor to a feature of type Gray16

Gray16Pixel& Gray16Value(int FeatureColumn, int SampleRow = -1);

returned Gray16Pixel&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Value Access

Method Classifier::RgbValue: accessor to an RGB color feature

RgbPixel& RgbValue(int FeatureColumn, int SampleRow = -1);

returned RgbPixel&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Value Access

Method Classifier::IntValue: accessor to an integer feature

int& IntValue(int FeatureColumn, int SampleRow = -1);

returned int&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Value Access

Method Classifier::FloatValue: accessor to a single precision feature

float& FloatValue(int FeatureColumn, int SampleRow = -1);

returned float&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Value Access

Method Classifier::DbleValue: accessor to a double precision feature

double& DbleValue(int FeatureColumn, int SampleRow = -1);

returned double&: the feature value

int FeatureColumn: column index of the feature

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Training

Method Classifier::TrainClusters: computes the centers and extents (covariance matrix) of the feature vectors, per class

void TrainClusters(int NumSetFeatures, int FeatureSet[], int ClassColumn, int NumClasses);

int NumSetFeatures: number of features in the feature set

int* FeatureSet: indexes of the feature participating in the feature set

int ClassColumn: index of the feature giving the class labels, in range [0..NumFeatures-1]

int NumClasses: index of the feature giving the class labels, in range [0..NumFeatures-1]


Member of the class Classifier - Training

Method Classifier::TrainNeighbors: prepares the sample set for efficient comparison

void TrainNeighbors(int NumSetFeatures, int FeatureSet[], int ClassColumn);

int NumSetFeatures: length of the list of features

int* FeatureSet: list of feature indexes used for the classification

int ClassColumn: index of the feature corresponding to the class


Member of the class Classifier - Training

Method Classifier::ClusterCenter: compute the center of cluster, obtained as the average of feature values

double ClusterCenter(int ClassLabel, int FeatureIndex);

returned double: mean feature value

int ClassLabel: class label of the cluster

int FeatureIndex: index of the desired feature


Member of the class Classifier - Training

Method Classifier::ClusterCovariance: compute the variance or covariance in a cluster

double ClusterCovariance(int ClassLabel, int FeatureIndex, int FeatureIndexB);

returned double: the covariance for the desired feature pair (or the variance when they are equal)

int ClassLabel: class label of the cluster

int FeatureIndex: index of the first feature

int FeatureIndexB: index of the second feature


Member of the class Classifier - Matching

Property Metrics Classifier::Mode: Way to compute the distance between the samples, as defined by enum Metrics


Member of the class Classifier - Matching

Method Classifier::SlowNearestNeighbor: less optimized version of the NearestNeighbor method

int SlowNearestNeighbor(int& NearIndex, double& NearDistance, int SampleRow = -1);

returned int: the class label of the most similar training sample

int& NearIndex: index of the most similar sample

double& NearDistance: distance to the most similar sample

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Matching

Method Classifier::SlowNearestNeighbors: less optimized version of the NearestNeighbors method

int SlowNearestNeighbors(int K, int& NearIndex, double& NearDistance, int SampleRow = -1);

returned int: class of the most similar training sample

int K: number of nearest neighbors to be retrieved

int& NearIndex: index of the most similar sample (not necessarily of the most frequent class)

double& NearDistance: distance to the most similar sample

int SampleRow: row index of the sample; -1 by default, i.e. the last row

Method Classifier::SlowNearestNeighbors: unoptimized version of the Nearest method(s)

void SlowNearestNeighbors(int K, int NearIndexes[], double NearDistances[], int SampleRow = -1);

int K: number of nearest neighbors to be retrieved

int* NearIndexes: array of indexes of the most similar samples

double* NearDistances: array of distances to the most similar samples

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Matching

Method Classifier::NearestNeighbor: finds the trained sample the most similar to the given one

int NearestNeighbor(int& NearIndex, double& NearDistance, int SampleRow = -1);

returned int: the class label of the most similar training sample

int& NearIndex: index of the most similar sample

double& NearDistance: distance to the most similar sample

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Matching

Method Classifier::NearestNeighbors: finds the trained samples the most similar to the given one

int NearestNeighbors(int K, int& NearIndex, double& NearDistance, int SampleRow = -1);

returned int: the class label of the most similar training sample

int K: number of nearest neighbors to be used for voting

int& NearIndex: index of the most similar sample (not necessarily of the most frequent class)

double& NearDistance: distance to the most similar sample

int SampleRow: row index of the sample; -1 by default, i.e. the last row

Method Classifier::NearestNeighbors: finds the K trained samples the most similar to the given one and performs a majority vote

void NearestNeighbors(int K, int NearIndexes[], double NearDistances[], int SampleRow = -1);

int K: number of nearest neighbors to be used for voting

int* NearIndexes: array of indexes of the most similar samples

double* NearDistances: array of distances to the most similar samples

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Matching

Method Classifier::NearestCenter: find the nearest class center, in the Euclidean sense

int NearestCenter(double& NearDistance, int SampleRow = -1);

returned int: the label of the closest class center

double& NearDistance: Euclidean distance to the nearest cluster

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Matching

Method Classifier::NearestCluster: find the nearest class cluster, using the current per-cluster metric

int NearestCluster(double& NearDistance, int SampleRow = -1);

returned int: the class label of the closest class center, using the current per-cluster metric

double& NearDistance: distance to the nearest cluster, using the current per-cluster metric)

int SampleRow: row index of the sample; -1 by default, i.e. the last row


Member of the class Classifier - Performance Assessment

Method Classifier::InterDistance: distance between to class centers

double InterDistance(int ClassLabel, int ClassLabelB);

returned double: the distance

int ClassLabel: class label of the first cluster

int ClassLabelB: class label of the second cluster


Member of the class Classifier - Performance Assessment

Method Classifier::CrossValidateClusters: evaluates the performance of a training by counting the correct classifications in a validation set, using the nearest cluster method

int CrossValidateClusters(int SampleRow, int NumSamples);

returned int: the number of correctly classified samples

int SampleRow: row index of the first sample; -1 by default, i.e. the last row

int NumSamples: number of samples to be tested, starting from SampleIndex


Member of the class Classifier - Performance Assessment

Method Classifier::CrossValidateNeighbors: evaluates the performance of a training by counting the correct classifications in a validation set, using the K-nearest neighbors method

int CrossValidateNeighbors(int K, int SampleRow, int NumSamples);

returned int: the number of correctly classified samples

int K: number of nearest neighbors to be used for voting

int SampleRow: row index of the first sample; -1 by default, i.e. the last row

int NumSamples: number of samples to be tested, starting from SampleIndex


Member of the class Classifier - Storage

Method Classifier::Read: loads the trained feature description and sample values to initialize the classifier from a file (ASCII path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .cls extension recommended

Method Classifier::Read: loads the trained feature description and sample values to initialize the classifier from a file (UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .cls extension recommended


Member of the class Classifier - Storage

Method Classifier::Write: saves the trained feature description and sample values for later reuse to a file (ASCII path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .cls extension recommended

Method Classifier::Write: saves the trained feature description and sample values for later reuse to a file (UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .cls extension recommended


Member of the class Classifier - Graphics

Method Classifier::PlotY: plot a diagram (I, Y) from a feature; multiple Y are also possible

void PlotY(Limits& Bounds, int FeatureYIndex, double MinYValue = 0, double MaxYValue = 0);

Limits& Bounds: X and Y limits of the plot area, in pixels

int FeatureYIndex: index of the feature to be plotted

double MinYValue: smallest X value

double MaxYValue: largest Y value

Method Classifier::PlotY: plot a diagram (I, Y) from a feature; multiple Y are also possible

void PlotY(Limits& Bounds, int FeatureYSet[], int SizeYSet, double MinYValue = 0, double MaxYValue = 0);

Limits& Bounds: X and Y limits of the plot area, in pixels

int* FeatureYSet: list of indexes to be plotted

int SizeYSet: number of features in the set

double MinYValue: smallest X value

double MaxYValue: largest Y value


Member of the class Classifier - Graphics

Method Classifier::PlotXY: plot a 2D diagram (X, Y) from a pair of features; multiple Y are also possible

void PlotXY(Limits& Bounds, int FeatureXIndex, int FeatureYIndex, double MinXValue = 0, double MaxXValue = 0, double MinYValue = 0, double MaxYValue = 0);

Limits& Bounds: X and Y limits of the plot area, in pixels

int FeatureXIndex: index of the feature in abscissa

int FeatureYIndex: index of the feature in ordinate

double MinXValue: smallest X value

double MaxXValue: largest X value

double MinYValue: smallest Y value

double MaxYValue: largest Y value

Method Classifier::PlotXY: plot a diagram (I, Y) from a feature; multiple Y are also possible

void PlotXY(Limits& Bounds, int FeatureXIndex, int FeatureYSet[], int SizeYSet, double MinXValue = 0, double MaxXValue = 0, double MinYValue = 0, double MaxYValue = 0);

Limits& Bounds: X and Y limits of the plot area, in pixels

int FeatureXIndex: index of the feature in abscissa

int* FeatureYSet: list of indexes to be plotted

int SizeYSet: number of features in the set

double MinXValue: smallest X value

double MaxXValue: largest X value

double MinYValue: smallest Y value

double MaxYValue: largest Y value


Member of the class Classifier - Clipboard

Method Classifier::CopyToClipboard: copy the table to the clipboard, as tabular text

void CopyToClipboard(int FeatureColumn = All, int SampleRow = All);

BlobSelection FeatureColumn: column index, in range 0..NumFeatures-1, or All

BlobSelection SampleRow: index of the row to be copied, or All


Member of the class Classifier - Clipboard

Method Classifier::PasteFromClipboard: paste table rows from the clipboard, using a tabular text representation; the column titles must match

void PasteFromClipboard();


Enumeration

Enum EdgeSelection: pseudo-index that designates an edge selection criterion

Case BestSlope: the edge with largest slope (sharpness)

Case BestStep: the edge with the largest step (contrast)

Case BestSpan: the edge with the largest span (width)

Case OverCenter: the edge that straddles the center of the profile (reserved)


Struct Edge

Descriptor of a detected edge point

Strength Assessment

Property Slope: the maximum value of the first derivative of the signal

Property Span: the length of the transition along the signal

Property Step: the difference between the extreme values in the signal

Sub-pixel Position

Property Start: the integer index of the first edge pixel

Property T: the sub-pixel position of the edge along the signal profile

Property X: sub-pixel abscissa of the detected point

Property Y: sub-pixel ordinate of the detected point

Class

Property Class: the class of the edge; reserved for internal use


Member of the class Edge - Strength Assessment

Property int Edge::Slope: the maximum value of the first derivative of the signal


Member of the class Edge - Strength Assessment

Property int Edge::Span: the length of the transition along the signal


Member of the class Edge - Strength Assessment

Property int Edge::Step: the difference between the extreme values in the signal


Member of the class Edge - Sub-pixel Position

Property int Edge::Start: the integer index of the first edge pixel


Member of the class Edge - Sub-pixel Position

Property double Edge::T: the sub-pixel position of the edge along the signal profile


Member of the class Edge - Sub-pixel Position

Property double Edge::X: sub-pixel abscissa of the detected point


Member of the class Edge - Sub-pixel Position

Property double Edge::Y: sub-pixel ordinate of the detected point


Member of the class Edge - Class

Property int Edge::Class: the class of the edge; reserved for internal use


Class EdgePoint

Edge point detector; will detect the edges that cross a given line segment and report the crossing points

Constructor EdgePoint: creates an uninitialized EdgePoint object

Location

Method Locate: specify the gauge position

Property From: starting point of the edge point detection probe

Property To: ending point of the edge detection probe

Property XMin: smallest abscissa of the bounding box of the sampling area

Property YMin: smallest ordinate of the bounding box of the sampling area

Property XMax: largest abscissa of the bounding box of the sampling area

Property YMax: largest ordinate of the bounding box of the sampling area

Measurement

Property Breadth: breadth of the edge detection probe, in pixels

Property Smoothing: longitudinal filter strength for noise removal

Property Noise: noise level under which signal values are ignored

Property MinimumSlope: slope level under which signal peaks are not considered as valid points

Property MinimumStep: the minimum value of the Step feature; below this value, the edge is ignored

Property MinimumSpan: the minimum value of the Span feature; below this value, the edge is ignored

Property Polarity: allowed transition polarity of the detected edges

Property SplitPeaks: when edges of the same polarity are next to each other, they may fail to be separated. When the split peaks mode is in action the touching edges are separated and only the strongest one is kept

Method Detect: detects the edge points along the probe in the given image

Detection Results

Method NumPoints: number of detected edge points

Method FittedEdge: accessor to a given detected edge point

Method FittedPoint: accessor to the coordinates of a detected edge point (uncalibrated or calibrated)

Storage

Method Read: load the edge point parameters from a file (ASCII or UNICODE path and name)

Method Write: save the edge point parameters to a file (ASCII or UNICODE path and name)

Graphics

Method SetWindow: defines the limits of the source image used for detection

Method Draw: draws the measurement probe as an overlay on the current drawing window, with the detected edges

Method HitHandle: identity of the handle under the cursor

Property Handle: identity of the last hit handle

Property HandleOctant: hint for the choice of the cursor shape when a handle has been hit

Method Drag: when dragging on the screen; moves the edge detection probe by dragging the last hit handle, if any


Member of the class EdgePoint

Constructor EdgePoint::EdgePoint: creates an uninitialized EdgePoint object

EdgePoint();


Member of the class EdgePoint - Location

Method EdgePoint::Locate: specify the gauge position

void Locate(XY& Center, double Length, double Angle);

XY& Center: coordinates of the center point of the gauge

double Length: length of the gauge in pixels

double Angle: orientation angle in the current angle unit


Member of the class EdgePoint - Location

Property XY EdgePoint::From: starting point of the edge point detection probe


Member of the class EdgePoint - Location

Property XY EdgePoint::To: ending point of the edge detection probe


Member of the class EdgePoint - Location

Property int EdgePoint::XMin: smallest abscissa of the bounding box of the sampling area


Member of the class EdgePoint - Location

Property int EdgePoint::YMin: smallest ordinate of the bounding box of the sampling area


Member of the class EdgePoint - Location

Property int EdgePoint::XMax: largest abscissa of the bounding box of the sampling area


Member of the class EdgePoint - Location

Property int EdgePoint::YMax: largest ordinate of the bounding box of the sampling area


Member of the class EdgePoint - Measurement

Property int EdgePoint::Breadth: breadth of the edge detection probe, in pixels


Member of the class EdgePoint - Measurement

Property int EdgePoint::Smoothing: longitudinal filter strength for noise removal


Member of the class EdgePoint - Measurement

Property int EdgePoint::Noise: noise level under which signal values are ignored


Member of the class EdgePoint - Measurement

Property int EdgePoint::MinimumSlope: slope level under which signal peaks are not considered as valid points


Member of the class EdgePoint - Measurement

Property int EdgePoint::MinimumStep: the minimum value of the Step feature; below this value, the edge is ignored


Member of the class EdgePoint - Measurement

Property int EdgePoint::MinimumSpan: the minimum value of the Span feature; below this value, the edge is ignored


Member of the class EdgePoint - Measurement

Property Polarities EdgePoint::Polarity: allowed transition polarity of the detected edges


Member of the class EdgePoint - Measurement

Property bool EdgePoint::SplitPeaks: when edges of the same polarity are next to each other, they may fail to be separated. When the split peaks mode is in action the touching edges are separated and only the strongest one is kept


Member of the class EdgePoint - Measurement

Method EdgePoint::Detect: detects the edge points along the probe in the given image

bool Detect(const Image& Src);

returned bool: true if at least one point was detected

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Method EdgePoint::Detect: detects the edge points along the probe in the given image

bool Detect(const Image& Src, const Geometry& Calibrator);

returned bool: true if at least one point was detected

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration


Member of the class EdgePoint - Detection Results

Method EdgePoint::NumPoints: number of detected edge points

int NumPoints(enum Polarities Polarity = Both);

returned int: integer value; read-only

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both (default)


Member of the class EdgePoint - Detection Results

Method EdgePoint::FittedEdge: accessor to a given detected edge point

Edge FittedEdge(int Index, enum Polarities Polarity = Both);

returned Edge: edge point descriptor

int Index: index of the desired point, in range [-NumPoints..NumPoints-1], or one of BestSlope, BestStep (default) or BestSpan

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both (default)


Member of the class EdgePoint - Detection Results

Method EdgePoint::FittedPoint: accessor to the coordinates of a detected edge point (uncalibrated or calibrated)

XY FittedPoint(int Index, enum Polarities Polarity = Both);

returned XY: (X, Y) point coordinates

int Index: zero-based index value to access a list of items

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both

Method EdgePoint::FittedPoint: accessor to the coordinates of a detected edge point (uncalibrated or calibrated)

XY FittedPoint(const Geometry& Calibrator, int Index, enum Polarities Polarity = Both);

returned XY: (X, Y) point coordinates

Geometry& Calibrator: the Calibrator used to calibrate the image, if any

int Index: zero-based index value to access a list of items

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both


Member of the class EdgePoint - Storage

Method EdgePoint::Read: load the edge point parameters from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .edp extension recommended

Method EdgePoint::Read: load the edge point parameters from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .edp extension recommended


Member of the class EdgePoint - Storage

Method EdgePoint::Write: save the edge point parameters to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .edp extension recommended

Method EdgePoint::Write: save the edge point parameters to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .edp extension recommended


Member of the class EdgePoint - Graphics

Method EdgePoint::SetWindow: defines the limits of the source image used for detection

void SetWindow(int X, int Y, int Width, int Height);

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels, horizontally

int Height: number of pixels, vertically

Method EdgePoint::SetWindow: defines the limits of the source image used for detection

void SetWindow(const Image& Src);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst


Member of the class EdgePoint - Graphics

Method EdgePoint::Draw: draws the measurement probe as an overlay on the current drawing window, with the detected edges

void Draw(bool Handles = false, bool Points = false);

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too

Method EdgePoint::Draw: draws the measurement probe as an overlay on the current drawing window, with the detected edges

void Draw(const Geometry& Calibrator, bool Handles = false, bool Points = false);

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too


Member of the class EdgePoint - Graphics

Method EdgePoint::HitHandle: identity of the handle under the cursor

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: a value enumerated in DraggingHandles

int CursorX: point abscissa, in pixels

int CursorY: point ordinate, in pixels, top-down


Member of the class EdgePoint - Graphics

Property DraggingHandles EdgePoint::Handle: identity of the last hit handle


Member of the class EdgePoint - Graphics

Property int EdgePoint::HandleOctant(): hint for the choice of the cursor shape when a handle has been hit


Member of the class EdgePoint - Graphics

Method EdgePoint::Drag: when dragging on the screen; moves the edge detection probe by dragging the last hit handle, if any

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Enumeration

Enum FittingSide: specifies where line fitting is to be performed

Case FitOver: the error is minimized and the line runs between the edge points

Case FitBefore: the line comes in contact with the edge points before them (in the gauge direction)

Case FitAfter: the line comes in contact with the shape after them (in the gauge direction)


Class EdgeLine

Edge line detector; will detect the straight edges that follow a given line segment and fit it accurately

Constructor EdgeLine: creates a void EdgeLine object

Location

Method Locate: moves the gauge to the desired location

Property Beg: first endpoint of the reference line

Property End: second endpoint of the reference line

Property Width: width of the sampled region, in pixels

Measurement

Property Density: spacing of the sampling profiles, in pixels

Property Clearance: empty space at the line endpoints where sampling is avoided (in the vicinity of corners)

Property Oblique: when true, the image is sampled perpendicularly to the reference line; otherwise only sampling is made horizontally or vertically to avoid interpolation

Property Fitting: select among the fitting options as defined by enum FittingSide; FittingOver by default

Method Detect: locate the edge near the reference line

Property NumSamples: total number of profiles to be sampled

Property SampleIndex: All for normal operation, as by default, or index in the range 0..NumSamples-1 to evaluate a single sample, before a FittedPoint query

Method FittedPoint: accessor to the coordinates of the last detected edge points as selected by SampleIndex

Fit

Property FittedBeg: coordinates of the first endpoint of the fitted line

Property FittedEnd: coordinates of the second endpoint of the fitted line

Property FittedAngle: orientation angle of the fitted line, from horizontal, clockwise

Property NumDetectedPoints: number of detected points used for the fitting, after outlier rejection

Property Deviation: average distance between the fitted line and the measured points, in pixels; can be used as a linearity criterion

Property NumFittedPoints: number of points detected along the edge

Property RobustDeviation: average distance between the fitted line and the measured points, in pixels, after outlier rejection

Method Realign: moves the gauge so that the reference line overlaps the fitted line

Storage

Method Read: load the edge line parameters from a file (ASCII or UNICODE path and name)

Method Write: save the edge line parameters to a file (ASCII or UNICODE path and name)

Graphics

Method Draw: renders the gauge in the current drawing window

Method HitHandle: returns the dragging handle under the cursor, or NoHandle

Property Handle: identity of the last dragging handle hit

Property HandleOctant: hint for the choice of the cursor shape when a handle has been hit

Method Drag: move the current dragging handle


Member of the class EdgeLine

Constructor EdgeLine::EdgeLine: creates a void EdgeLine object

EdgeLine();


Member of the class EdgeLine - Location

Method EdgeLine::Locate: moves the gauge to the desired location

void Locate(double Width = 32);

double Width: breadth of the gauge, i.e. length of the individual point profiles used

Method EdgeLine::Locate: moves the gauge to the desired location

void Locate(XY& Center, double Length, double Angle, double Width = 32);

XY& Center: center point of the gauge

double Length: length of the gauge, distance between the endpoints

double Angle: orientation angle of the gauge, from horizontal, clockwise

double Width: breadth of the gauge, i.e. length of the individual point profiles used


Member of the class EdgeLine - Location

Property XY EdgeLine::Beg: first endpoint of the reference line


Member of the class EdgeLine - Location

Property XY EdgeLine::End: second endpoint of the reference line


Member of the class EdgeLine - Location

Property double EdgeLine::Width: width of the sampled region, in pixels


Member of the class EdgeLine - Measurement

Property double EdgeLine::Density: spacing of the sampling profiles, in pixels


Member of the class EdgeLine - Measurement

Property double EdgeLine::Clearance: empty space at the line endpoints where sampling is avoided (in the vicinity of corners)


Member of the class EdgeLine - Measurement

Property bool EdgeLine::Oblique: when true, the image is sampled perpendicularly to the reference line; otherwise only sampling is made horizontally or vertically to avoid interpolation


Member of the class EdgeLine - Measurement

Property FittingSide EdgeLine::Fitting: select among the fitting options as defined by enum FittingSide; FittingOver by default


Member of the class EdgeLine - Measurement

Method EdgeLine::Detect: locate the edge near the reference line

bool Detect(const Image& Src, int EdgeIndex = BestStep);

returned bool: true if the detection succeeded (can fail because of too few points available)

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

EdgeSelection EdgeIndex: one of BestStep, BestSlope, BestSpan or zero-based positive/negative index (from begin/end)

Method EdgeLine::Detect: locate the edge near the reference line

bool Detect(const Image& Src, const Geometry& Calibrator, int EdgeIndex = BestStep);

returned bool: true if the detection succeeded (can fail because of too few points available)

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

EdgeSelection EdgeIndex: one of BestStep, BestSlope, BestSpan or zero-based positive/negative index (from begin/end)


Member of the class EdgeLine - Measurement

Property int EdgeLine::NumSamples: total number of profiles to be sampled


Member of the class EdgeLine - Measurement

Property BlobSelection EdgeLine::SampleIndex: All for normal operation, as by default, or index in the range 0..NumSamples-1 to evaluate a single sample, before a FittedPoint query


Member of the class EdgeLine - Measurement

Method EdgeLine::FittedPoint: accessor to the coordinates of the last detected edge points as selected by SampleIndex

XY FittedPoint(int Index, Polarities Polarity = Both);

returned XY: (X, Y) point coordinates

int Index: index of the desired point, in range [-NumPoints..NumPoints-1], or one of BestSlope, BestStep (default) or BestSpan

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both


Member of the class EdgeLine - Fit

Property XY EdgeLine::FittedBeg: coordinates of the first endpoint of the fitted line


Member of the class EdgeLine - Fit

Property XY EdgeLine::FittedEnd: coordinates of the second endpoint of the fitted line


Member of the class EdgeLine - Fit

Property double EdgeLine::FittedAngle: orientation angle of the fitted line, from horizontal, clockwise


Member of the class EdgeLine - Fit

Property int EdgeLine::NumDetectedPoints: number of detected points used for the fitting, after outlier rejection


Member of the class EdgeLine - Fit

Property double EdgeLine::Deviation: average distance between the fitted line and the measured points, in pixels; can be used as a linearity criterion


Member of the class EdgeLine - Fit

Property int EdgeLine::NumFittedPoints: number of points detected along the edge


Member of the class EdgeLine - Fit

Property double EdgeLine::RobustDeviation: average distance between the fitted line and the measured points, in pixels, after outlier rejection


Member of the class EdgeLine - Fit

Method EdgeLine::Realign: moves the gauge so that the reference line overlaps the fitted line

void Realign();


Member of the class EdgeLine - Storage

Method EdgeLine::Read: load the edge line parameters from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .edl extension recommended

Method EdgeLine::Read: load the edge line parameters from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .edl extension recommended


Member of the class EdgeLine - Storage

Method EdgeLine::Write: save the edge line parameters to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .edl extension recommended

Method EdgeLine::Write: save the edge line parameters to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .edl extension recommended


Member of the class EdgeLine - Graphics

Method EdgeLine::Draw: renders the gauge in the current drawing window

void Draw(bool Handles = false, bool Points = false);

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too

Method EdgeLine::Draw: renders the gauge in the current drawing window

void Draw(const Geometry& Calibrator, bool Handles = false, bool Points = false);

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too


Member of the class EdgeLine - Graphics

Method EdgeLine::HitHandle: returns the dragging handle under the cursor, or NoHandle

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: identity of the dragging handle, or NoHandle

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class EdgeLine - Graphics

Property DraggingHandles EdgeLine::Handle: identity of the last dragging handle hit


Member of the class EdgeLine - Graphics

Property int EdgeLine::HandleOctant(): hint for the choice of the cursor shape when a handle has been hit


Member of the class EdgeLine - Graphics

Method EdgeLine::Drag: move the current dragging handle

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Class EdgeArc

Edge arc detector; will detect the curved edges that follow a given circular arc (or circle) and fit it accurately

Constructor EdgeArc: creates a void EdgeArc object

Location

Method Locate: moves the circle gauge to the desired location

Property Beg: beginngin handle point

Property Mid: intermediate handle point

Property End: ending handle point

Property Center: moves the gauge so that the reference arc overlaps the fitted arc

Property Radius: radius of the nominal center of the gauge, in pixels

Property Width: width of the sampled region, in pixels

Measurement

Property Density: spacing between the sampling profiles

Property Clearance: empty space at the arc endpoints where sampling is avoided

Property Oblique: when true, the image is sampled perpendicularly to the arc; otherwise, only vertical and horizontal profiles are used to avoid resampling

Property Closed: when true, the gauge is a full circle

Property Fitting: select among the fitting options as defined by enum FittingSide; FittingOver by default

Method Detect: locate the edge near the reference arc

Property NumSamples: total number of profiles to be sampled

Property SampleIndex: All for normal operation, as by default, or an index in the range 0..NumSamples-1 to evaluate a single sample, before a FittedPoint query

Method FittedPoint: accessor to the coordinates of the last detected edge points as selected by SampleIndex

Longitudinal Detection

Method DetectAlong: detect the edges crossed by the circle; the results are retrieved as those of an EdgePoint

Fit

Property FittedCenter: coordinates of the center of the fitted circle

Property FittedRadius: radius of the fitted circle

Property NumDetectedPoints: number of points detected along the edge

Property Deviation: average distance between the fitted circle and the measured points, in pixels; can be used as a circularity criterion

Property NumFittedPoints: number of detected points used for the fitting, after outlier rejection

Property RobustDeviation: average distance between the fitted circle and the measured points, in pixels, after outlier rejection

Method Realign: moves the gauge so that the reference arc overlaps the fitted arc

Storage

Method Read: load the edge arc parameters from a file (ASCII or UNICODE path and name)

Method Write: save the edge arc parameters to a file (ASCII or UNICODE path and name)

Graphics

Method Draw: renders the gauge in the current drawing window

Method HitHandle: returns the dragging handle under the cursor, or NoHandle

Property Handle: identity of the last dragging handle hit

Property HandleOctant: hint for the choice of the cursor shape when a handle has been hit

Method Drag: move the current dragging handle


Member of the class EdgeArc

Constructor EdgeArc::EdgeArc: creates a void EdgeArc object

EdgeArc();


Member of the class EdgeArc - Location

Method EdgeArc::Locate: moves the circle gauge to the desired location

void Locate(double Width = 32, bool Closed = true);

double Width: breadth of the gauge, i.e. length of the individual point profiles used

bool Closed: when true, the gauge is a full circle

Method EdgeArc::Locate: moves the arc gauge to the desired location

void Locate(XY& Center, double Radius, double Width = 32);

XY& Center: arc center of the gauge

double Radius: arc radius of the gauge

double Width: breadth of the gauge, i.e. length of the individual point profiles used

Method EdgeArc::Locate: moves the circle gauge to the desired location

void Locate(XY& Center, double Radius, double BegAngle, double EndAngle, double Width = 32);

XY& Center: arc center of the gauge

double Radius: arc radius of the gauge

double BegAngle: starting angle of the gauge

double EndAngle: ending angle of the gauge

double Width: breadth of the gauge, i.e. length of the individual point profiles used


Member of the class EdgeArc - Location

Property XY EdgeArc::Beg: beginngin handle point


Member of the class EdgeArc - Location

Property XY EdgeArc::Mid: intermediate handle point


Member of the class EdgeArc - Location

Property XY EdgeArc::End: ending handle point


Member of the class EdgeArc - Location

Property XY EdgeArc::Center: moves the gauge so that the reference arc overlaps the fitted arc


Member of the class EdgeArc - Location

Property double EdgeArc::Radius: radius of the nominal center of the gauge, in pixels


Member of the class EdgeArc - Location

Property double EdgeArc::Width: width of the sampled region, in pixels


Member of the class EdgeArc - Measurement

Property double EdgeArc::Density: spacing between the sampling profiles


Member of the class EdgeArc - Measurement

Property double EdgeArc::Clearance: empty space at the arc endpoints where sampling is avoided


Member of the class EdgeArc - Measurement

Property bool EdgeArc::Oblique: when true, the image is sampled perpendicularly to the arc; otherwise, only vertical and horizontal profiles are used to avoid resampling


Member of the class EdgeArc - Measurement

Property bool EdgeArc::Closed: when true, the gauge is a full circle


Member of the class EdgeArc - Measurement

Property FittingSide EdgeArc::Fitting: select among the fitting options as defined by enum FittingSide; FittingOver by default


Member of the class EdgeArc - Measurement

Method EdgeArc::Detect: locate the edge near the reference arc

bool Detect(const Image& Src, int EdgeIndex = BestStep);

returned bool: true if the detection succeeded (can fail because of too few points available)

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

EdgeSelection EdgeIndex: one of BestStep, BestSlope, BestSpan or zero-based positive/negative index (from begin/end)

Method EdgeArc::Detect: locate the edge near the reference arc

bool Detect(const Image& Src, const Geometry& Calibrator, int EdgeIndex = BestStep);

returned bool: true if the detection succeeded (can fail because of too few points available)

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

EdgeSelection EdgeIndex: one of BestStep, BestSlope, BestSpan or zero-based positive/negative index (from begin/end)


Member of the class EdgeArc - Measurement

Property int EdgeArc::NumSamples: total number of profiles to be sampled


Member of the class EdgeArc - Measurement

Property BlobSelection EdgeArc::SampleIndex: All for normal operation, as by default, or an index in the range 0..NumSamples-1 to evaluate a single sample, before a FittedPoint query


Member of the class EdgeArc - Measurement

Method EdgeArc::FittedPoint: accessor to the coordinates of the last detected edge points as selected by SampleIndex

XY FittedPoint(int Index, Polarities Polarity = Both);

returned XY: (X, Y) point coordinates

int Index: index of the desired point, in range [-NumPoints..NumPoints-1], or one of BestSlope, BestStep (default) or BestSpan

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both


Member of the class EdgeArc - Longitudinal Detection

Method EdgeArc::DetectAlong: detect the edges crossed by the circle; the results are retrieved as those of an EdgePoint

void DetectAlong(const Image& Src);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class EdgeArc - Fit

Property XY EdgeArc::FittedCenter: coordinates of the center of the fitted circle


Member of the class EdgeArc - Fit

Property double EdgeArc::FittedRadius: radius of the fitted circle


Member of the class EdgeArc - Fit

Property int EdgeArc::NumDetectedPoints: number of points detected along the edge


Member of the class EdgeArc - Fit

Property double EdgeArc::Deviation: average distance between the fitted circle and the measured points, in pixels; can be used as a circularity criterion


Member of the class EdgeArc - Fit

Property int EdgeArc::NumFittedPoints: number of detected points used for the fitting, after outlier rejection


Member of the class EdgeArc - Fit

Property double EdgeArc::RobustDeviation: average distance between the fitted circle and the measured points, in pixels, after outlier rejection


Member of the class EdgeArc - Fit

Method EdgeArc::Realign: moves the gauge so that the reference arc overlaps the fitted arc

void Realign();


Member of the class EdgeArc - Storage

Method EdgeArc::Read: load the edge arc parameters from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .eda extension recommended

Method EdgeArc::Read: load the edge arc parameters from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .eda extension recommended


Member of the class EdgeArc - Storage

Method EdgeArc::Write: save the edge arc parameters to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .eda extension recommended

Method EdgeArc::Write: save the edge arc parameters to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .eda extension recommended


Member of the class EdgeArc - Graphics

Method EdgeArc::Draw: renders the gauge in the current drawing window

void Draw(bool Handles = false, bool Points = false);

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too

Method EdgeArc::Draw: renders the gauge in the current drawing window

void Draw(const Geometry& Calibrator, bool Handles = false, bool Points = false);

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too


Member of the class EdgeArc - Graphics

Method EdgeArc::HitHandle: returns the dragging handle under the cursor, or NoHandle

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: identity of the dragging handle, or NoHandle

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class EdgeArc - Graphics

Property DraggingHandles EdgeArc::Handle: identity of the last dragging handle hit


Member of the class EdgeArc - Graphics

Property int EdgeArc::HandleOctant(): hint for the choice of the cursor shape when a handle has been hit


Member of the class EdgeArc - Graphics

Method EdgeArc::Drag: move the current dragging handle

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Class EdgeEllipse

Edge ellipse detector; will detect the curved edges that follow a given elliptic arc (or ellipse) and fit it accurately

Constructor EdgeEllipse: creates a void EdgeEllipse object

Location

Method Locate: set the position of the gauge, using five handle points

Property Beg: beginning handle point

Property Mid0: first intermediate handle coordinates

Property Mid1: second intermediate handle coordinates

Property Mid2: third intermediate handle coordinates

Property End: ending handle point

Property Width: width of the sampled region, in pixels

Property Center: coordinates of the ellipse center

Property FirstAxis: first semi-axis length (usually major)

Property SecondAxis: length of the second semi-axis (usually major)

Property Angle: direction angle of the first ellipse axis, in degrees

Measurement

Property Density: spacing between the sampling profiles

Property Clearance: empty space at the arc endpoints where sampling is avoided

Property Oblique: when true, the image is sampled perpendicularly to the arc; otherwise, only vertical and horizontal profiles are used to avoid resampling

Property Closed: if true, full ellipse ; otherwise an open elliptic arc

Property Fitting: select among the fitting options as defined by enum FittingSide; currently only FittingOver, as by default, is supported

Method Detect: locate the elliptic edge near the reference ellipse

Property NumSamples: total number of profiles to be sampled

Property SampleIndex: All for normal operation, as by default, or an index in the range 0..NumSamples-1 to evaluate a single sample, before a FittedPoint query

Method FittedPoint: accessor to the coordinates of the last detected edge points as selected by SampleIndex

Fit

Property FittedCenter: coordinates of the center of the fitted ellipse

Property FittedFirstAxis: length of the first ellipse axis, as fitted (usually major)

Property FittedSecondAxis: length of the second ellipse axis, as fitted (usually minor)

Property FittedAngle: direction angle of the first semi-axis of the fitted ellipse, in degrees

Property NumDetectedPoints: number of points detected along the edge

Property Deviation: average distance between the fitted ellipse and the measured points, in pixels; can be used as an ellipticity criterion

Property NumFittedPoints: number of detected points used for the fitting, after outlier rejection

Property RobustDeviation: average distance between the fitted circle and the measured points, in pixels, after outlier rejection

Method Realign: moves the gauge so that the reference arc overlaps the fitted arc

Storage

Method Read: load the edge arc parameters from a file (ASCII or UNICODE path and name)

Method Write: save the edge arc parameters to a file (ASCII or UNICODE path and name)

Graphics

Method Draw: renders the gauge in the current drawing window

Method HitHandle: returns the dragging handle under the cursor, or NoHandle

Property Handle: identity of the last dragging handle hit

Property HandleOctant: hint for the choice of the cursor shape when a handle has been hit

Method Drag: move the current dragging handle


Member of the class EdgeEllipse

Constructor EdgeEllipse::EdgeEllipse: creates a void EdgeEllipse object

EdgeEllipse();


Member of the class EdgeEllipse - Location

Method EdgeEllipse::Locate: set the position of the gauge, using five handle points

void Locate(double Width = 32, bool Closed = true);

double Width: width of the sampled region, in pixels

bool Closed: when true, the gauge is a closed ellipse

Method EdgeEllipse::Locate: set the position of the gauge, using the geometric parameters

void Locate(const XY& Center, double FirstAxis, double SecondAxis, double Angle, double Width = 32);

XY& Center: center of the ellipse

double FirstAxis: length of the first semi-axis (usually major)

double SecondAxis: length of the second semi-axis (usually minor)

double Angle: angle of the first semi-axis wrt horizontal, in degrees

double Width: width of the sampled region, in pixels

Method EdgeEllipse::Locate: set the position of the gauge, using five handle points

void Locate(const XY& Center, double FirstAxis, double SecondAxis, double Angle, double BegAngle, double EndAngle, double Width = 32);

XY& Center: center of the ellipse

double FirstAxis: length of the first semi-axis (usually major)

double SecondAxis: length of the second semi-axis (usually minor)

double Angle: angle of the first semi-axis wrt horizontal, in degrees

double BegAngle: angle of the beginning of the arc, wrt the first semi-axis, in degrees

double EndAngle: angle of the end of the arc, wrt the first semi-axis, in degrees

double Width: width of the sampled region, in pixels


Member of the class EdgeEllipse - Location

Property XY EdgeEllipse::Beg: beginning handle point


Member of the class EdgeEllipse - Location

Property XY EdgeEllipse::Mid0: first intermediate handle coordinates


Member of the class EdgeEllipse - Location

Property XY EdgeEllipse::Mid1: second intermediate handle coordinates


Member of the class EdgeEllipse - Location

Property XY EdgeEllipse::Mid2: third intermediate handle coordinates


Member of the class EdgeEllipse - Location

Property XY EdgeEllipse::End: ending handle point


Member of the class EdgeEllipse - Location

Property double EdgeEllipse::Width: width of the sampled region, in pixels


Member of the class EdgeEllipse - Location

Property XY EdgeEllipse::Center: coordinates of the ellipse center


Member of the class EdgeEllipse - Location

Property double EdgeEllipse::FirstAxis: first semi-axis length (usually major)


Member of the class EdgeEllipse - Location

Property double EdgeEllipse::SecondAxis: length of the second semi-axis (usually major)


Member of the class EdgeEllipse - Location

Property double EdgeEllipse::Angle: direction angle of the first ellipse axis, in degrees


Member of the class EdgeEllipse - Measurement

Property double EdgeEllipse::Density: spacing between the sampling profiles


Member of the class EdgeEllipse - Measurement

Property double EdgeEllipse::Clearance: empty space at the arc endpoints where sampling is avoided


Member of the class EdgeEllipse - Measurement

Property bool EdgeEllipse::Oblique: when true, the image is sampled perpendicularly to the arc; otherwise, only vertical and horizontal profiles are used to avoid resampling


Member of the class EdgeEllipse - Measurement

Property bool EdgeEllipse::Closed: if true, full ellipse ; otherwise an open elliptic arc


Member of the class EdgeEllipse - Measurement

Property FittingSide EdgeEllipse::Fitting: select among the fitting options as defined by enum FittingSide; currently only FittingOver, as by default, is supported


Member of the class EdgeEllipse - Measurement

Method EdgeEllipse::Detect: locate the elliptic edge near the reference ellipse

bool Detect(const Image& Src, int EdgeIndex = BestStep);

returned bool: true if the detection succeeded (can fail because of too few points available)

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

EdgeSelection EdgeIndex: zero-based index value to access a list of items

Method EdgeEllipse::Detect: locate the elliptic edge near the reference ellipse, with integrated calibration

bool Detect(const Image& Src, const Geometry& Calibrator, int EdgeIndex = BestStep);

returned bool: true if the detection succeeded (can fail because of too few points available)

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

EdgeSelection EdgeIndex: zero-based index value to access a list of items


Member of the class EdgeEllipse - Measurement

Property int EdgeEllipse::NumSamples: total number of profiles to be sampled


Member of the class EdgeEllipse - Measurement

Property BlobSelection EdgeEllipse::SampleIndex: All for normal operation, as by default, or an index in the range 0..NumSamples-1 to evaluate a single sample, before a FittedPoint query


Member of the class EdgeEllipse - Measurement

Method EdgeEllipse::FittedPoint: accessor to the coordinates of the last detected edge points as selected by SampleIndex

XY FittedPoint(int Index, Polarities Polarity = Both);

returned XY: (X, Y) point coordinates

int Index: index of the desired point, in range [-NumPoints..NumPoints-1], or one of BestSlope, BestStep (default) or BestSpan

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both


Member of the class EdgeEllipse - Fit

Property XY EdgeEllipse::FittedCenter: coordinates of the center of the fitted ellipse


Member of the class EdgeEllipse - Fit

Property double EdgeEllipse::FittedFirstAxis: length of the first ellipse axis, as fitted (usually major)


Member of the class EdgeEllipse - Fit

Property double EdgeEllipse::FittedSecondAxis: length of the second ellipse axis, as fitted (usually minor)


Member of the class EdgeEllipse - Fit

Property double EdgeEllipse::FittedAngle: direction angle of the first semi-axis of the fitted ellipse, in degrees


Member of the class EdgeEllipse - Fit

Property int EdgeEllipse::NumDetectedPoints: number of points detected along the edge


Member of the class EdgeEllipse - Fit

Property double EdgeEllipse::Deviation: average distance between the fitted ellipse and the measured points, in pixels; can be used as an ellipticity criterion


Member of the class EdgeEllipse - Fit

Property int EdgeEllipse::NumFittedPoints: number of detected points used for the fitting, after outlier rejection


Member of the class EdgeEllipse - Fit

Property double EdgeEllipse::RobustDeviation: average distance between the fitted circle and the measured points, in pixels, after outlier rejection


Member of the class EdgeEllipse - Fit

Method EdgeEllipse::Realign: moves the gauge so that the reference arc overlaps the fitted arc

void Realign();


Member of the class EdgeEllipse - Storage

Method EdgeEllipse::Read: load the edge arc parameters from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .ede extension recommended

Method EdgeEllipse::Read: load the edge arc parameters from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .ede extension recommended


Member of the class EdgeEllipse - Storage

Method EdgeEllipse::Write: save the edge arc parameters to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .ede extension recommended

Method EdgeEllipse::Write: save the edge arc parameters to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .ede extension recommended


Member of the class EdgeEllipse - Graphics

Method EdgeEllipse::Draw: renders the gauge in the current drawing window

void Draw(bool Handles = false, bool Points = false);

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too

Method EdgeEllipse::Draw: renders the gauge in the current drawing window, with calibration

void Draw(const Geometry& Calibrator, bool Handles = false, bool Points = false);

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too


Member of the class EdgeEllipse - Graphics

Method EdgeEllipse::HitHandle: returns the dragging handle under the cursor, or NoHandle

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: identity of the handle/anchor that was hit, as defined by enum DraggingHandles

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class EdgeEllipse - Graphics

Property DraggingHandles EdgeEllipse::Handle: identity of the last dragging handle hit


Member of the class EdgeEllipse - Graphics

Property int EdgeEllipse::HandleOctant(): hint for the choice of the cursor shape when a handle has been hit


Member of the class EdgeEllipse - Graphics

Method EdgeEllipse::Drag: move the current dragging handle

void Drag(int CursorX, int CursorY);

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Class EdgeRectangle

Creates a void EdgeRectangle object

Constructor EdgeRectangle: creates a void EdgeRectangle object

Location

Method Locate: moves the gauge to the desired location

Property Angle: orientation angle of the width side of the gauge, from horizontal, clockwise

Property Size: width and height of the rectangular gauge

Property Width: width of the sampled region, in pixels

Measurement

Property Density: spacing of the sampling profiles, in pixels

Property Clearance: empty space at the line endpoints where sampling is avoided (in the vicinity of corners)

Property Oblique: when true, the image is sampled perpendicularly to the reference line; otherwise only sampling is made horizontally or vertically to avoid interpolation

Property FourSides: when true, all four sides are fitted, to measure a rectangle; when false only two parallel sides are fitted, to measure a thickness

Property Fitting: select among the fitting options as defined by enum FittingSide; FittingOver by default

Method Detect: locate the edges near the reference rectangle

Property NumSamples: total number of profiles to be sampled

Property SampleIndex: All for normal operation, as by default, or index in the range 0..NumSamples-1 to evaluate a single sample, before a FittedPoint query

Method FittedPoint: accessor to the coordinates of the last detected edge points as selected by SampleIndex

Fit

Property FittedMiddle: coordinates of the middle (symmetry center) of the fitted rectangle

Property FittedSize: width/height of the fitted rectangle

Property FittedAngle: rotation angle of the fitted rectangle

Property Deviation: average distance between the fitted rectangle and the measured points, in pixels; can be used as a rectangularity criterion

Property RobustDeviation: average distance between the fitted rectangle and the measured points, in pixels, after outlier rejection

Method NumDetectedPoints: number of points detected along the edges; per side

Method NumFittedPoints: number of detected points used for the fitting, after outlier rejection; per side

Method Realign: moves the gauge so that the reference rectangle overlaps the fitted rectangle

Storage

Method Read: load the edge rectangle parameters from a file (ASCII or UNICODE path and name)

Method Write: save the edge rectangle parameters to a file (ASCII or UNICODE path and name)

Graphics

Method Draw: renders the gauge in the current drawing window

Method HitHandle: returns the dragging handle under the cursor, or NoHandle

Property Handle: identity of the last hit dragging handle

Property HandleOctant: hint for the choice of the cursor shape when a handle has been hit

Method Drag: move the current dragging handle


Member of the class EdgeRectangle

Constructor EdgeRectangle::EdgeRectangle: creates a void EdgeRectangle object

EdgeRectangle();


Member of the class EdgeRectangle - Location

Method EdgeRectangle::Locate: moves the gauge to the desired location

void Locate(XY& Middle, XY& Size, double Angle, double Width = 32);

XY& Middle: coordinates of the gauge middle (symmetry center)

XY& Size: width and height of the rectangular gauge

double Angle: orientation angle of the width side of the gauge, from horizontal, clockwise

double Width: width of the sampled region, in pixels


Member of the class EdgeRectangle - Location

Property double EdgeRectangle::Angle: orientation angle of the width side of the gauge, from horizontal, clockwise


Member of the class EdgeRectangle - Location

Property XY EdgeRectangle::Size(): width and height of the rectangular gauge


Member of the class EdgeRectangle - Location

Property double EdgeRectangle::Width: width of the sampled region, in pixels


Member of the class EdgeRectangle - Measurement

Property double EdgeRectangle::Density: spacing of the sampling profiles, in pixels


Member of the class EdgeRectangle - Measurement

Property double EdgeRectangle::Clearance: empty space at the line endpoints where sampling is avoided (in the vicinity of corners)


Member of the class EdgeRectangle - Measurement

Property bool EdgeRectangle::Oblique: when true, the image is sampled perpendicularly to the reference line; otherwise only sampling is made horizontally or vertically to avoid interpolation


Member of the class EdgeRectangle - Measurement

Property bool EdgeRectangle::FourSides: when true, all four sides are fitted, to measure a rectangle; when false only two parallel sides are fitted, to measure a thickness


Member of the class EdgeRectangle - Measurement

Property FittingSide EdgeRectangle::Fitting: select among the fitting options as defined by enum FittingSide; FittingOver by default


Member of the class EdgeRectangle - Measurement

Method EdgeRectangle::Detect: locate the edges near the reference rectangle

bool Detect(const Image& Src, int EdgeIndex = BestStep);

returned bool: true if the detection succeeded (can fail because of too few points available)

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

EdgeSelection EdgeIndex: one of BestStep, BestSlope, BestSpan or zero-based positive/negative index (from begin/end)

Method EdgeRectangle::Detect: locate the edges near the reference rectangle

bool Detect(const Image& Src, const Geometry& Calibrator, int EdgeIndex = BestStep);

returned bool: true if the detection succeeded (can fail because of too few points available)

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

EdgeSelection EdgeIndex: one of BestStep, BestSlope, BestSpan or zero-based positive/negative index (from begin/end)


Member of the class EdgeRectangle - Measurement

Property int EdgeRectangle::NumSamples: total number of profiles to be sampled


Member of the class EdgeRectangle - Measurement

Property BlobSelection EdgeRectangle::SampleIndex: All for normal operation, as by default, or index in the range 0..NumSamples-1 to evaluate a single sample, before a FittedPoint query


Member of the class EdgeRectangle - Measurement

Method EdgeRectangle::FittedPoint: accessor to the coordinates of the last detected edge points as selected by SampleIndex

XY FittedPoint(int Index, Polarities Polarity = Both);

returned XY: (X, Y) point coordinates

int Index: index of the desired point, in range [-NumPoints..NumPoints-1], or one of BestSlope, BestStep (default) or BestSpan

Polarities Polarity: desired polarity filter, one of Raising, Falling or Both


Member of the class EdgeRectangle - Fit

Property XY EdgeRectangle::FittedMiddle: coordinates of the middle (symmetry center) of the fitted rectangle


Member of the class EdgeRectangle - Fit

Property XY EdgeRectangle::FittedSize: width/height of the fitted rectangle


Member of the class EdgeRectangle - Fit

Property double EdgeRectangle::FittedAngle: rotation angle of the fitted rectangle


Member of the class EdgeRectangle - Fit

Property double EdgeRectangle::Deviation: average distance between the fitted rectangle and the measured points, in pixels; can be used as a rectangularity criterion


Member of the class EdgeRectangle - Fit

Property double EdgeRectangle::RobustDeviation: average distance between the fitted rectangle and the measured points, in pixels, after outlier rejection


Member of the class EdgeRectangle - Fit

Method EdgeRectangle::NumDetectedPoints: number of points detected along the edges; per side

int NumDetectedPoints(int Side);

returned int: number of points

int Side: rectangle side index, in range [0..3]


Member of the class EdgeRectangle - Fit

Method EdgeRectangle::NumFittedPoints: number of detected points used for the fitting, after outlier rejection; per side

int NumFittedPoints(int Side);

returned int: number of points

int Side: rectangle side index, in range [0..3]


Member of the class EdgeRectangle - Fit

Method EdgeRectangle::Realign: moves the gauge so that the reference rectangle overlaps the fitted rectangle

void Realign();


Member of the class EdgeRectangle - Storage

Method EdgeRectangle::Read: load the edge rectangle parameters from a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .edr extension recommended

Method EdgeRectangle::Read: load the edge rectangle parameters from a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .edr extension recommended


Member of the class EdgeRectangle - Storage

Method EdgeRectangle::Write: save the edge rectangle parameters to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .edr extension recommended

Method EdgeRectangle::Write: save the edge rectangle parameters to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .edr extension recommended


Member of the class EdgeRectangle - Graphics

Method EdgeRectangle::Draw: renders the gauge in the current drawing window

void Draw(bool Handles = false, bool Points = false);

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too

Method EdgeRectangle::Draw: renders the gauge in the current drawing window

void Draw(const Geometry& Calibrator, bool Handles = false, bool Points = false);

Geometry& Calibrator: Geometry object that has been setup with a model, for direct calibration

bool Handles: when true, the dragging handles are drawn too

bool Points: when true, the detected points are drawn too


Member of the class EdgeRectangle - Graphics

Method EdgeRectangle::HitHandle: returns the dragging handle under the cursor, or NoHandle

enum DraggingHandles HitHandle(double CursorX, double CursorY);

returned DraggingHandles: identity of the dragging handle, or NoHandle

double CursorX: mouse cursor abscissa, in pixels

double CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class EdgeRectangle - Graphics

Property DraggingHandles EdgeRectangle::Handle: identity of the last hit dragging handle


Member of the class EdgeRectangle - Graphics

Property int EdgeRectangle::HandleOctant(): hint for the choice of the cursor shape when a handle has been hit


Member of the class EdgeRectangle - Graphics

Method EdgeRectangle::Drag: move the current dragging handle

void Drag(double CursorX, double CursorY, int SrcWidth = 0, int SrcHeight = 0);

double CursorX: mouse cursor abscissa, in pixels

double CursorY: mouse cursor ordinate, in pixels, top-down

int SrcWidth: number of pixels in the source image, horizontally

int SrcHeight: number of pixels in the source image, vertically

Method EdgeRectangle::Drag: move the current dragging handle

void Drag(double CursorX, double CursorY, Image& Src);

double CursorX: mouse cursor abscissa, in pixels

double CursorY: mouse cursor ordinate, in pixels, top-down

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Struct Pose

Location information for a template instance

Pose Information

Property X: anchor abscissa

Property Y: anchor ordinate

Property Angle: rotation angle

Property Scale: scaling factor

Matching Score

Property Score: matching score

Property Contrast: ratio of the instance contrast over the template contrast; values belon one for dark instances, and above for light instances


Member of the class Pose - Pose Information

Property double Pose::X: anchor abscissa


Member of the class Pose - Pose Information

Property double Pose::Y: anchor ordinate


Member of the class Pose - Pose Information

Property double Pose::Angle: rotation angle


Member of the class Pose - Pose Information

Property double Pose::Scale: scaling factor


Member of the class Pose - Matching Score

Property double Pose::Score: matching score


Member of the class Pose - Matching Score

Property double Pose::Contrast: ratio of the instance contrast over the template contrast; values belon one for dark instances, and above for light instances


Class Locator

Template matching to accurately locate instances of a pre-recorded sub-image in another image

Constructor Locator: creates a void Locator object

Training

Method Train: show a template image to the locator to let it find matching features

Property MaxAreaDepths: maximum height of the search pyramid in the area mode; this is an advanced feature

Property MaxEdgesDepths: maximum height of the search pyramid in the edge mode; this is an advanced feature

Method TemplateImage: retrieve the image that was used for training

Method MaskImage: retrieve the mask that was used for training

Method SearchMaskImage: retrieve the mask that was used for searching

Searching

Property MaxLocations: maximum number of template instances to be returned; the ones with the highest scores are preserved

Property MinScore: score threshold to accept a template instance

Property MinContrast: minimum instance contrast, used to reject false instance

Property MinAngle: lower bound of the rotation search range

Property MaxAngle: upper bound of the rotation search range

Property MinScale: lower bound of the scaling search range (avoid smaller then 0.70)

Property MaxScale: upper bound of the scaling search range (avoid larger than 1.40)

Property Edges: true to search in the edge mode (i.e. geometric matching); false for the area mode (i.e. normalized grayscale correlation)

Property Symmetry: informs the locator of the degree of symmetry of the template; 1 for asymmetric, 2 for 180 degrees symmetry, 4 for 90 degrees

Property MaxOverlap: sets an allowance for the instance to overlap; value in [0..1] (no overlap to complete overlap); exceeding 0.5 is not recommended

Property MaxDepths: limit imposed on the number of pyramid levels to be used; setting a low value will improve the robustness at the expense of a longer running time

Property StopDepth: depth where the search will end; values larger than 0 result in faster but less accurate searches; this is an advanced feature

Method Find: look for instances of the template in the given image

Method SearchMask: specifies a mask to restrict the search area

Property NumLocations: number of valid template instances that were found

Found Locations

Method Clear: drop all instances detected at the last Find

Method Location: gives access to the pose information of the template instance with the given index

Method Register: maps a point at given coordinates at search time to the corresponding one at training time, or conversely

Normalization

Storage

Method Read: get the template and search parameter from a locator model file (ASCII filename)

Method Write: store the template and the search parameters to a locator model file for later use (ASCII filename)

Graphics

Method Draw: draw the template occurrences that were found

Method DrawModel: draw a graphical representation of the model, in the training pose

Method Corners: compute the corner coordinates of a given found instance

Method EdgePoints: returns the points along the edges for a given location

Method HitHandle: tells if a template instance is under the cursor

Property Handle: identity of the last dragging handle hit

Property LocationIndex: index of the template instance that was last hit


Member of the class Locator

Constructor Locator::Locator: creates a void Locator object

Locator();


Member of the class Locator - Training

Method Locator::Train: show a template image to the locator to let it find matching features

void Train(const Image& Src, bool Disk = false);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool Disk: when true, training is made from a circular area centered on the window; otherwise, as by default, the whole window is used

Method Locator::Train: show a template image to the locator to let it find matching features; areas outside the region are defined as don't care

void Train(const Image& Mask, const Image& Src, bool EdgeMask = false);

Image& Mask: the mask allows defining templates of an arbitrary shape; only the white pixels in the mask are used, the black ones are don't care

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool EdgeMask: when true, the mask image is used as the edge map in the Edges mode, instead of the one which is build from the Src image

Method Locator::Train: show a template image to the locator to let it find matching features

void Train(const Region& Mask, const Image& Src, bool SrcWindow = false);

Region& Mask: the mask allows defining templates of an arbitrary shape; only the white pixels in the mask are used, the black ones are don't care

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

bool SrcWindow: when true, the origin of the training Region is taken to be the origin of the image Window; when false it is taken to be the origin of the whole image


Member of the class Locator - Training

Property int Locator::MaxAreaDepths: maximum height of the search pyramid in the area mode; this is an advanced feature


Member of the class Locator - Training

Property int Locator::MaxEdgesDepths: maximum height of the search pyramid in the edge mode; this is an advanced feature


Member of the class Locator - Training

Method Locator::TemplateImage: retrieve the image that was used for training

const Image& TemplateImage();

returned Image&: a read-only Image object containing the template


Member of the class Locator - Training

Method Locator::MaskImage: retrieve the mask that was used for training

const Image& MaskImage();

returned Image&: a read-ony Image object containing the mask


Member of the class Locator - Training

Method Locator::SearchMaskImage: retrieve the mask that was used for searching

const Image& SearchMaskImage();

returned Image&: the mask image


Member of the class Locator - Searching

Property int Locator::MaxLocations: maximum number of template instances to be returned; the ones with the highest scores are preserved


Member of the class Locator - Searching

Property double Locator::MinScore: score threshold to accept a template instance


Member of the class Locator - Searching

Property double Locator::MinContrast: minimum instance contrast, used to reject false instance


Member of the class Locator - Searching

Property double Locator::MinAngle: lower bound of the rotation search range


Member of the class Locator - Searching

Property double Locator::MaxAngle: upper bound of the rotation search range


Member of the class Locator - Searching

Property double Locator::MinScale: lower bound of the scaling search range (avoid smaller then 0.70)


Member of the class Locator - Searching

Property double Locator::MaxScale: upper bound of the scaling search range (avoid larger than 1.40)


Member of the class Locator - Searching

Property bool Locator::Edges: true to search in the edge mode (i.e. geometric matching); false for the area mode (i.e. normalized grayscale correlation)


Member of the class Locator - Searching

Property int Locator::Symmetry: informs the locator of the degree of symmetry of the template; 1 for asymmetric, 2 for 180 degrees symmetry, 4 for 90 degrees


Member of the class Locator - Searching

Property double Locator::MaxOverlap: sets an allowance for the instance to overlap; value in [0..1] (no overlap to complete overlap); exceeding 0.5 is not recommended


Member of the class Locator - Searching

Property int Locator::MaxDepths: limit imposed on the number of pyramid levels to be used; setting a low value will improve the robustness at the expense of a longer running time


Member of the class Locator - Searching

Property int Locator::StopDepth: depth where the search will end; values larger than 0 result in faster but less accurate searches; this is an advanced feature


Member of the class Locator - Searching

Method Locator::Find: look for instances of the template in the given image

void Find(const Image& Src);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst


Member of the class Locator - Searching

Method Locator::SearchMask: specifies a mask to restrict the search area

void SearchMask(const Image& Mask);

Image& Mask: mask image or region

Method Locator::SearchMask: specifies a mask to restrict the search area

void SearchMask(const Region& Mask, const Image& Src, bool SrcWindow = false);

Region& Mask: mask image or region

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool SrcWindow: when true, the origin of the training Region is taken to be the origin of the image Window; when false it is taken to be the origin of the whole image

Method Locator::SearchMask: resets the search mask, as by default; the whole image will be processed

void SearchMask();


Member of the class Locator - Searching

Property int Locator::NumLocations: number of valid template instances that were found


Member of the class Locator - Found Locations

Method Locator::Clear: drop all instances detected at the last Find

void Clear();


Member of the class Locator - Found Locations

Method Locator::Location: gives access to the pose information of the template instance with the given index

Pose& Location(int LocationIndex, int Depth = -1);

returned Pose&: the pose information for this instance

int LocationIndex: zero-based index value in range [0..NumLocations-1]

int Depth: pyramid level to which the location relates; use 0 for full resolution; by default, the StopDepth

Method Locator::Location: gives access to the pose information of the template instance with the given index

Pose& Location(const Geometry& Calibrator, int LocationIndex, int Depth = -1);

returned Pose&: the pose information for this instance

Geometry& Calibrator: geometry object used for calibration (if absent, simple calibration is used)

int LocationIndex: zero-based index value in range [0..NumLocations-1]

int Depth: pyramid level to which the location relates; use 0 for full resolution; by default, the StopDepth


Member of the class Locator - Found Locations

Method Locator::Register: maps a point at given coordinates at search time to the corresponding one at training time, or conversely

XY Register(XY P, int LocationIndex = 0, bool Reverse = false, bool TrainedWindow = true);

returned XY: the transformed point

XY P: the point to be transformed

int LocationIndex: zero-based index value in range [0..NumLocations-1]

bool Reverse: when false, as by default, the function maps the point of the searching image to the training image; otherwise, the inverse mapping is applied

bool TrainedWindow: when true, as by default, the training coordinates are relative to the training window instead of the whole training image

Method Locator::Register: maps the image of an instance to the reference position (at training time) so that they can be overlapped

void Register(int LocationIndex, const Image& Src, Image& Dst, bool Interpolate = true);

int LocationIndex: zero-based index value in range [0..NumLocations-1]

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class Locator - Storage

Method Locator::Read: get the template and search parameter from a locator model file (ASCII filename)

void Read(const char* PathName);

char* PathName: file path and name as an ASCII or UNICODE character string; .loc extension recommended

Method Locator::Read: get the template and search parameter from a locator model file (UNICODE filename)

void Read(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string; .loc extension recommended


Member of the class Locator - Storage

Method Locator::Write: store the template and the search parameters to a locator model file for later use (ASCII filename)

void Write(const char* PathName);

char* PathName: file path and name as an ASCII or UNICODE character string; .loc extension recommended

Method Locator::Write: store the template and the search parameters to a locator model file for later use (UNICODE filename)

void Write(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string; .loc extension recommended


Member of the class Locator - Graphics

Method Locator::Draw: draw the template occurrences that were found

void Draw(bool Scores = false, double MinScore = -1, int Depth = -1);

bool Scores: when true, the score value is displayed at the top left corner of each instance

double MinScore: instances with a score above MinScore are drawn in green and in red below

int Depth: pyramid level to be displayed; use 0 for full resolution; by default, the StopDepth

Method Locator::Draw: draw the template occurrences that were found

void Draw(bool Scores, bool Contrasts, double MinScore = -1, int Depth = -1);

bool Scores: when true, the score value is displayed at the top left corner of each instance

bool Contrasts: when true, the numerical value of the contrast is displayed at the top left corner of each instance

double MinScore: instances with a score above MinScore are drawn in green and in red below

int Depth: pyramid level to be displayed; use 0 for full resolution; by default, the StopDepth


Member of the class Locator - Graphics

Method Locator::DrawModel: draw a graphical representation of the model, in the training pose

void DrawModel();


Member of the class Locator - Graphics

Method Locator::Corners: compute the corner coordinates of a given found instance

void Corners(int LocationIndex, Poly& Outline);

int LocationIndex: zero-based index value in range [0..NumLocations-1]

Poly& Outline: Path object that receives the coordinates of the four corners


Member of the class Locator - Graphics

Method Locator::EdgePoints: returns the points along the edges for a given location

void EdgePoints(int LocationIndex, Path& Dst);

int LocationIndex: zero-based index value in range [0..NumLocations-1]

Path& Dst: Path object holding the point coordinates


Member of the class Locator - Graphics

Method Locator::HitHandle: tells if a template instance is under the cursor

enum DraggingHandles HitHandle(int CursorX, int CursorY);

returned DraggingHandles: one of AllHandle, over a template instance, or NoHandle

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class Locator - Graphics

Property DraggingHandles Locator::Handle: identity of the last dragging handle hit


Member of the class Locator - Graphics

Property int Locator::LocationIndex: index of the template instance that was last hit


Struct HTable

Reserved for internal use

Property A: Reserved for internal use; angle

Property V: Reserved for internal use; displacement


Member of the class HTable

Property short HTable::A: Reserved for internal use; angle


Member of the class HTable

Property Site HTable::V: Reserved for internal use; displacement


Class ShapeMatcher

Template matching engine able to learn several blob shapes and recognize/locate other blobs

Constructor ShapeMatcher: creates a void ShapeMatcher object

Training

Method Train: let the Finder learn the shape of a given outline and remember its type, represented by a class index

Method TrainBlob: let the Finder learn the shape of a given blob and remember its type, represented by a class index

Property NumTrained: number of blobs trained so far

Method Clear: forget the training

Recognition

Property MaxSimilarity: maximum matching similarity score; above this value, matches are considered irrelevant

Property MinAngle: minmum rotation angle

Property MaxAngle: maximum rotation angle

Property MinScale: minimum scale

Property MaxScale: maximum scale

Method Recognize: identify the type of a shape given as an outline by comparison to the trained samples

Method RecognizeBlobs: identify the type of one or more shapes given as blobs by comparison to the trained samples

Property Location: pose of the recognized template shape, as returned by Recognize

Property Class: class index of the recognized template shape

Storage

Method Read: load the trained blob set from a file (ASCII path and name)

Method Write: save the trained blob set to a file (ASCII path and name)

Graphics

Method DrawTrained: draws the shapes that have participated in the training

Method DrawMatched: overlap a shape with the outline of the matched template

Method HitTrained: detects over which shape the cursor is

Property HitIndex: index of the last shape that was hit

Method DeleteHit: removes the last shape that was hit by a call to HitTrained


Member of the class ShapeMatcher

Constructor ShapeMatcher::ShapeMatcher: creates a void ShapeMatcher object

ShapeMatcher();


Member of the class ShapeMatcher - Training

Method ShapeMatcher::Train: let the Finder learn the shape of a given outline and remember its type, represented by a class index

void Train(const Image& EdgeMap, int ClassIndex, int Symmetry = 1);

Image& EdgeMap: train on an edge map; reserved use

int ClassIndex: class index to assign this blob/edge pattern

int Symmetry: order of the symmetry of the shape (1: asymmetric, 2: rectangle symmetric, 4: square symmetry...)

Method ShapeMatcher::Train: let the Finder learn the shape of a given outline and remember its type, represented by a class index

void Train(const Path& Outline, int ClassIndex, int Symmetry = 1);

Path& Outline: outline of the shape to be recognized

int ClassIndex: class index to assign this blob/edge pattern

int Symmetry: order of the symmetry of the shape (1: asymmetric, 2: rectangle symmetric, 4: square symmetry...)


Member of the class ShapeMatcher - Training

Method ShapeMatcher::TrainBlob: let the Finder learn the shape of a given blob and remember its type, represented by a class index

void TrainBlob(const Blobs& Src, int BlobIndex, int ClassIndex, int Symmetry = 1);

Blobs& Src: blob analysis context that provides the shape

int BlobIndex: zero-based index of the blob to train on, in range [0..NumBlobs-1]

int ClassIndex: class index to assign this blob

int Symmetry: order of the symmetry of the shape (1: asymmetric, 2: rectangle symmetric, 4: square symmetry...)


Member of the class ShapeMatcher - Training

Property int ShapeMatcher::NumTrained: number of blobs trained so far


Member of the class ShapeMatcher - Training

Method ShapeMatcher::Clear: forget the training

void Clear();


Member of the class ShapeMatcher - Recognition

Property double ShapeMatcher::MaxSimilarity: maximum matching similarity score; above this value, matches are considered irrelevant


Member of the class ShapeMatcher - Recognition

Property double ShapeMatcher::MinAngle: minmum rotation angle


Member of the class ShapeMatcher - Recognition

Property double ShapeMatcher::MaxAngle: maximum rotation angle


Member of the class ShapeMatcher - Recognition

Property double ShapeMatcher::MinScale: minimum scale


Member of the class ShapeMatcher - Recognition

Property double ShapeMatcher::MaxScale: maximum scale


Member of the class ShapeMatcher - Recognition

Method ShapeMatcher::Recognize: identify the type of a shape given as an outline by comparison to the trained samples

int Recognize(Path& Outline);

returned int: index of the recognized template shape, in range [0..NumTrained-1]

Path& Outline: outline of the subject shape


Member of the class ShapeMatcher - Recognition

Method ShapeMatcher::RecognizeBlobs: identify the type of one or more shapes given as blobs by comparison to the trained samples

void RecognizeBlobs(Blobs& Src, int BlobIndex = AllSelected);

Blobs& Src: blob analysis context that provides the shapes

BlobSelection BlobIndex: zero-based index of the blob(s) to be recognized in range [0..NumBlobs-1] or one of All, AllSelected, AllDeselected


Member of the class ShapeMatcher - Recognition

Property Pose ShapeMatcher::Location: pose of the recognized template shape, as returned by Recognize


Member of the class ShapeMatcher - Recognition

Property int ShapeMatcher::Class: class index of the recognized template shape


Member of the class ShapeMatcher - Storage

Method ShapeMatcher::Read: load the trained blob set from a file (ASCII path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .shm extension recommended

Method ShapeMatcher::Read: load the trained blob set from a file (UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .shm extension recommended


Member of the class ShapeMatcher - Storage

Method ShapeMatcher::Write: save the trained blob set to a file (ASCII path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .shm extension recommended

Method ShapeMatcher::Write: save the trained blob set to a file (UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .shm extension recommended


Member of the class ShapeMatcher - Graphics

Method ShapeMatcher::DrawTrained: draws the shapes that have participated in the training

void DrawTrained(Limits& PlotArea, int ShapeIndex = All, bool ClassLabel = false, bool Normalized = false);

Limits& PlotArea: limits of the area where the trained shapes are displayed

BlobSelection ShapeIndex: index of the recognized template shape, in range [0..NumTrained-1]

bool ClassLabel: when true, the learnt shapes are annotated with the corresponding class index

bool Normalized: when true, the shapes are shown with a standardized size


Member of the class ShapeMatcher - Graphics

Method ShapeMatcher::DrawMatched: overlap a shape with the outline of the matched template

void DrawMatched(bool ClassLabel = false, bool Similarity = false);

bool ClassLabel: when true, the class index is shown next to the outline

bool Similarity: when true, the similarity score is displayed in the label


Member of the class ShapeMatcher - Graphics

Method ShapeMatcher::HitTrained: detects over which shape the cursor is

int HitTrained(Limits& PlotArea, int CursorX, int CursorY, bool Normalized = false);

returned int: shape index

Limits& PlotArea: limits of the area where the trained shapes are displayed

int CursorX: abscissa of the cursor, in pixels

int CursorY: ordinate of the cursor, in pixels

bool Normalized: when true, the shapes are shown with a standardized size; use the same setting as for DrawTrained


Member of the class ShapeMatcher - Graphics

Property int ShapeMatcher::HitIndex: index of the last shape that was hit


Member of the class ShapeMatcher - Graphics

Method ShapeMatcher::DeleteHit: removes the last shape that was hit by a call to HitTrained

void DeleteHit();


Struct Pose3

Description of an object pose in 3D, by means of a rotation and a translation

Coordinate transformation

Property XForm[4]: pose transformation; rotation and translation

Matching assessment

Property InlierDistanceMean: mean distance between the template and the matched subject, for inliers only; large value indicates a bad match

Property InlierDistanceDeviation: mean distance between the template and the matched subject, for inliers only; large value may reveal more outliers

Property DistanceMean: mean distance between the template and the matched subject; small value indicates a good match

Property DistanceDeviation: standard deviation of the distance between the template and the matched subject; large value confirm the presence of outliers

Method _lt: TBD


Member of the class Pose3 - Coordinate transformation

Property dXYZ Pose3::XForm[4]: pose transformation; rotation and translation


Member of the class Pose3 - Matching assessment

Property double Pose3::InlierDistanceMean: mean distance between the template and the matched subject, for inliers only; large value indicates a bad match


Member of the class Pose3 - Matching assessment

Property double Pose3::InlierDistanceDeviation: mean distance between the template and the matched subject, for inliers only; large value may reveal more outliers


Member of the class Pose3 - Matching assessment

Property double Pose3::DistanceMean: mean distance between the template and the matched subject; small value indicates a good match


Member of the class Pose3 - Matching assessment

Property double Pose3::DistanceDeviation: standard deviation of the distance between the template and the matched subject; large value confirm the presence of outliers


Member of the class Pose3 - Matching assessment

Method Pose3::_lt: TBD

bool operator<(const Pose3 P);

returned bool: TBD

Pose3 P: TBD


Struct FontCharImage

Trained character descriptor

Character Descriptor

Property Code: the ASCII or UNICODE character value

Property Class: a used-defined value

Correlation Moments

Property WhiteOnBlack: character contrast

Property M: zero-th order character moment; reserved for internal use

Property MP: first order character moment; reserved for internal use

Property MPP: second order character moment; reserved for internal use

Property NPP: reserved for internal use

Property M2: reserved for internal use

Property MP2: reserved for internal use

Property NPP2: reserved for internal use

Property M4: reserved for internal use

Property MP4: reserved for internal use

Property NPP4: reserved for internal use

Property SafeScore: the score under which recognition is deemed unreliable

Thumbnails

Property Raw: the original character image

Property Fixed: the size-normalized character image

Property Fixed2: reserved for internal use

Property Fixed4: reserved for internal use

Stroke width template

Property SWT: reserved for character quality verification


Member of the class FontCharImage - Character Descriptor

Property wchar_t FontCharImage::Code: the ASCII or UNICODE character value


Member of the class FontCharImage - Character Descriptor

Property int FontCharImage::Class: a used-defined value


Member of the class FontCharImage - Correlation Moments

Property bool FontCharImage::WhiteOnBlack: character contrast


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::M: zero-th order character moment; reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::MP: first order character moment; reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::MPP: second order character moment; reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::NPP: reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::M2: reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::MP2: reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::NPP2: reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::M4: reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::MP4: reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::NPP4: reserved for internal use


Member of the class FontCharImage - Correlation Moments

Property double FontCharImage::SafeScore: the score under which recognition is deemed unreliable


Member of the class FontCharImage - Thumbnails

Property Image FontCharImage::Raw: the original character image


Member of the class FontCharImage - Thumbnails

Property Image FontCharImage::Fixed: the size-normalized character image


Member of the class FontCharImage - Thumbnails

Property Image FontCharImage::Fixed2: reserved for internal use


Member of the class FontCharImage - Thumbnails

Property Image FontCharImage::Fixed4: reserved for internal use


Member of the class FontCharImage - Stroke width template

Property Image FontCharImage::SWT: reserved for character quality verification


Enumeration

Enum LayoutModes: different ways to locate the characters to be inspected

Case NoLayout: character location does not use a pre-trained model

Case RigidLayout: character location is done by comparing to the pre-trained model with no deformation allowance

Case FlexibleLayout: character location is done by comparing to the pre-trained model with allowance of individual character moves


Class CharReader

OCR engine for part identification

Constructor CharReader: creates a void CharReader object

Destructor ~CharReader: Destructor

Character Segmentation

Method CharsSegment: isolate and arrange the characters in the given image

Property Quadrant: rotation angle of the text, expressed as a number of quarter turns from horizontal

Property LocalThreshold: use a local, adaptive threshold instead of a global one; use in case of uneven illumination

Property Threshold: binarization threshold used for code detection when AdaptiveThreshold is false; by default Auto, which causes automatic adjustment; manual use is discouraged

Property WhiteOnBlack: character contrast

Property CharWidth: estimate of the character width used for character segmentation

Property CharHeight: estimate of the character height used for character segmentation

Property GuessSize: when true, try and determine the character size automatically from the image content; otherwise, use CharWidth and CharHeight

Property KeepRatio: when true, the original aspect ratio (CharHeight/CharWidth) is retained; otherwise, CharWidth and CharHeight are both freely adapted

Property RepairBroken: when true, as by default, an attempt is made to group character pieces

Property Dotted: to improve the connectivity of dot printed characters, increase this value

Property InkingCorrection: if the thickness of the strokes differs from that at training time, allows a positive or negative thickness adjustment; only use knowingly

Property Masking: special mode of segmentation meant to cleanup the background; 0 disables it

Property AlignChars: when true, horizontal character alignment is enforced

Property EvenlySpaceChars: when true, equal character spacing is enforced

Property MaxTouching: the maximum number of characters that can touch each other; 5 by default; when 1 is specified, no attempt is made to separate touching characters

Property SplitRows: special mode of operation menat to split touching lines; set the exact number of text lines; 0 disables it

Property VariableWidth: when true, the width of the characters is taken into account instead of being kept fixed

Property GapFraction: relative size of the spacing between characters character; 0.1 by default, i.e. 10% of the normal character width

Property DotFraction: relative size of the smallest blob accepted as a character; 0.5 by default, i.e. 50% of the normal character width and height

Property NumChars: number of characters found during segmentation

Method Separator: returns the separator (gap or line jump) that precedes the character at the given index, if any

Method PresetCharBoxes: creates a user-defined set of character boxes

Method PresetCharBox: sets the coordinates (top-left corner, size) of a given box

Training

Method FontChar: index of the segmented character that was last hit

Property FontWidth: width of the normalized characters used in the recognition process

Property FontHeight: height of the normalized characters used in the recognition process

Method FontCharInsert: add an ASCII character to the font by providing a sample image

Method FontStringInsert: add ASCII characters to the font after segmentation of the characters from an image

Method FontCharDelete: remove the given character from the trained font

Property NumFontChars: number of characters in the trained font

Method LayoutTrain: learn the geometry of the text string to be read or verified

Method LayoutReset: forget the geometry of the text string to be read or verified

Property NumLayoutChars: total number of characters in the defined layout

Property NumLayoutStrings: number of character string sections in the current template

Method Optimize: in the case of training with numerous samples of each character, reduces the training set to a sufficient minimum, for speed

Reading

Method CharsDecode: read a character string from an image after segmentation, by comparison to the trained font

Method CharsRead: segment and read a character string from an image, by comparison to the trained font

Property MinimumScore: score threshold under which a character is deemed misrecognized or misprinted

Property MinimumContrast: characters such that the ratio of their contrast and the contrast at train time is lower than this threshold are ignored; by default, 10%

Property UseSafeScores: automatically determine a minimum score for each character in the font based on possible confusions

Property DiscardBadScores: characters with a score below the allowed minimum are replaced with a question mark ('?')

Property OCVScoring: by default (false), verbatim characters get a 100% score; when true, comparison with the corresponding trained samples is performed, for quality verification

Property GlobalFilter: global rather than per-character filter; one of u/U/v/V: %uppercase/+digit/+special, l/m/L/M: lowercase/+digit/+special, a/b/A/B: mixed case/+digit/+special, 9/0: digit/+special, *: any, -: ignore, %: %

Method Filter: character specifiers, a string made of specifiers escaped by %; without a %, taken verbatim; e.g. %u-%9%9 is an uppercase followed by a dash and two digits

Property JitterX: horizontal movement allowance used during the recognition process for fine matching; use a small value; by default, no jitter

Property JitterY: vertical movement allowance used during the recognition process for fine matching; use a small value; by default, no jitter

Property AsciiFilter: get the per-character filter as an ASCII string

Property UnicodeFilter: get the per-character filter as a UNICODE string

Property InsertSpaces: when true, as by default, the detected spaces (gaps between characters) are output to the result string

Property InsertNewlines: when true, as by default, the detected new lines (line jumps) are output to the result string

Property MinAngle: minimum rotation angle of the text, in the current angle unit

Property MaxAngle: maximum rotation angle of the text, in the current angle unit

Property AsciiString: result of the reading, an ASCII string of characters

Property UnicodeString: result of the reading, a UNICODE string of characters

Property AverageScore: global matching score for the decoded string

Property AverageContrast: average of the constrasts of the individual characters

Method CharScore: score achieved by the given segmented character

Method CharContrast: returns the measured contrast of this character as compared to the trained character

Method MatchingFontChar: get the index of the font character matching this segmented character

Method CharTrueWidth: returns the actual width of a given character; requires VariableWidth to be true

Property LayoutMode: the character location mode in use, as enumerated in LayoutModes

Storage

Method Read: loads the font description and recognition parameters to initialize the reader from a file (ASCII path and name)

Method Write: saves the font description and recognition parameters for later reuse to a file (ASCII path and name)

Graphics

Method Draw: renders the segmented characters in the current drawing window as a series of boxes

Method GetBoxes: undocumented; reserved

Method DrawLayout: renders the layout of the characters in the current drawing window

Method GetLayoutBoxes: returns the limit coordinates of the layout boxes

Method DrawFontChars: renders the trained characters in the current drawing window

Method HitChar: tells if a segmented character is under the cursor

Property CharIndex: index of the segmented character that was last hit

Method HitFontChar: tells if a font character is under the cursor; pass the same layout parameter as for the call of DrawFontChars

Property Handle: identity of the last dragging handle hit

Property FontCharIndex: index of the font character that was last hit, or -1 if none was

Method CharThumbnail: get a bitmap representation of the given segmented character

Method Dump: Outputs the current parameters of a CharReader


Member of the class CharReader

Constructor CharReader::CharReader: creates a void CharReader object

CharReader();


Member of the class CharReader

Destructor CharReader::~CharReader: Destructor

~CharReader();


Member of the class CharReader - Character Segmentation

Method CharReader::CharsSegment: isolate and arrange the characters in the given image

void CharsSegment(const Image& Src);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb, Rgba


Member of the class CharReader - Character Segmentation

Property int CharReader::Quadrant: rotation angle of the text, expressed as a number of quarter turns from horizontal


Member of the class CharReader - Character Segmentation

Property bool CharReader::LocalThreshold: use a local, adaptive threshold instead of a global one; use in case of uneven illumination


Member of the class CharReader - Character Segmentation

Property int CharReader::Threshold: binarization threshold used for code detection when AdaptiveThreshold is false; by default Auto, which causes automatic adjustment; manual use is discouraged


Member of the class CharReader - Character Segmentation

Property bool CharReader::WhiteOnBlack: character contrast


Member of the class CharReader - Character Segmentation

Property int CharReader::CharWidth: estimate of the character width used for character segmentation


Member of the class CharReader - Character Segmentation

Property int CharReader::CharHeight: estimate of the character height used for character segmentation


Member of the class CharReader - Character Segmentation

Property bool CharReader::GuessSize: when true, try and determine the character size automatically from the image content; otherwise, use CharWidth and CharHeight


Member of the class CharReader - Character Segmentation

Property bool CharReader::KeepRatio: when true, the original aspect ratio (CharHeight/CharWidth) is retained; otherwise, CharWidth and CharHeight are both freely adapted


Member of the class CharReader - Character Segmentation

Property bool CharReader::RepairBroken: when true, as by default, an attempt is made to group character pieces


Member of the class CharReader - Character Segmentation

Property int CharReader::Dotted: to improve the connectivity of dot printed characters, increase this value


Member of the class CharReader - Character Segmentation

Property int CharReader::InkingCorrection: if the thickness of the strokes differs from that at training time, allows a positive or negative thickness adjustment; only use knowingly


Member of the class CharReader - Character Segmentation

Property int CharReader::Masking: special mode of segmentation meant to cleanup the background; 0 disables it


Member of the class CharReader - Character Segmentation

Property bool CharReader::AlignChars: when true, horizontal character alignment is enforced


Member of the class CharReader - Character Segmentation

Property bool CharReader::EvenlySpaceChars: when true, equal character spacing is enforced


Member of the class CharReader - Character Segmentation

Property int CharReader::MaxTouching: the maximum number of characters that can touch each other; 5 by default; when 1 is specified, no attempt is made to separate touching characters


Member of the class CharReader - Character Segmentation

Property int CharReader::SplitRows: special mode of operation menat to split touching lines; set the exact number of text lines; 0 disables it


Member of the class CharReader - Character Segmentation

Property bool CharReader::VariableWidth: when true, the width of the characters is taken into account instead of being kept fixed


Member of the class CharReader - Character Segmentation

Property double CharReader::GapFraction: relative size of the spacing between characters character; 0.1 by default, i.e. 10% of the normal character width


Member of the class CharReader - Character Segmentation

Property double CharReader::DotFraction: relative size of the smallest blob accepted as a character; 0.5 by default, i.e. 50% of the normal character width and height


Member of the class CharReader - Character Segmentation

Property int CharReader::NumChars: number of characters found during segmentation


Member of the class CharReader - Character Segmentation

Method CharReader::Separator: returns the separator (gap or line jump) that precedes the character at the given index, if any

wchar_t Separator(int CharIndex);

returned wchar_t: one of space and newline, or null inside a word

int CharIndex: index of the desired character


Member of the class CharReader - Character Segmentation

Method CharReader::PresetCharBoxes: creates a user-defined set of character boxes

void PresetCharBoxes(int NumBoxes);

int NumBoxes: total number of desired boxes


Member of the class CharReader - Character Segmentation

Method CharReader::PresetCharBox: sets the coordinates (top-left corner, size) of a given box

void PresetCharBox(int Index, int X, int Y, int Width, int Height);

int Index: zero-based index value to access a list of items

int X: upper left point abscissa, in pixels

int Y: upper left point ordinate, in pixels, top-down

int Width: number of pixels, horizontally

int Height: number of pixels, vertically


Member of the class CharReader - Training

Method CharReader::FontChar: index of the segmented character that was last hit

FontCharImage& FontChar(int Index);

returned FontCharImage&: CharImage descriptor

int Index: zero-based index value to access a list of items


Member of the class CharReader - Training

Property int CharReader::FontWidth: width of the normalized characters used in the recognition process


Member of the class CharReader - Training

Property int CharReader::FontHeight: height of the normalized characters used in the recognition process


Member of the class CharReader - Training

Method CharReader::FontCharInsert: add an ASCII character to the font by providing a sample image

void FontCharInsert(const Image& Src, const char Code, int Class = 0, int FontCharIndex = -1);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

char Code: ASCII or UNICODE value associated to the character

int Class: user-defined class information

int FontCharIndex: zero-based index where to insert the character; a negative value, as by default, inserts in the alphabetic order

Method CharReader::FontCharInsert: add a UNICODE character to the font by providing a sample image

void FontCharInsert(const Image& Src, const wchar_t Code, int Class = 0, int FontCharIndex = -1);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

wchar_t Code: ASCII or UNICODE value associated to the character

int Class: user-defined class information

int FontCharIndex: zero-based index where to insert the character; a negative value, as by default, inserts in the alphabetic order


Member of the class CharReader - Training

Method CharReader::FontStringInsert: add ASCII characters to the font after segmentation of the characters from an image

void FontStringInsert(const Image& Src, const char Codes[], int Class = 0, int FontCharIndex = -1);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

char* Codes: null-terminated ASCII or UNICODE string associated to the characters

int Class: user-defined class information

int FontCharIndex: zero-based index where to insert the characters; a negative value, as by default, inserts in the alphabetic order

Method CharReader::FontStringInsert: add UNICODE characters to the font after segmentation of the characters from an image

void FontStringInsert(const Image& Src, const wchar_t Codes[], int Class = 0, int FontCharIndex = -1);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

wchar_t* Codes: null-terminated ASCII or UNICODE string associated to the characters

int Class: user-defined class information

int FontCharIndex: zero-based index where to insert the characters; a negative value, as by default, inserts in the alphabetic order


Member of the class CharReader - Training

Method CharReader::FontCharDelete: remove the given character from the trained font

void FontCharDelete(int FontCharIndex = All);

int FontCharIndex: index of the character in the font, in range [0..NumFontChars - 1], or All


Member of the class CharReader - Training

Property int CharReader::NumFontChars: number of characters in the trained font


Member of the class CharReader - Training

Method CharReader::LayoutTrain: learn the geometry of the text string to be read or verified

void LayoutTrain();


Member of the class CharReader - Training

Method CharReader::LayoutReset: forget the geometry of the text string to be read or verified

void LayoutReset();


Member of the class CharReader - Training

Property int CharReader::NumLayoutChars: total number of characters in the defined layout


Member of the class CharReader - Training

Property int CharReader::NumLayoutStrings: number of character string sections in the current template


Member of the class CharReader - Training

Method CharReader::Optimize: in the case of training with numerous samples of each character, reduces the training set to a sufficient minimum, for speed

void Optimize(bool Enable);

bool Enable: when true, only sufficiently many samples will be used; when false, reverts to the whole training set


Member of the class CharReader - Reading

Method CharReader::CharsDecode: read a character string from an image after segmentation, by comparison to the trained font

void CharsDecode(Image& Src);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst


Member of the class CharReader - Reading

Method CharReader::CharsRead: segment and read a character string from an image, by comparison to the trained font

void CharsRead(Image& Src);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst


Member of the class CharReader - Reading

Property double CharReader::MinimumScore: score threshold under which a character is deemed misrecognized or misprinted


Member of the class CharReader - Reading

Property double CharReader::MinimumContrast: characters such that the ratio of their contrast and the contrast at train time is lower than this threshold are ignored; by default, 10%


Member of the class CharReader - Reading

Property bool CharReader::UseSafeScores: automatically determine a minimum score for each character in the font based on possible confusions


Member of the class CharReader - Reading

Property bool CharReader::DiscardBadScores: characters with a score below the allowed minimum are replaced with a question mark ('?')


Member of the class CharReader - Reading

Property bool CharReader::OCVScoring: by default (false), verbatim characters get a 100% score; when true, comparison with the corresponding trained samples is performed, for quality verification


Member of the class CharReader - Reading

Property wchar_t CharReader::GlobalFilter: global rather than per-character filter; one of u/U/v/V: %uppercase/+digit/+special, l/m/L/M: lowercase/+digit/+special, a/b/A/B: mixed case/+digit/+special, 9/0: digit/+special, *: any, -: ignore, %: %


Member of the class CharReader - Reading

Method CharReader::Filter: character specifiers, a string made of specifiers escaped by %; without a %, taken verbatim; e.g. %u-%9%9 is an uppercase followed by a dash and two digits

void Filter(const char Specifiers[]);

char* Specifiers: u/U/v/V: %uppercase/+digit/+special, l/m/L/M: lowercase/+digit/+special, a/b/A/B: mixed case/+digit/+special, 9/0: digit/+special, *: any, -: ignore, %: %

Method CharReader::Filter: u/U/v/V: uppercase/+special/+digit, l/m/L/M: lowercase/+special/+digit, a/b/A/B: mixed case/+special/+digit, 9/0: digit/+special, *: any, -: ignore, %: %

void Filter(const wchar_t Specifiers[]);

wchar_t* Specifiers: u/U/v/V: %uppercase/+digit/+special, l/m/L/M: lowercase/+digit/+special, a/b/A/B: mixed case/+digit/+special, 9/0: digit/+special, *: any, -: ignore, %: %


Member of the class CharReader - Reading

Property int CharReader::JitterX: horizontal movement allowance used during the recognition process for fine matching; use a small value; by default, no jitter


Member of the class CharReader - Reading

Property int CharReader::JitterY: vertical movement allowance used during the recognition process for fine matching; use a small value; by default, no jitter


Member of the class CharReader - Reading

Property char* CharReader::AsciiFilter: get the per-character filter as an ASCII string


Member of the class CharReader - Reading

Property wchar_t* CharReader::UnicodeFilter: get the per-character filter as a UNICODE string


Member of the class CharReader - Reading

Property bool CharReader::InsertSpaces: when true, as by default, the detected spaces (gaps between characters) are output to the result string


Member of the class CharReader - Reading

Property bool CharReader::InsertNewlines: when true, as by default, the detected new lines (line jumps) are output to the result string


Member of the class CharReader - Reading

Property double CharReader::MinAngle: minimum rotation angle of the text, in the current angle unit


Member of the class CharReader - Reading

Property double CharReader::MaxAngle: maximum rotation angle of the text, in the current angle unit


Member of the class CharReader - Reading

Property char* CharReader::AsciiString: result of the reading, an ASCII string of characters


Member of the class CharReader - Reading

Property wchar_t* CharReader::UnicodeString: result of the reading, a UNICODE string of characters


Member of the class CharReader - Reading

Property double CharReader::AverageScore: global matching score for the decoded string


Member of the class CharReader - Reading

Property double CharReader::AverageContrast: average of the constrasts of the individual characters


Member of the class CharReader - Reading

Method CharReader::CharScore: score achieved by the given segmented character

double CharScore(int CharIndex);

returned double: quality score, in range [-1..+1]

int CharIndex: index of the segmented character, in range [0..NumChars-1]


Member of the class CharReader - Reading

Method CharReader::CharContrast: returns the measured contrast of this character as compared to the trained character

double CharContrast(int CharIndex);

returned double: Contrast value a number close to 1

int CharIndex: index of the segmented character, in range [0..NumChars-1]


Member of the class CharReader - Reading

Method CharReader::MatchingFontChar: get the index of the font character matching this segmented character

int MatchingFontChar(int CharIndex);

returned int: font character index, in range [0..NumFontChars-1]

int CharIndex: index of the segmented character, in range [0..NumChars-1]


Member of the class CharReader - Reading

Method CharReader::CharTrueWidth: returns the actual width of a given character; requires VariableWidth to be true

int CharTrueWidth(int CharIndex);

returned int: width in pixels

int CharIndex: index of the segmented character, in range [0..NumChars-1]


Member of the class CharReader - Reading

Property LayoutModes CharReader::LayoutMode: the character location mode in use, as enumerated in LayoutModes


Member of the class CharReader - Storage

Method CharReader::Read: loads the font description and recognition parameters to initialize the reader from a file (ASCII path and name)

void Read(const char* PathName, bool SettingsOnly = false);

char* PathName: file path and name as an ASCII or UNICODE character string; .fnt extension recommended

bool SettingsOnly: when true, only the working parameters are saved, not the font; reserved for internal use

Method CharReader::Read: loads the font description and recognition parameters to initialize the reader from a file (UNICODE path and name)

void Read(const wchar_t* PathName, bool SettingsOnly = false);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string; .fnt extension recommended

bool SettingsOnly: when true, only the working parameters are saved, not the font; reserved for internal use


Member of the class CharReader - Storage

Method CharReader::Write: saves the font description and recognition parameters for later reuse to a file (ASCII path and name)

void Write(const char* PathName, bool SettingsOnly = false, bool OptimalOnly = false);

char* PathName: file path and name as an ASCII or UNICODE character string; .fnt extension recommended

bool SettingsOnly: when true, only the working parameters are saved, not the font; reserved for internal use

bool OptimalOnly: when true, only the minimal subset is saved to the file; otherwise the whole training set

Method CharReader::Write: saves the font description and recognition parameters for later reuse to a .fnt file (UNICODE path and name)

void Write(const wchar_t* PathName, bool SettingsOnly = false, bool OptimalOnly = false);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string; .fnt extension recommended

bool SettingsOnly: when true, only the working parameters are saved, not the font; reserved for internal use

bool OptimalOnly: when true, only the minimal subset is saved to the file; otherwise the whole training set


Member of the class CharReader - Graphics

Method CharReader::Draw: renders the segmented characters in the current drawing window as a series of boxes

void Draw(bool Codes = true);

bool Codes: when true, the character values are shown at the box corners


Member of the class CharReader - Graphics

Method CharReader::GetBoxes: undocumented; reserved

bool GetBoxes(Limits* Box, wchar_t Code[], bool Valid[]);

returned bool: when false, the operation has not been performed

Limits* Box: bounding box coordinates

wchar_t* Code: ASCII or UNICODE value

bool* Valid: score validity


Member of the class CharReader - Graphics

Method CharReader::DrawLayout: renders the layout of the characters in the current drawing window

void DrawLayout(bool Codes = true);

bool Codes: when true, filter codes are drawn as well


Member of the class CharReader - Graphics

Method CharReader::GetLayoutBoxes: returns the limit coordinates of the layout boxes

bool GetLayoutBoxes(Limits* Box);

returned bool: when false, the operation has not been performed

Limits* Box: user-allocated array of bounding box coordinates; CAUTION: must be large enough to hold NumLayoutBoxes Limits


Member of the class CharReader - Graphics

Method CharReader::DrawFontChars: renders the trained characters in the current drawing window

void DrawFontChars(int X, int Y, int Width, int Height, int ColumnSpacing = 5, int RowSpacing = 5, bool Raw = true, bool Codes = true, bool OptimizedOnly = true);

int X: upper left point abscissa of the drawing area, in pixels

int Y: upper left point ordinate of the drawing area, in pixels, top-down

int Width: number of pixels of the drawing area, horizontally

int Height: number of pixels, vertically

int ColumnSpacing: number of pixels skipped horizontally between two characters

int RowSpacing: number of pixels skipped vertically between two characters

bool Raw: when true, the original character images are displayed; when false, normalized images are used

bool Codes: when true, the character values are shown at the box corners

bool OptimizedOnly: when true, only the minimal subset is shown; otherwise the whole training set


Member of the class CharReader - Graphics

Method CharReader::HitChar: tells if a segmented character is under the cursor

enum DraggingHandles HitChar(int CursorX, int CursorY);

returned DraggingHandles: one of AllHandle, over a segmented character, or NoHandle

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down


Member of the class CharReader - Graphics

Property int CharReader::CharIndex: index of the segmented character that was last hit


Member of the class CharReader - Graphics

Method CharReader::HitFontChar: tells if a font character is under the cursor; pass the same layout parameter as for the call of DrawFontChars

enum DraggingHandles HitFontChar(int CursorX, int CursorY, int X, int Y, int Width, int Height, int ColumnSpacing = 5, int RowSpacing = 5, bool Raw = true);

returned DraggingHandles: one of AllHandle if over a font character, or NoHandle if not

int CursorX: mouse cursor abscissa, in pixels

int CursorY: mouse cursor ordinate, in pixels, top-down

int X: upper left point abscissa of the drawing area, in pixels

int Y: upper left point ordinate of the drawing area, in pixels, top-down

int Width: number of pixels of the drawing area, horizontally

int Height: number of pixels, vertically

int ColumnSpacing: number of pixels skipped horizontally between two characters

int RowSpacing: number of pixels skipped vertically between two characters

bool Raw: when true, the original character images are displayed; when false, normalized images are used


Member of the class CharReader - Graphics

Property DraggingHandles CharReader::Handle: identity of the last dragging handle hit


Member of the class CharReader - Graphics

Property int CharReader::FontCharIndex: index of the font character that was last hit, or -1 if none was


Member of the class CharReader - Graphics

Method CharReader::CharThumbnail: get a bitmap representation of the given segmented character

void CharThumbnail(Image& Src, int Index, Image& Dst, bool Fixed = true);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst

int Index: zero-based index value to access a list of items

Image& Dst: the destination image, which is computed by this operation

bool Fixed: when true, the image is normalized in size; otherwise the size as segmented is kept


Member of the class CharReader - Graphics

Method CharReader::Dump: Outputs the current parameters of a CharReader

void Dump(char* Name = 0);

char* Name: Optional identification for the CharReader object


Struct Split

Character split descriptor; reserved for internal use

Property X: upper left point abscissa, in pixels

Property S: split cost; reserved for internal use


Member of the class Split

Property int Split::X: upper left point abscissa, in pixels


Member of the class Split

Property int Split::S: split cost; reserved for internal use


Struct Word

Character group descriptor; ; reserved for internal use

First chunk in the group

Property Nxt: link to the next word in the text

Links to neighboring words

Property Left: link to the next word on the left

Property Right: link to the next word on the right

Property Visited: traversal flag

Skew box

Property CenterX: abscissa of the center of the Feret box

Property CenterY: ordinate of the center of the Feret box

Property SkewWidth: width of the Feret box

Property SkewHeight: height of the Feret box

Property SkewAngle: orientation of the Feret box


Member of the class Word - First chunk in the group

Property int Word::Nxt: link to the next word in the text


Member of the class Word - Links to neighboring words

Property int Word::Left: link to the next word on the left


Member of the class Word - Links to neighboring words

Property int Word::Right: link to the next word on the right


Member of the class Word - Links to neighboring words

Property bool Word::Visited: traversal flag


Member of the class Word - Skew box

Property double Word::CenterX: abscissa of the center of the Feret box


Member of the class Word - Skew box

Property double Word::CenterY: ordinate of the center of the Feret box


Member of the class Word - Skew box

Property double Word::SkewWidth: width of the Feret box


Member of the class Word - Skew box

Property double Word::SkewHeight: height of the Feret box


Member of the class Word - Skew box

Property double Word::SkewAngle: orientation of the Feret box


Struct Chunk

Partial character descriptor; reserved for internal use

Related chunk

Property Nxt: link to the next chunk in the word

Related blob

Property Blob: link to the blob representation


Member of the class Chunk - Related chunk

Property int Chunk::Nxt: link to the next chunk in the word


Member of the class Chunk - Related blob

Property int Chunk::Blob: link to the blob representation


Enumeration

Enum Symbologies: the 1D or 2D code symbologies supported by the readers

Case NoSymbology: means that decoding failed

Case CodeEAN128: GS1-128, formerly EAN 128

Case CodeEAN13: 13 digits European Article Numbering

Case CodeEAN8: 8 digits European Article Numbering

Case CodeUPCA: Universal Product Code, type A

Case CodeUPCE: Universal Product Code, type C

Case Code2of5: Interleaved Two of Five, IATA compliant

Case Code39: USS Code 39 (Intermec; optional modulo 43 checksum)

Case Code39Extended: USS Code 39 Extended (full ASCII; optional modulo 43 checksum)

Case CodePharmacode: binary Pharmacode

Case CodeDatabar: GS1 Databar, formerly RSS-14

Case CodeDatabarLimited: GS1 Databar Limited, formerly RSS-14 Limited

Case CodeDatabarExpanded: GS1 Databar Expanded, formerly RSS-14 Expanded

Case Code93: Code 93 (Intermec)

Case CodeCodabar: Codabar (Pitney Bowes; optional Luhn checksum)

Case CodeDataMatrix: Data Matrix (ISO/IEC 16022:2006)

Case CodeDMRectangle: Data Matrix with a rectangular shape (ISO/IEC 16022:2006)

Case CodeQR: QR - Quick Response code (SO/IEC 18004:2006)

Case CodeMicroQR: microQR - micro Quick Response code (SO/IEC 18004:2006)

Case CodeAztec: Aztec code (ISO/IEC 24778:2008)

Case CodeAztecCompact: Aztec Compact code (ISO/IEC 24778:2008)

Case CodePDF417: Portable Data File 417

Case CodeDotCode: ISS DotCode code (AIM AIMD013:2012)


Class Code1DReader

Barcode reader

Constructor Code1DReader: creates a void Code1DReader object

Destructor ~Code1DReader: Destructor

Decoding

Method Decode: process the image to find a barcode and read it

Property DetectEAN128: when true, as by default, Code128 symbols can be detected

Property DetectEAN13: when true, as by default, EAN13 symbols can be detected

Property DetectEAN8: when true, as by default, EAN8 symbols can be detected

Property DetectUPCA: when true, as by default, UPC-A symbols can be detected; when the first digit is 0, they take precendence over EAN13

Property DetectUPCE: when true, as by default, UPC-E symbols can be detected

Property Detect2of5: when true, as by default, Interleaved 2 of 5 symbols can be detected

Property Detect39: when true, as by default, Code39 symbols can be detected

Property Detect39Extended: when true, as by default, full ASCII Code39 symbols can be detected ($, /, % and + interpreted as shifts)

Property Detect93: when true, as by default, Code93 symbols can be detected

Property DetectCodabar: when true, as by default, Codabar symbols can be detected

Property DetectDatabar: when true, as by default, GS1 Databar (RSS-14) symbols can be detected

Property DetectDatabarLimited: when true, as by default, GS1 Databar Limited (RSS-14 Limited) symbols can be detected

Property DetectPharmacode: when true, as by default, Pharmacode symbols can be detected

Property NumDirections: Number of scanning directions, Auto: any, 0: vertical, 1: horizontal, 2: both, 3 and more: oblique, every 180/N degrees

Property Density: spacing between scanning-lines, in pixels; small values favor the decoding rate and increase the running time; 5 by default

Property Noise: threshold level to get rid of spurious bars caused by noise; 10 by default, increase for a noisy image

Property Step: minimum bar constrast wrt the background; 32 by default, decrease for a low contrasted image

Property Reverse: reverse the reading direction (for direction-sensitive codes such as Pharmacode); false to read left-to-right or top-down, true to read right-to-left or bottom-up

Property CheckQuietZone: when true, as by default, a quiet zone as large as the standard requires must be present; when set to false, it is advisable to disable other symbologies to avoid false matches

Property MinimumBars: minimum number of bars required for a successful decode; 3 by default

Property SymbologyIdentifier: EAN128 only: when true, as by default, and an FNC1 code was found in the first position, the Symbology Identifier ]C1 is prepended

Decoding Results

Property NumDecoded: number of successfully decoded symbols

Method Choose: select a symbol to read the associated results; by default the best read is selected

Property AsciiString: barcode content returned as an string of ASCII characters

Property UnicodeString: barcode content returned as an string of UNICODE characters

Property Symbology: the type of the symbol that was decoded

Property ValidCRC: indicates if the decoded string has a valid checksum; only meaningful when the checksum is optional (Code2of5 and Code39)

Property ReadFNC1: 1 or 2 when a FNC1 code was found in the first or second position; 0 otherwise

Property ReaderProgramming: true if the Reader Programming control character was found in the first position

Property Append: true if an Append control character was found

Method ExpandGS1: converts a GS1 barcode/2D code content to the Application Identifiers format

Quality Indicators

Property CheckQuality: when true, activates computation of the Quality Indicators

Property AsciiGrade: ASCII overall quality grade

Property UnicodeGrade: UNICODE overall quality grade

Property AsciiProfileGrades: ASCII per profile quality gradings, in the order: Scan, Minimum Reflectance, Edge Determination, Symbol Contrast, Edge Contrast, Modulation, Defects, Decode, Decodability, Quiet Zone

Property UnicodeProfileGrades: UNICODE per profile quality gradings, in the order: Scan, Minimum Reflectance, Edge Determination, Symbol Contrast, Edge Contrast, Modulation, Defects, Decode, Decodability, Quiet Zone

Storage

Method Read: save the barcode reader parameters to a file (ASCII or UNICODE path and name)

Method Write: save the barcode reader parameters to a file (ASCII or UNICODE path and name)

Color Training

Method ColorTrain: learn the colors of the bars to be verified

Property RgbTolerance: allowed deviation on the RGB color components

Property ValidColors: true when the color inspection found no flaw

Property NumColorBars: total number of bars to be inspected for color

Graphics

Method Draw: draws the barcode that was decoded

Property X: abscissa of the upper-left corner of the symbol in the image

Property Y: ordinate of the upper-left corner of the symbol in the image

Property Width: estimated width of the symbol in the image

Property Height: estimated height of the symbol in the image

Property Angle: estimated rotation angle of the symbol in the image, in the current angle unit

Method ColorReset: forget the colors of the bars to be verified

Method BarColor: reference color for a given bar


Member of the class Code1DReader

Constructor Code1DReader::Code1DReader: creates a void Code1DReader object

Code1DReader();


Member of the class Code1DReader

Destructor Code1DReader::~Code1DReader: Destructor

~Code1DReader();


Member of the class Code1DReader - Decoding

Method Code1DReader::Decode: process the image to find a barcode and read it

bool Decode(const Image& Src);

returned bool: true when reading was successful

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Gray16, Rgb, Rgba


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectEAN128: when true, as by default, Code128 symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectEAN13: when true, as by default, EAN13 symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectEAN8: when true, as by default, EAN8 symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectUPCA: when true, as by default, UPC-A symbols can be detected; when the first digit is 0, they take precendence over EAN13


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectUPCE: when true, as by default, UPC-E symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::Detect2of5: when true, as by default, Interleaved 2 of 5 symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::Detect39: when true, as by default, Code39 symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::Detect39Extended: when true, as by default, full ASCII Code39 symbols can be detected ($, /, % and + interpreted as shifts)


Member of the class Code1DReader - Decoding

Property bool Code1DReader::Detect93: when true, as by default, Code93 symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectCodabar: when true, as by default, Codabar symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectDatabar: when true, as by default, GS1 Databar (RSS-14) symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectDatabarLimited: when true, as by default, GS1 Databar Limited (RSS-14 Limited) symbols can be detected


Member of the class Code1DReader - Decoding

Property bool Code1DReader::DetectPharmacode: when true, as by default, Pharmacode symbols can be detected


Member of the class Code1DReader - Decoding

Property int Code1DReader::NumDirections: Number of scanning directions, Auto: any, 0: vertical, 1: horizontal, 2: both, 3 and more: oblique, every 180/N degrees


Member of the class Code1DReader - Decoding

Property int Code1DReader::Density: spacing between scanning-lines, in pixels; small values favor the decoding rate and increase the running time; 5 by default


Member of the class Code1DReader - Decoding

Property int Code1DReader::Noise: threshold level to get rid of spurious bars caused by noise; 10 by default, increase for a noisy image


Member of the class Code1DReader - Decoding

Property int Code1DReader::Step: minimum bar constrast wrt the background; 32 by default, decrease for a low contrasted image


Member of the class Code1DReader - Decoding

Property bool Code1DReader::Reverse: reverse the reading direction (for direction-sensitive codes such as Pharmacode); false to read left-to-right or top-down, true to read right-to-left or bottom-up


Member of the class Code1DReader - Decoding

Property bool Code1DReader::CheckQuietZone: when true, as by default, a quiet zone as large as the standard requires must be present; when set to false, it is advisable to disable other symbologies to avoid false matches


Member of the class Code1DReader - Decoding

Property int Code1DReader::MinimumBars: minimum number of bars required for a successful decode; 3 by default


Member of the class Code1DReader - Decoding

Property bool Code1DReader::SymbologyIdentifier: EAN128 only: when true, as by default, and an FNC1 code was found in the first position, the Symbology Identifier ]C1 is prepended


Member of the class Code1DReader - Decoding Results

Property int Code1DReader::NumDecoded: number of successfully decoded symbols


Member of the class Code1DReader - Decoding Results

Method Code1DReader::Choose: select a symbol to read the associated results; by default the best read is selected

void Choose(int DecodedIndex);

int DecodedIndex: the index of the code, in range [0..NumDecoded-1]

Method Code1DReader::Choose: select a symbol to read the associated results; by default the best read is selected

void Choose(int DecodedIndex, const Image& Src);

int DecodedIndex: the index of the code, in range [0..NumDecoded-1]

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Code1DReader - Decoding Results

Property char* Code1DReader::AsciiString: barcode content returned as an string of ASCII characters


Member of the class Code1DReader - Decoding Results

Property wchar_t* Code1DReader::UnicodeString: barcode content returned as an string of UNICODE characters


Member of the class Code1DReader - Decoding Results

Property Symbologies Code1DReader::Symbology: the type of the symbol that was decoded


Member of the class Code1DReader - Decoding Results

Property bool Code1DReader::ValidCRC: indicates if the decoded string has a valid checksum; only meaningful when the checksum is optional (Code2of5 and Code39)


Member of the class Code1DReader - Decoding Results

Property bool Code1DReader::ReadFNC1: 1 or 2 when a FNC1 code was found in the first or second position; 0 otherwise


Member of the class Code1DReader - Decoding Results

Property bool Code1DReader::ReaderProgramming: true if the Reader Programming control character was found in the first position


Member of the class Code1DReader - Decoding Results

Property bool Code1DReader::Append: true if an Append control character was found


Member of the class Code1DReader - Decoding Results

Method Code1DReader::ExpandGS1: converts a GS1 barcode/2D code content to the Application Identifiers format

static int ExpandGS1(const char In[], char Out[], int OutLength, bool Verbose = false);

returned int: length of the expanded string, including a terminating null byte

char* In: GS1 barcode or 2D code content; a starting Symbology Identifier ]cm is ignored

char* Out: output buffer; if null, no output string is produced, only the length is computed

int OutLength: length of the output buffer, in characters, including a terminating null byte; must be large enough to accomodate the output string

bool Verbose: if true, the fields are listed one per row, with their full name; otherwise the linear AI format is used


Member of the class Code1DReader - Quality Indicators

Property bool Code1DReader::CheckQuality: when true, activates computation of the Quality Indicators


Member of the class Code1DReader - Quality Indicators

Property char Code1DReader::AsciiGrade: ASCII overall quality grade


Member of the class Code1DReader - Quality Indicators

Property wchar_t Code1DReader::UnicodeGrade: UNICODE overall quality grade


Member of the class Code1DReader - Quality Indicators

Property char* Code1DReader::AsciiProfileGrades: ASCII per profile quality gradings, in the order: Scan, Minimum Reflectance, Edge Determination, Symbol Contrast, Edge Contrast, Modulation, Defects, Decode, Decodability, Quiet Zone


Member of the class Code1DReader - Quality Indicators

Property wchar_t* Code1DReader::UnicodeProfileGrades: UNICODE per profile quality gradings, in the order: Scan, Minimum Reflectance, Edge Determination, Symbol Contrast, Edge Contrast, Modulation, Defects, Decode, Decodability, Quiet Zone


Member of the class Code1DReader - Storage

Method Code1DReader::Read: save the barcode reader parameters to a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .c1r extension recommended

Method Code1DReader::Read: save the barcode reader parameters to a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .c1r extension recommended


Member of the class Code1DReader - Storage

Method Code1DReader::Write: save the barcode reader parameters to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .c1r extension recommended

Method Code1DReader::Write: save the barcode reader parameters to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .c1r extension recommended


Member of the class Code1DReader - Color Training

Method Code1DReader::ColorTrain: learn the colors of the bars to be verified

void ColorTrain(const Image& Src);

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Rgb, Rgba


Member of the class Code1DReader - Color Training

Property int Code1DReader::RgbTolerance: allowed deviation on the RGB color components


Member of the class Code1DReader - Color Training

Property bool Code1DReader::ValidColors: true when the color inspection found no flaw


Member of the class Code1DReader - Color Training

Property int Code1DReader::NumColorBars: total number of bars to be inspected for color


Member of the class Code1DReader - Graphics

Method Code1DReader::Draw: draws the barcode that was decoded

void Draw(bool Text = true, bool Type = true, bool All = true, bool HighlightCurrent = false);

bool Text: when true, as by default, the textual content is displayed next to the symbol

bool Type: when true, as by default, the symbology name is displayed next to the content

bool All: when true, as by default, all codes found are displayed in addition to the chosen one

bool HighlightCurrent: when true, only the current code is drawn in green and with text; by default false


Member of the class Code1DReader - Graphics

Property int Code1DReader::X: abscissa of the upper-left corner of the symbol in the image


Member of the class Code1DReader - Graphics

Property int Code1DReader::Y: ordinate of the upper-left corner of the symbol in the image


Member of the class Code1DReader - Graphics

Property int Code1DReader::Width: estimated width of the symbol in the image


Member of the class Code1DReader - Graphics

Property int Code1DReader::Height: estimated height of the symbol in the image


Member of the class Code1DReader - Graphics

Property double Code1DReader::Angle: estimated rotation angle of the symbol in the image, in the current angle unit


Member of the class Code1DReader - Graphics

Method Code1DReader::ColorReset: forget the colors of the bars to be verified

void ColorReset();


Member of the class Code1DReader - Graphics

Method Code1DReader::BarColor: reference color for a given bar

RgbPixel BarColor(int BarIndex);

returned RgbPixel: RGB components of the color

int BarIndex: zero-based index of the bar, in range [0..NumColorBars-1]


Enumeration

Enum CodePolarities: contrast of the marking

Case BlackOnWhite: dark print on a light background

Case WhiteOnBlack: light print on a dark background

Case AutoPolarity: both polarities are possible and automatically determined


Enumeration

Enum CodeViews: side from which the marking is seen

Case Straight: seen from the front

Case Mirrored: mirrored, as seen from the back

Case AutoView: both sides are possible and automatically determined


Enumeration

Enum Sizes: logical size of the Data Matrix, in cells

Case Size10: DataMatrix, 10x10 cells

Case Size12: DataMatrix, 12x12 cells

Case Size14: DataMatrix, 14x14 cells

Case Size16: DataMatrix, 16x16 cells

Case Size18: DataMatrix, 18x18 cells

Case Size20: DataMatrix, 20x20 cells

Case Size22: DataMatrix, 22x22 cells

Case Size24: DataMatrix, 24x24 cells

Case Size26: DataMatrix, 26x26 cells

Case Size32: DataMatrix, 32x32 cells

Case Size36: DataMatrix, 36x36 cells

Case Size40: DataMatrix, 40x40 cells

Case Size44: DataMatrix, 44x44 cells

Case Size48: DataMatrix, 48x48 cells

Case Size52: DataMatrix, 52x52 cells

Case Size64: DataMatrix, 64x64 cells

Case Size72: DataMatrix, 72x72 cells

Case Size80: DataMatrix, 80x80 cells

Case Size88: DataMatrix, 88x88 cells

Case Size96: DataMatrix, 96x96 cells

Case Size104: DataMatrix, 104x104 cells

Case Size120: DataMatrix, 120x120 cells

Case Size132: DataMatrix, 132x132 cells

Case Size144: DataMatrix, 144x144 cells

Case Size8x18: DataMatrix, 8x18 cells

Case Size8x32: DataMatrix, 8x32 cells

Case Size12x26: DataMatrix, 12x26 cells

Case Size12x36: DataMatrix, 12x36 cells

Case Size16x36: DataMatrix, 16x36 cells

Case Size16x48: DataMatrix, 16x48 cells

Case Version1: QR Version 1, 21x21 cells

Case Version2: QR Version 2, 25x25 cells

Case Version3: QR Version 3, 29x29 cells

Case Version4: QR Version 4, 33x33 cells

Case Version5: QR Version 5, 37x37 cells

Case Version6: QR Version 6, 41x41 cells

Case Version7: QR Version 7, 45x45 cells

Case Version8: QR Version 8, 49x49 cells

Case Version9: QR Version 9, 53x53 cells

Case Version10: QR Version 10, 57x57 cells

Case Version11: QR Version 11, 61x61 cells

Case Version12: QR Version 12, 65x65 cells

Case Version13: QR Version 13, 69x69 cells

Case Version14: QR Version 14, 73x73 cells

Case Version15: QR Version 15, 77x77 cells

Case Version16: QR Version 16, 81x81 cells

Case Version17: QR Version 17, 85x85 cells

Case Version18: QR Version 18, 89x89 cells

Case Version19: QR Version 19, 93x93 cells

Case Version20: QR Version 20, 97x97 cells

Case Version21: QR Version 21, 101x101 cells

Case Version22: QR Version 22, 105x105 cells

Case Version23: QR Version 23, 109x109 cells

Case Version24: QR Version 24, 113x113 cells

Case Version25: QR Version 25, 117x117 cells

Case Version26: QR Version 26, 121x121 cells

Case Version27: QR Version 27, 125x125 cells

Case Version28: QR Version 28, 129x129 cells

Case Version29: QR Version 29, 133x133 cells

Case Version30: QR Version 30, 137x137 cells

Case Version31: QR Version 31, 141x141 cells

Case Version32: QR Version 32, 145x145 cells

Case Version33: QR Version 33, 149x149 cells

Case Version34: QR Version 34, 153x153 cells

Case Version35: QR Version 35, 157x157 cells

Case Version36: QR Version 36, 161x161 cells

Case Version37: QR Version 37, 165x165 cells

Case Version38: QR Version 38, 169x169 cells

Case Version39: QR Version 39, 173x173 cells

Case Version40: QR Version 40, 177x177 cells

Case DotCode: DotCode, %dx%d

Case SizesCount: enumerated values bound; do not use


Class Code2DReader

Data Matrix code reader

Constructor Code2DReader: creates a void Code2DReader object

Destructor ~Code2DReader: Destructor

Properties

Property EnabledPolarities: selects the possible contrast of the marking, as enumerated in CodePolarities

Property EnabledViews: selects the possible orientation of the marking, as enumerated in CodeViews

Property SizeFrom: smallest size to look for (DataMatrix only); one of Size10, Size12, Size14, Size16, Size18, Size20, Size22, Size24, Size26, Size32, Size36, Size40, Size44, Size48, Size52, Size64, Size72, Size80, Size88, Size96, Size104, Size120, Size132, Size144, Size8x18, Size8x32, Size12x26, Size12x36, Size16x36, Size16x48

Property SizeTo: largest size to look for; by default rectangular codes are ignored (DataMatrix only); one of Size10, Size12, Size14, Size16, Size18, Size20, Size22, Size24, Size26, Size32, Size36, Size40, Size44, Size48, Size52, Size64, Size72, Size80, Size88, Size96, Size104, Size120, Size132, Size144, Size8x18, Size8x32, Size12x26, Size12x36, Size16x36, Size16x48

Property Size: logical size of the detected code, as enumerated in Sizes

Property DetectDataMatrix: enable the detection of DataMatrix codes

Property DetectQR: enable the detection of QR codes

Property DetectDotCode: enable the detection of DotCodes

Property InkingCorrection: a positive value thickens the black cells in case of underinking, a negative value thins them in case of overinking

Property AdaptiveThreshold: when true, as by default, the reader compensates illumination unevenness and the effect of clutter; false is recommended when the quality indicators are evaluated

Property Threshold: binarization threshold used for code detection when AdaptiveThreshold is false; by default Auto, which causes automatic adjustment; manual use is discouraged

Property StartLevel: for large images, you can skip the first pyramid levels for faster execution; try small positive value

Property AccurateEdges: when true, a final subpixel fit of the edges is performed for very accurate location

Property SymbologyIdentifier: when true, the Symbology Identifier preamble is added to the returned string

Property ObsoleteDotCode: DotCode only: when true, the codes compliant with the AIM standard before 4.0 are decoded even with empty peripheric rows; false by default

Property ClutteredQuietZone: DotCode only: when true, as by default, reading is made robust against clutter in the vicinity of the code

Decoding

Property MaxDecoded: maximum number of codes to be decoded; 1 by default; the search stops when this number has been reached

Method Decode: finds and reads a Data Matrix code

Method DCCorrectGeometry: enables a correction of the dot positions in case of a known affine deformation; DotCode only

Method QRPresetFinders: reserved use; specify explicitly three finder pattern; no specific order

Decoding Results

Property NumDecoded: number of codes that were succesfully decoded

Method Choose: selects the symbol for which data is retrieved

Property AsciiString: the decoded string, using the ASCII representation

Property UnicodeString: the decoded string, using the UNICODE representation

Property Symbology: the type of the symbol that was decoded

Property StringLength: number of characters in the string, excluding the final null byte

Property Polarity: polarity of the code that was detected, BlackOnWhite or WhiteOnBlack=

Property View: orientation of the code that was detected, Straight or Mirrored

Property CellSize: average length of the sides of the cells, in pixels

Property ReadFNC1: 1 or 2 when a valid first or second FNC1 code was found; otherwise 0

Property ReaderProgramming: true if the Reader Programming control character was found in the first position

Property SymbolPosition: DataMatrix only: if Structured Append is in use, gives the position in the sequence [0..Total-1]

Property SymbolTotal: DataMatrix only: if Structured Append is in use, gives the total number of symbols in the sequence; otherwise 0

Property SymbolFileID1: if Structured Append is in use, first File Identification code, in range [1..254]

Property SymbolFileID2: if Structured Append is in use, second File Identification code, in range [1..254]

Property ParityData: QR code only: stored parity value in case of a Structured Append

Method ExpandGS1: converts a GS1 barcode/2D code content to the Application Identifiers format

Method ExpandMIL: converts a 2D code content to the MIL-STD-130 format

Quality ISO / IEC 15415

Property CheckQuality: when true, activates computation of the Quality Indicators

Property AsciiGrades: ASCII quality gradings in the order: Overall, Symbol Contrast, Print Growth H, Print Growth V, Axial NonUniformity, Grid NonUniformity, Unused Error, Modulation, Reflectance Margin, Fixed Pattern Damage

Property UnicodeGrades: UNICODE quality gradings in the order: Overall, Symbol Contrast, Print Growth, Axial NonUniformity, Unused Error

Property SymbolContrast: numerical assessment of the contrast strength

Property ContrastUniformity: numerical assessment of local losses of contrast

Property AxialNonUniformity: numerical assessment of geometric isotropy

Property GridNonUniformity: numerical assessment of geometric distortion

Property UnusedError: numerical assessment of error-freeness

Property PrintGrowthHorizontal: numerical assessment of the cell filling in the horizontal direction

Property PrintGrowthVertical: numerical assessment of the cell filling in the vertical direction

Storage

Method Read: save the 2D code reader parameters to a file (ASCII or UNICODE path and name)

Method Write: save the 2D code reader parameters to a file (ASCII or UNICODE path and name)

Graphics

Method Draw: draws the outline of the code

Property X: abscissa of the top-left corner of the symbol

Property Y: ordinate of the top-left corner of the symbol

Property Width: width of the symbol, in pixels

Property Height: height of the symbol, in pixels

Property Angle: rotation angle of the symbol, in the current angle unit

Method Corner: coordinates of the four corners of the outer quadrilateral

Property PrintGrowthNominal: the nominal value required to compute the PrintGrowth quality indicator

Property PrintGrowthMinimum: the minimum value required to compute the PrintGrowth quality indicator

Property PrintGrowthMaximum: the maximum value required to compute the PrintGrowth quality indicator


Member of the class Code2DReader

Constructor Code2DReader::Code2DReader: creates a void Code2DReader object

Code2DReader();


Member of the class Code2DReader

Destructor Code2DReader::~Code2DReader: Destructor

~Code2DReader();


Member of the class Code2DReader - Properties

Property CodePolarities Code2DReader::EnabledPolarities: selects the possible contrast of the marking, as enumerated in CodePolarities


Member of the class Code2DReader - Properties

Property CodeViews Code2DReader::EnabledViews: selects the possible orientation of the marking, as enumerated in CodeViews


Member of the class Code2DReader - Properties

Property Sizes Code2DReader::SizeFrom: smallest size to look for (DataMatrix only); one of Size10, Size12, Size14, Size16, Size18, Size20, Size22, Size24, Size26, Size32, Size36, Size40, Size44, Size48, Size52, Size64, Size72, Size80, Size88, Size96, Size104, Size120, Size132, Size144, Size8x18, Size8x32, Size12x26, Size12x36, Size16x36, Size16x48


Member of the class Code2DReader - Properties

Property Sizes Code2DReader::SizeTo: largest size to look for; by default rectangular codes are ignored (DataMatrix only); one of Size10, Size12, Size14, Size16, Size18, Size20, Size22, Size24, Size26, Size32, Size36, Size40, Size44, Size48, Size52, Size64, Size72, Size80, Size88, Size96, Size104, Size120, Size132, Size144, Size8x18, Size8x32, Size12x26, Size12x36, Size16x36, Size16x48


Member of the class Code2DReader - Properties

Property Sizes Code2DReader::Size: logical size of the detected code, as enumerated in Sizes


Member of the class Code2DReader - Properties

Property bool Code2DReader::DetectDataMatrix: enable the detection of DataMatrix codes


Member of the class Code2DReader - Properties

Property bool Code2DReader::DetectQR: enable the detection of QR codes


Member of the class Code2DReader - Properties

Property bool Code2DReader::DetectDotCode: enable the detection of DotCodes


Member of the class Code2DReader - Properties

Property int Code2DReader::InkingCorrection: a positive value thickens the black cells in case of underinking, a negative value thins them in case of overinking


Member of the class Code2DReader - Properties

Property bool Code2DReader::AdaptiveThreshold: when true, as by default, the reader compensates illumination unevenness and the effect of clutter; false is recommended when the quality indicators are evaluated


Member of the class Code2DReader - Properties

Property int Code2DReader::Threshold: binarization threshold used for code detection when AdaptiveThreshold is false; by default Auto, which causes automatic adjustment; manual use is discouraged


Member of the class Code2DReader - Properties

Property int Code2DReader::StartLevel: for large images, you can skip the first pyramid levels for faster execution; try small positive value


Member of the class Code2DReader - Properties

Property bool Code2DReader::AccurateEdges: when true, a final subpixel fit of the edges is performed for very accurate location


Member of the class Code2DReader - Properties

Property bool Code2DReader::SymbologyIdentifier: when true, the Symbology Identifier preamble is added to the returned string


Member of the class Code2DReader - Properties

Property bool Code2DReader::ObsoleteDotCode: DotCode only: when true, the codes compliant with the AIM standard before 4.0 are decoded even with empty peripheric rows; false by default


Member of the class Code2DReader - Properties

Property bool Code2DReader::ClutteredQuietZone: DotCode only: when true, as by default, reading is made robust against clutter in the vicinity of the code


Member of the class Code2DReader - Decoding

Property int Code2DReader::MaxDecoded: maximum number of codes to be decoded; 1 by default; the search stops when this number has been reached


Member of the class Code2DReader - Decoding

Method Code2DReader::Decode: finds and reads a Data Matrix code

bool Decode(const Image& Src);

returned bool: true when reading was successful

Image& Src: the source image for this operation - remains unchanged, unless Src = Dst; one of Gray, Rgb, Rgba


Member of the class Code2DReader - Decoding

Method Code2DReader::DCCorrectGeometry: enables a correction of the dot positions in case of a known affine deformation; DotCode only

void DCCorrectGeometry(double LengthX = 1, double AngleX = 0, double LengthY = 1, double AngleY = 0);

double LengthX: length of a deformed grid cell; 1 if not deformed

double AngleX: direction of deformation of the horizontal axis, in the current angle unit

double LengthY: height of a deformed grid cell; 1 if not deformed

double AngleY: direction of deformation of the vertical axis, in the current angle unit


Member of the class Code2DReader - Decoding

Method Code2DReader::QRPresetFinders: reserved use; specify explicitly three finder pattern; no specific order

void QRPresetFinders(const Site& P, const Site& Q, const Site& R, int Size);

Site& P: reserved use; finder pattern reference point

Site& Q: reserved use; finder pattern reference point

Site& R: reserved use; finder pattern reference point

int Size: reserved use; finder pattern size


Member of the class Code2DReader - Decoding Results

Property int Code2DReader::NumDecoded: number of codes that were succesfully decoded


Member of the class Code2DReader - Decoding Results

Method Code2DReader::Choose: selects the symbol for which data is retrieved

void Choose(int DecodedIndex);

int DecodedIndex: index of the desired symbol, in range [0..NumDecoded-1]

Method Code2DReader::Choose: selects the symbol for which data is retrieved

void Choose(int DecodedIndex, const Image& Src);

int DecodedIndex: index of the desired symbol, in range [0..NumDecoded-1]

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Code2DReader - Decoding Results

Property char* Code2DReader::AsciiString: the decoded string, using the ASCII representation


Member of the class Code2DReader - Decoding Results

Property wchar_t* Code2DReader::UnicodeString: the decoded string, using the UNICODE representation


Member of the class Code2DReader - Decoding Results

Property Symbologies Code2DReader::Symbology: the type of the symbol that was decoded


Member of the class Code2DReader - Decoding Results

Property int Code2DReader::StringLength: number of characters in the string, excluding the final null byte


Member of the class Code2DReader - Decoding Results

Property CodePolarities Code2DReader::Polarity: polarity of the code that was detected, BlackOnWhite or WhiteOnBlack=


Member of the class Code2DReader - Decoding Results

Property CodeViews Code2DReader::View: orientation of the code that was detected, Straight or Mirrored


Member of the class Code2DReader - Decoding Results

Property float Code2DReader::CellSize: average length of the sides of the cells, in pixels


Member of the class Code2DReader - Decoding Results

Property bool Code2DReader::ReadFNC1: 1 or 2 when a valid first or second FNC1 code was found; otherwise 0


Member of the class Code2DReader - Decoding Results

Property bool Code2DReader::ReaderProgramming: true if the Reader Programming control character was found in the first position


Member of the class Code2DReader - Decoding Results

Property int Code2DReader::SymbolPosition: DataMatrix only: if Structured Append is in use, gives the position in the sequence [0..Total-1]


Member of the class Code2DReader - Decoding Results

Property int Code2DReader::SymbolTotal: DataMatrix only: if Structured Append is in use, gives the total number of symbols in the sequence; otherwise 0


Member of the class Code2DReader - Decoding Results

Property int Code2DReader::SymbolFileID1: if Structured Append is in use, first File Identification code, in range [1..254]


Member of the class Code2DReader - Decoding Results

Property int Code2DReader::SymbolFileID2: if Structured Append is in use, second File Identification code, in range [1..254]


Member of the class Code2DReader - Decoding Results

Property int Code2DReader::ParityData: QR code only: stored parity value in case of a Structured Append


Member of the class Code2DReader - Decoding Results

Method Code2DReader::ExpandGS1: converts a GS1 barcode/2D code content to the Application Identifiers format

static int ExpandGS1(const char In[], char Out[], int OutLength, bool Verbose = false);

returned int: length of the expanded string, including a terminating null byte

char* In: GS1 barcode or 2D code content; a starting Symbology Identifier ]cm is ignored

char* Out: output buffer; if null, no output string is produced, only the length is computed

int OutLength: length of the output buffer, in characters, including a terminating null byte; must be large enough to accomodate the output string

bool Verbose: if true, the fields are listed one per row, with their full name; otherwise the linear AI format is used


Member of the class Code2DReader - Decoding Results

Method Code2DReader::ExpandMIL: converts a 2D code content to the MIL-STD-130 format

static int ExpandMIL(const char In[], char Out[], int OutLen, bool Verbose= false);

returned int: length of the expanded string, including a terminating null byte

char* In: 2D code content; must begin with [)>RS

char* Out: output buffer; if null, no output string is produced, only the length is computed

int OutLen: length of the output buffer, in characters, including a terminating null byte; must be large enough to accomodate the output string

bool Verbose: if true, the fields are listed one per row; otherwise a linear format is used


Member of the class Code2DReader - Quality ISO / IEC 15415

Property bool Code2DReader::CheckQuality: when true, activates computation of the Quality Indicators


Member of the class Code2DReader - Quality ISO / IEC 15415

Property char* Code2DReader::AsciiGrades: ASCII quality gradings in the order: Overall, Symbol Contrast, Print Growth H, Print Growth V, Axial NonUniformity, Grid NonUniformity, Unused Error, Modulation, Reflectance Margin, Fixed Pattern Damage


Member of the class Code2DReader - Quality ISO / IEC 15415

Property wchar_t* Code2DReader::UnicodeGrades: UNICODE quality gradings in the order: Overall, Symbol Contrast, Print Growth, Axial NonUniformity, Unused Error


Member of the class Code2DReader - Quality ISO / IEC 15415

Property float Code2DReader::SymbolContrast: numerical assessment of the contrast strength


Member of the class Code2DReader - Quality ISO / IEC 15415

Property float Code2DReader::ContrastUniformity: numerical assessment of local losses of contrast


Member of the class Code2DReader - Quality ISO / IEC 15415

Property float Code2DReader::AxialNonUniformity: numerical assessment of geometric isotropy


Member of the class Code2DReader - Quality ISO / IEC 15415

Property float Code2DReader::GridNonUniformity: numerical assessment of geometric distortion


Member of the class Code2DReader - Quality ISO / IEC 15415

Property float Code2DReader::UnusedError: numerical assessment of error-freeness


Member of the class Code2DReader - Quality ISO / IEC 15415

Property float Code2DReader::PrintGrowthHorizontal: numerical assessment of the cell filling in the horizontal direction


Member of the class Code2DReader - Quality ISO / IEC 15415

Property float Code2DReader::PrintGrowthVertical: numerical assessment of the cell filling in the vertical direction


Member of the class Code2DReader - Storage

Method Code2DReader::Read: save the 2D code reader parameters to a file (ASCII or UNICODE path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .c2r extension recommended

Method Code2DReader::Read: save the 2D code reader parameters to a file (ASCII or UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .c2r extension recommended


Member of the class Code2DReader - Storage

Method Code2DReader::Write: save the 2D code reader parameters to a file (ASCII or UNICODE path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .c2r extension recommended

Method Code2DReader::Write: save the 2D code reader parameters to a file (ASCII or UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .c2r extension recommended


Member of the class Code2DReader - Graphics

Method Code2DReader::Draw: draws the outline of the code

void Draw(bool Text = true, bool Type = true, bool All = true, bool HighlightCurrent = false);

bool Text: when true, the decoded text is drawn too

bool Type: when true, as by default, the symbology name is displayed next to the content

bool All: when true, as by default, all codes are displayed in addition to the chosen one

bool HighlightCurrent: when true, only the current code is drawn in green and with text; by default false


Member of the class Code2DReader - Graphics

Property int Code2DReader::X: abscissa of the top-left corner of the symbol


Member of the class Code2DReader - Graphics

Property int Code2DReader::Y: ordinate of the top-left corner of the symbol


Member of the class Code2DReader - Graphics

Property int Code2DReader::Width: width of the symbol, in pixels


Member of the class Code2DReader - Graphics

Property int Code2DReader::Height: height of the symbol, in pixels


Member of the class Code2DReader - Graphics

Property double Code2DReader::Angle: rotation angle of the symbol, in the current angle unit


Member of the class Code2DReader - Graphics

Method Code2DReader::Corner: coordinates of the four corners of the outer quadrilateral

XY Corner(int Index);

returned XY: coordinates of the selected corner

int Index: corner index, one of [0..3]


Member of the class Code2DReader - Graphics

Property float Code2DReader::PrintGrowthNominal: the nominal value required to compute the PrintGrowth quality indicator


Member of the class Code2DReader - Graphics

Property float Code2DReader::PrintGrowthMinimum: the minimum value required to compute the PrintGrowth quality indicator


Member of the class Code2DReader - Graphics

Property float Code2DReader::PrintGrowthMaximum: the maximum value required to compute the PrintGrowth quality indicator


Struct CodeCandidate

Code descriptor; reserved

Property Type: symbology identifier; reserved

Property Center: coordinates of the center; reserved

Property Size: side length; reserved

Property Middle[8]: key points coordinates; reserved


Member of the class CodeCandidate

Property Symbologies CodeCandidate::Type: symbology identifier; reserved


Member of the class CodeCandidate

Property Site CodeCandidate::Center: coordinates of the center; reserved


Member of the class CodeCandidate

Property int CodeCandidate::Size: side length; reserved


Member of the class CodeCandidate

Property Site CodeCandidate::Middle[8]: key points coordinates; reserved


Struct BlobData2D

Internal data descriptor; RESERVED

Property Tag: Blob label; RESERVED

Reserved use

Property Area: Blob area; RESERVED

Pixel count

Property X: Blob center abscissa; RESERVED

Property Y: Blob center ordinate; RESERVED

Property Dx: X pitch; RESERVED

Property Dy: Y pitch; RESERVED

Bounding box

Property D2: Pitch vector square; RESERVED

Distance to the closest


Member of the class BlobData2D

Property int BlobData2D::Tag: Blob label; RESERVED


Member of the class BlobData2D - Reserved use

Property int BlobData2D::Area: Blob area; RESERVED


Member of the class BlobData2D - Pixel count

Property short BlobData2D::X: Blob center abscissa; RESERVED


Member of the class BlobData2D - Pixel count

Property short BlobData2D::Y: Blob center ordinate; RESERVED


Member of the class BlobData2D - Pixel count

Property short BlobData2D::Dx: X pitch; RESERVED


Member of the class BlobData2D - Pixel count

Property short BlobData2D::Dy: Y pitch; RESERVED


Member of the class BlobData2D - Bounding box

Property int BlobData2D::D2: Pitch vector square; RESERVED


Struct ScanEdge

Reserved for internal use

Vertex pointers

Property I0: reserved for internal use

Property I1: reserved for internal use

Current intersection

Property X: reserved for internal use


Member of the class ScanEdge - Vertex pointers

Property Site* ScanEdge::I0: reserved for internal use


Member of the class ScanEdge - Vertex pointers

Property Site* ScanEdge::I1: reserved for internal use


Member of the class ScanEdge - Current intersection

Property double ScanEdge::X: reserved for internal use


Enumeration

Enum ComparatorMode: Inspection by comparison works in different processing phases

Case CompareIdle: The Comparator has not been initialized yet

Case EditingAligners: The comparator is ready for alignment ROI adjustments

Case EditingDetectors: The comparator is ready for detection ROI adjustments

Case Trained: The comparator is ready for inspections

Case Aligned: The comparator has performed alignment

Case Inspected: The comparator has performed inspection


Enumeration

Enum ROITypes: Regions of Interest for template training, alignment and inspection

Case NoType: No ROI selected

Case Train: Training ROI, used to define a template

Case Search: Search ROI, used to define a search area

Case Detect: Inspection ROI, used to define the area to be compared to the reference


Class Comparator

Discrepancy detection tool with built-in registration

Constructor Comparator: creates a void Comparator object

Property Mode: The current working mode of the Comparator, as defined by enum ComparatorModes

Property Reference: The reference image, as passed to SetReference

Aligners definition

Method SetReference: Pass the Golden template image to be used for reference in the next operations

Property NumAligners: number of regions used for alignment

Property AlignerIndex: Index of the aligner to be used in subsequent operations, in range [0..NumAligners-1]; for some operations, can also be All

Method AlignerTrainROI: Returns the limits of the current searching region, as referenced by AlignerIndex

Property AlignerTrainROI: Returns the limits of the current searching region, as referenced by AlignerIndex

Method AlignerSearchROI: Sets the limits of the current searching region, as referenced by AlignerIndex

Property AlignerSearchROI: Sets the limits of the current searching region, as referenced by AlignerIndex

Method AlignerSearchRange: Specifies the allowance for the search Degrees of Freedom

Method TrainAligners: Let the Comparator learn the matching pattern(s) in view of the alignment task

Property Aligner: Returns a reference to the Locator currently selected with the AlignerIndex, to allow settings

Detectors definition

Property NumDetectors: number of regions used for inspection

Property DetectorIndex: Index of the detector to be used in subsequent operations, in range [0..NumDetectors-1]; for some operations, can also be All

Method DetectorROI: returns the current inspection ROI

Property DetectorROI: returns the current inspection ROI

Method AppendDetectorROI: add an inspection region of interest

Method RemoveDetectorROI: remove the ROI of given index

Alignment

Method Align: realigns the image over the reference image

Property InstanceIndex: when multiple alignment is used with a single aligner, specifies the index of the desired instance

Property Clip: Clipping mask image that shows which pixels took part to the comparison in case of overrun

Property Overrun: when true, means that overrun has occurred while performing alignment

Method ResetRanges: reinitialize the motion range limits

Method UpdateRanges: adjust the motion ranges by taking into account the last alignment move

Property MinShiftX: Measured statistical shift left

Property MaxShiftX: Measured statistical shift right

Property MinShiftY: Measured statistical shift up

Property MaxShiftY: Measured statistical shift down

Property MinRotation: Measured statistical angle minimum

Property MaxRotation: Measured statistical angle maximum

Property MinScaling: Measured statistical scale minimum

Property MaxScaling: Measured statistical scale maximum

Tolerancing

Property Normalize: adjusts the gray-levels in the inspected image so that they globally match those in the reference

Method StraightTolerancing: Computes tolerance masks using simple geometric and radiometric margins

Method StartTolerancing: Starts a sequence of statistical training to create tolerance masks

Method NextTolerancing: Admits a new image in the statistical training process

Method EndTolerancing: Creates tolerance masks after a statistical training sequence has been performed

Property NumAccumulated: during statistical tolerancing, tells how many images have been passed do far

Detection

Method Differences: Computes a difference image between the current (realigned) image and the reference

Storage

Method Read: retrieve the comparator model from an external file

Method Write: save the comparator model to an external file

Graphics

Method DrawROI: Draws a training, searching or inspection region

Method HitROI: index of the ROI a handle of which was hit

Method DragROI: Allows to displace a handle of some Region of Interest, after a HitROI test has been performed

Property ROIHandle: identifies the handle of an ROI that was hit, for cursor change or dragging

Property ROIType: identifies the nature of the ROI that was hit (Train, Search or Inspect)

Method DrawDifferences: Draws as an overlay the out-of-tolerance pixels in the inspected image

Property LowBound: Image of the darkest accepted pixel values

Property HighBound: Image of the lightest accepted pixel values


Member of the class Comparator - Inspect

Constructor Comparator::Comparator: creates a void Comparator object

Comparator();


Member of the class Comparator - Inspect

Property ComparatorMode Comparator::Mode: The current working mode of the Comparator, as defined by enum ComparatorModes


Member of the class Comparator - Inspect

Property Image Comparator::Reference: The reference image, as passed to SetReference


Member of the class Comparator - Aligners definition

Method Comparator::SetReference: Pass the Golden template image to be used for reference in the next operations

void SetReference(Image& Src, int NumAligners = 1, RegistrationModels Model = Translation);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

int NumAligners: Number of aligment devices to be used; one by default for simple alignment; more for composite alignment

RegistrationModels Model: for composite alignment only; specifies the geometric model to use, such as Similarity, Affinity or Perspective

Method Comparator::SetReference: Pass the Golden template image to be used for reference in the next operations

void SetReference(Image& Src, int NumColumns, int NumRows, RegistrationModels Model = Translation);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

int NumColumns: In case of composite array alignment, number of array columns

int NumRows: In case of composite array alignment, number of array rows

RegistrationModels Model: for composite alignment only; specifies the geometric model to use, such as Similarity, Affinity or Perspective


Member of the class Comparator - Aligners definition

Property int Comparator::NumAligners: number of regions used for alignment


Member of the class Comparator - Aligners definition

Property int Comparator::AlignerIndex: Index of the aligner to be used in subsequent operations, in range [0..NumAligners-1]; for some operations, can also be All


Member of the class Comparator - Aligners definition

Method Comparator::AlignerTrainROI: Returns the limits of the current searching region, as referenced by AlignerIndex

void AlignerTrainROI(Limits& L);

Limits& L: Sets the limits of the current training region, as referenced by AlignerIndex


Member of the class Comparator - Aligners definition

Method Comparator::AlignerSearchROI: Sets the limits of the current searching region, as referenced by AlignerIndex

void AlignerSearchROI(Limits& L);

Limits& L: Limits of this ROI


Member of the class Comparator - Aligners definition

Method Comparator::AlignerSearchRange: Specifies the allowance for the search Degrees of Freedom

void AlignerSearchRange(int MinX, int MinY, int MaxX, int MaxY, double MinAngle = 0, double MaxAngle = 0, double MinScale = 1, double MaxScale = 1);

int MinX: Translation allowance on the left side of the template; a negative number

int MinY: Translation allowance on the top side of the template; a negative number

int MaxX: Translation allowance on the right side of the template; a positive number

int MaxY: Translation allowance on the bottom side of the template; a positive number

double MinAngle: Minimum angle of the rotation allowance; a negative number

double MaxAngle: Maximum angle of the rotation allowance; a positive number

double MinScale: Minimum factor of the scaling allowance; a number below 1

double MaxScale: Maximum factor of the scaling allowance; a number above 1

Method Comparator::AlignerSearchRange: Specifies the allowance for the search Degrees of Freedom

void AlignerSearchRange(double MinAngle = 0, double MaxAngle = 0, double MinScale = 1, double MaxScale = 1);

double MinAngle: Minimum angle of the rotation allowance; a negative number

double MaxAngle: Maximum angle of the rotation allowance; a positive number

double MinScale: Minimum factor of the scaling allowance; a number below 1

double MaxScale: Maximum factor of the scaling allowance; a number above 1


Member of the class Comparator - Aligners definition

Method Comparator::TrainAligners: Let the Comparator learn the matching pattern(s) in view of the alignment task

void TrainAligners();


Member of the class Comparator - Aligners definition

Property Locator& Comparator::Aligner(): Returns a reference to the Locator currently selected with the AlignerIndex, to allow settings


Member of the class Comparator - Detectors definition

Property int Comparator::NumDetectors: number of regions used for inspection


Member of the class Comparator - Detectors definition

Property int Comparator::DetectorIndex: Index of the detector to be used in subsequent operations, in range [0..NumDetectors-1]; for some operations, can also be All


Member of the class Comparator - Detectors definition

Method Comparator::DetectorROI: returns the current inspection ROI

void DetectorROI(Limits& L);

Limits& L: returned region of interest


Member of the class Comparator - Detectors definition

Method Comparator::AppendDetectorROI: add an inspection region of interest

void AppendDetectorROI(Limits& L);

Limits& L: the desired region of interest


Member of the class Comparator - Detectors definition

Method Comparator::RemoveDetectorROI: remove the ROI of given index

void RemoveDetectorROI();


Member of the class Comparator - Alignment

Method Comparator::Align: realigns the image over the reference image

void Align(Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation


Member of the class Comparator - Alignment

Property int Comparator::InstanceIndex: when multiple alignment is used with a single aligner, specifies the index of the desired instance


Member of the class Comparator - Alignment

Property Region& Comparator::Clip(): Clipping mask image that shows which pixels took part to the comparison in case of overrun


Member of the class Comparator - Alignment

Property bool Comparator::Overrun: when true, means that overrun has occurred while performing alignment


Member of the class Comparator - Alignment

Method Comparator::ResetRanges: reinitialize the motion range limits

void ResetRanges();


Member of the class Comparator - Alignment

Method Comparator::UpdateRanges: adjust the motion ranges by taking into account the last alignment move

void UpdateRanges(int InstanceIndex= 0);

int InstanceIndex: index of the instance, in case of multi-instance search, in range [0..NumInstances-1]; by default 0, valid for a single-instance search


Member of the class Comparator - Alignment

Property double Comparator::MinShiftX: Measured statistical shift left


Member of the class Comparator - Alignment

Property double Comparator::MaxShiftX: Measured statistical shift right


Member of the class Comparator - Alignment

Property double Comparator::MinShiftY: Measured statistical shift up


Member of the class Comparator - Alignment

Property double Comparator::MaxShiftY: Measured statistical shift down


Member of the class Comparator - Alignment

Property double Comparator::MinRotation: Measured statistical angle minimum


Member of the class Comparator - Alignment

Property double Comparator::MaxRotation: Measured statistical angle maximum


Member of the class Comparator - Alignment

Property double Comparator::MinScaling: Measured statistical scale minimum


Member of the class Comparator - Alignment

Property double Comparator::MaxScaling: Measured statistical scale maximum


Member of the class Comparator - Tolerancing

Property bool Comparator::Normalize: adjusts the gray-levels in the inspected image so that they globally match those in the reference


Member of the class Comparator - Tolerancing

Method Comparator::StraightTolerancing: Computes tolerance masks using simple geometric and radiometric margins

void StraightTolerancing(int Noise, int Radius);

int Noise: tolerance on the gray-levels, used to cope with noise and color variations

int Radius: tolerance on the geometric position, used to cope with deformations and inking effects


Member of the class Comparator - Tolerancing

Method Comparator::StartTolerancing: Starts a sequence of statistical training to create tolerance masks

void StartTolerancing(bool Soft);

bool Soft: when true, the tolerance interval is obtained as a multiple of the standard deviation around the average; otherwise, as the min-max range possibly enlarged


Member of the class Comparator - Tolerancing

Method Comparator::NextTolerancing: Admits a new image in the statistical training process

void NextTolerancing(Image& Src);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Comparator - Tolerancing

Method Comparator::EndTolerancing: Creates tolerance masks after a statistical training sequence has been performed

void EndTolerancing(double SigmaFactor);

double SigmaFactor: Enlargement factor applied to the range or the deviation


Member of the class Comparator - Tolerancing

Property int Comparator::NumAccumulated: during statistical tolerancing, tells how many images have been passed do far


Member of the class Comparator - Detection

Method Comparator::Differences: Computes a difference image between the current (realigned) image and the reference

void Differences(Image& Src, Image& Dst);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

Method Comparator::Differences: Computes a difference image between the current (realigned) image and the reference

void Differences(Image& Src, Histogram& Dark, Histogram& Light);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Histogram& Dark: histogram of the too dark pixels; can be the same as Light

Histogram& Light: histogram of the too light pixels; can be the same as Dark

Method Comparator::Differences: Computes a difference image between the current (realigned) image and the reference

void Differences(Image& Src, Blobs& Defects, int MinimumArea = 5, int MaximumArea = MaxInt);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Blobs& Defects: Blobs object that will hold the results of the comparison, ready for blob analysis

int MinimumArea: area threshold under which blobs are completely undetected; by default 5 pixels

int MaximumArea: area threshold above which blobs are completely undetected; by default the largest integer


Member of the class Comparator - Storage

Method Comparator::Read: retrieve the comparator model from an external file

void Read(const char* PathName);

char* PathName: file path and name as an ASCII or UNICODE character string; .cmp extension recommended

Method Comparator::Read: retrieve the comparator model from an external file

void Read(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string; .cmp extension recommended


Member of the class Comparator - Storage

Method Comparator::Write: save the comparator model to an external file

void Write(const char* PathName);

char* PathName: file path and name as an ASCII or UNICODE character string; .cmp extension recommended

Method Comparator::Write: save the comparator model to an external file

void Write(const wchar_t* PathName);

wchar_t* PathName: file path and name as an ASCII or UNICODE character string; .cmp extension recommended


Member of the class Comparator - Graphics

Method Comparator::DrawROI: Draws a training, searching or inspection region

void DrawROI(ROITypes Type, bool Handles = false);

ROITypes Type: Selects the type of ROI to draw, as defined by enum ROITypes

bool Handles: when true, the dragging handles are drawn too


Member of the class Comparator - Graphics

Method Comparator::HitROI: index of the ROI a handle of which was hit

enum DraggingHandles HitROI(int CursorX, int CursorY, int EnabledTypes);

returned DraggingHandles: Returns the identity of the handle that was hit, as defined by enum HandleTypes

int CursorX: cursor abscissa, in pixels

int CursorY: cursor ordinate, in pixels

int EnabledTypes: Combination of the handle types for which hitting is enabled (use a + or | operator)


Member of the class Comparator - Graphics

Method Comparator::DragROI: Allows to displace a handle of some Region of Interest, after a HitROI test has been performed

void DragROI(int CursorX, int CursorY);

int CursorX: cursor abscissa, in pixels

int CursorY: cursor ordinate, in pixels


Member of the class Comparator - Graphics

Property DraggingHandles Comparator::ROIHandle: identifies the handle of an ROI that was hit, for cursor change or dragging


Member of the class Comparator - Graphics

Property ROITypes Comparator::ROIType: identifies the nature of the ROI that was hit (Train, Search or Inspect)


Member of the class Comparator - Graphics

Method Comparator::DrawDifferences: Draws as an overlay the out-of-tolerance pixels in the inspected image

void DrawDifferences(Image& Src);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst


Member of the class Comparator - Graphics

Property Image Comparator::LowBound: Image of the darkest accepted pixel values


Member of the class Comparator - Graphics

Property Image Comparator::HighBound: Image of the lightest accepted pixel values


Class Snake

Free form shape that can describe the axis of a SnakeGauge

Constructor Snake: creates a void Snake object

Axis definition

Method Append: Add a node to a snake

Append one vertex at a time

Method SegmentAppend: adds a line segment to the snake

Append two vertices defining a line segment (first possibly ignored)

Method ArcAppend: Add a circular arc to a snake

Append three vertices defining a circular arc (first possibly ignored)

Method SplineAppend: array of spline vertices to be added to the snake

Append N vertices defining a spline arc

Method CircleAppend: Add a circle to a snake

Append a single closed circle (empty snake only)

Method EllipseAppend: RESERVED; elliptic arc

Append a single closed ellipse (empty snake only)

Method Clear: Empties the snake geometry

Method Close: make the Snake closed by joining the last vertex to the first

Axis edition

Method ClosestTo: find the vertex or edges closest to the cursor

Method Insert: inserts a new vertex before the current one

Method Delete: removes the current point, if possible

Method Retype: change the type of the current vertex

Method Drag: move the current point to another location

Property HitType: type of the currently selected curve

Registration

Method Register: realign the snake to the image, using a Locator tool

Graphics

Method Draw: draws the snake geometry

Method DrawPolyline: draws a simplified snake representation (lines only)

Property Handle: if true, dragging handles are draws as well

Property HitIndex: index of the last vertex of curve found near the cursor

Storage

Property Length: number of pixels or samples

Property Closed: When true, the last vertex of a snake is joined to the first one


Member of the class Snake

Constructor Snake::Snake: creates a void Snake object

Snake();


Member of the class Snake - Axis definition

Method Snake::Append: Add a node to a snake

void Append(const XY P, SectionType Type);

XY P: node point coordinates

SectionType Type: Type of the appended node


Member of the class Snake - Append one vertex at a time

Method Snake::SegmentAppend: adds a line segment to the snake

void SegmentAppend(const XY& P, const XY& Q);

XY& P: first vertex

XY& Q: second vertex


Member of the class Snake - Append two vertices defining a line segment (first possibly ignored)

Method Snake::ArcAppend: Add a circular arc to a snake

void ArcAppend(const XY& P, const XY& Q, const XY& R);

XY& P: First arc point

XY& Q: Second arc point

XY& R: Third arc point


Member of the class Snake - Append three vertices defining a circular arc (first possibly ignored)

Method Snake::SplineAppend: array of spline vertices to be added to the snake

void SplineAppend(const XY P[], int N);

XY* P: vertex coordinates

int N: number of vertices to add


Member of the class Snake - Append N vertices defining a spline arc

Method Snake::CircleAppend: Add a circle to a snake

void CircleAppend(const XY& P, const XY& Q, const XY& R);

XY& P: First arc point

XY& Q: Second arc point

XY& R: Third arc point

Method Snake::CircleAppend: Add a circle to a snake

void CircleAppend(const XY& Center, double Radius);

XY& Center: RESERVED; single circle center

double Radius: RESERVED; single circle radius


Member of the class Snake - Append a single closed circle (empty snake only)

Method Snake::EllipseAppend: RESERVED; elliptic arc

void EllipseAppend(const XY& P, const XY& Q, const XY& R, const XY& S, const XY& T);

XY& P: RESERVED; ellipse first point

XY& Q: RESERVED; ellipse second point

XY& R: RESERVED; ellipse third point

XY& S: RESERVED; ellipse fourth point

XY& T: RESERVED; ellipse fifth point

Method Snake::EllipseAppend: RESERVED; elliptic arc

void EllipseAppend(const XY& Center, const XY& Axis, double Angle);

XY& Center: RESERVED; ellipse center

XY& Axis: RESERVED; ellipse axis lengths

double Angle: RESERVED; ellipse axis direction


Member of the class Snake - Append a single closed ellipse (empty snake only)

Method Snake::Clear: Empties the snake geometry

void Clear();


Member of the class Snake - Append a single closed ellipse (empty snake only)

Method Snake::Close: make the Snake closed by joining the last vertex to the first

void Close(bool Enable);

bool Enable: true to close, false to open the outline


Member of the class Snake - Axis edition

Method Snake::ClosestTo: find the vertex or edges closest to the cursor

void ClosestTo(XY Cursor);

XY Cursor: cursor coordinates


Member of the class Snake - Axis edition

Method Snake::Insert: inserts a new vertex before the current one

void Insert(XY Cursor);

XY Cursor: cursor coordinates


Member of the class Snake - Axis edition

Method Snake::Delete: removes the current point, if possible

void Delete();


Member of the class Snake - Axis edition

Method Snake::Retype: change the type of the current vertex

bool Retype(SectionType Type, bool CheckOnly = false);

returned bool: true if the operation was allowed

SectionType Type: new type to assign

bool CheckOnly: if true, only tests if this operation is allowed


Member of the class Snake - Axis edition

Method Snake::Drag: move the current point to another location

void Drag(XY Cursor);

XY Cursor: cursor coordinates


Member of the class Snake - Axis edition

Property SectionType Snake::HitType(): type of the currently selected curve


Member of the class Snake - Registration

Method Snake::Register: realign the snake to the image, using a Locator tool

void Register(const Locator& Search, int Index);

Locator& Search: Locator tool that has performed a Search operation for realignment

int Index: Index of the relevant template instance found by the Locator

Method Snake::Register: realign the snake to the image, using a Geometry tool

void Register(const Geometry& Transform);

Geometry& Transform: Geometry tool that has been initialized with the desired registration transform

Method Snake::Register: Restore the snake in its original location

void Register();


Member of the class Snake - Graphics

Method Snake::Draw: draws the snake geometry

void Draw(bool Handles = true);

bool Handles: when true, the dragging handles are drawn too


Member of the class Snake - Graphics

Method Snake::DrawPolyline: draws a simplified snake representation (lines only)

void DrawPolyline(bool Vertices = true);

bool Vertices: it true, the vertices are highlighted


Member of the class Snake - Graphics

Property DraggingHandles Snake::Handle: if true, dragging handles are draws as well


Member of the class Snake - Graphics

Property int Snake::HitIndex: index of the last vertex of curve found near the cursor


Member of the class Snake - Storage

Property int Snake::Length: number of pixels or samples


Member of the class Snake - Storage

Property bool Snake::Closed: When true, the last vertex of a snake is joined to the first one


Class SnakeGauge

Curvilinear stripe defined around a snake axis, with inspection capabilites

Constructor SnakeGauge: creates a void SnakeGauge object

Method Clear: Empties the snake gauge geometry and mesurements

Property Breadth: width of the snake ribbon, extension of the profiles

Inspection

Property Density: spacing of the profiles used for edge detection

Property Thickness: width of the profiles used for edge detection

Property MinimumStep: above this value, edges are considered invalid (too weak)

Property MinimumSlope: below this value, edges are considered invalid (too blurred)

Property MaximumSpan: above this value, edges are considered invalid (too blurred)

Property Noise: gray value under which signal fluctuations are considered as not significant

Property MinimumStep2: above this value, edges are considered invalid (too weak); relates to the second edge of the profile

Property MinimumSlope2: below this value, edges are considered invalid (too blurred) ; relates to the second edge of the profile

Property MaximumSpan2: above this value, edges are considered invalid (too blurred); relates to the second edge of the profile

Property Noise2: gray value under which signal fluctuations are considered as not significant; relates to the second edge of the profile

Property Polarity: desired polarity filter, one of Raising, Falling or Both

Property Polarity2: polarity of the edges to be considered, as defined by the enumeration Polarities

Property Selection: edge selection mode, as define by the enumeration EdgeSelection

Property Selection2: edge selection mode, as define by the enumeration EdgeSelection ; relates to the second edge of the profile

Property NominalWidth: reference width or a ribbon, used to detect intrusions and protrusions; should not exceed twice the Breadth

Property MaxDeviation: distance of the Snake edges to the axis

Property RMS: when true, the root-mean-square deviations are computed; otherwise the absolute mean is used

Method AssessEdge: utility to measure typical edge parameters

Method InspectEdge: inspection of the edges, which should follow the snake axis

Method InspectRibbon: inspection of a pair of edges, which should follow the snake axis and respect a nominal width

Inspection results

Property NumSections: number of sections (segment, arc, spline) of the snake

Method Type: type of the current section

Method NumProfiles: number of profiles in this section, or in total

Method Intrusions: an intrusion is a lack of matter

Method Protrusions: a protrusion is an excess of matter

Method Deviation: deviation for a snake section or the complete snake

Method SectionSegment: get the descriptive parameters of the line segment fitted to this section; must be a Corner type

Method SectionArc: get the descriptive parameters of the circular arc fitted to this section; must be a Circular type

Method EdgePoint: returns a given edge point after edge inspection

Method RibbonPoint: returns a given edge point after ribbon inspection

Sampling

Method Sample: sample an image along a snake ribbon, in a uniform way

Storage

Method Read: loads the snake description and parameters from a file (ASCII path and name)

Method Write: saves the snake description and parameters for later reuse to a file (ASCII path and name)

Axis edition

Method ClosestTo: find the vertex or edges closest to the cursor

Method Drag: move the current point to another location

Graphics

Property PreciseDrawing: when true, exact drawing of the ribbon edges is done; otherwise, a fast but inaccruate method is used

Method Draw: draws the snake gauge geometry

Method DrawEdge: if true,draws the detected edge points

Method DrawRibbon: draw the geometry of the snake gauge, including outer edges

Method DrawFit: draws the fitted sections; CAUTION: currently does not apply to spline sections


Member of the class SnakeGauge

Constructor SnakeGauge::SnakeGauge: creates a void SnakeGauge object

SnakeGauge();


Member of the class SnakeGauge

Method SnakeGauge::Clear: Empties the snake gauge geometry and mesurements

void Clear();


Member of the class SnakeGauge

Property double SnakeGauge::Breadth: width of the snake ribbon, extension of the profiles


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::Density: spacing of the profiles used for edge detection


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::Thickness: width of the profiles used for edge detection


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::MinimumStep: above this value, edges are considered invalid (too weak)


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::MinimumSlope: below this value, edges are considered invalid (too blurred)


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::MaximumSpan: above this value, edges are considered invalid (too blurred)


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::Noise: gray value under which signal fluctuations are considered as not significant


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::MinimumStep2: above this value, edges are considered invalid (too weak); relates to the second edge of the profile


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::MinimumSlope2: below this value, edges are considered invalid (too blurred) ; relates to the second edge of the profile


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::MaximumSpan2: above this value, edges are considered invalid (too blurred); relates to the second edge of the profile


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::Noise2: gray value under which signal fluctuations are considered as not significant; relates to the second edge of the profile


Member of the class SnakeGauge - Inspection

Property Polarities SnakeGauge::Polarity: desired polarity filter, one of Raising, Falling or Both


Member of the class SnakeGauge - Inspection

Property Polarities SnakeGauge::Polarity2: polarity of the edges to be considered, as defined by the enumeration Polarities


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::Selection: edge selection mode, as define by the enumeration EdgeSelection


Member of the class SnakeGauge - Inspection

Property int SnakeGauge::Selection2: edge selection mode, as define by the enumeration EdgeSelection ; relates to the second edge of the profile


Member of the class SnakeGauge - Inspection

Property double SnakeGauge::NominalWidth: reference width or a ribbon, used to detect intrusions and protrusions; should not exceed twice the Breadth


Member of the class SnakeGauge - Inspection

Property double SnakeGauge::MaxDeviation: distance of the Snake edges to the axis


Member of the class SnakeGauge - Inspection

Property bool SnakeGauge::RMS: when true, the root-mean-square deviations are computed; otherwise the absolute mean is used


Member of the class SnakeGauge - Inspection

Method SnakeGauge::AssessEdge: utility to measure typical edge parameters

bool AssessEdge(const Image& Src, double Fraction, int& StepThreshold, int& SlopeThreshold, int& SpanThreshold, int& NumRaising, int& NumFalling, int Selection = OverCenter);

returned bool: returns true to indicate succes; otherwise, too few edge points have been found

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

double Fraction: statistical risk parameter used to define the thresholds; sets the accepted quantile

int& StepThreshold: suitable threshold on the Step criterion

int& SlopeThreshold: suitable threshold on the Slope criterion

int& SpanThreshold: suitable threshold on the Span criterion

int& NumRaising: number of raising edges detected

int& NumFalling: number of falling edges detected

EdgeSelection Selection: one of the selection modes, as defined by the enumeration EdgeSelection


Member of the class SnakeGauge - Inspection

Method SnakeGauge::InspectEdge: inspection of the edges, which should follow the snake axis

void InspectEdge(const Image& Src, bool Fit = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Fit: when true, the section axis are fitted to the local edges before conformity assessment; otherwise, the snake axis remains rigid; CAUTION: currently does not apply to spline sections


Member of the class SnakeGauge - Inspection

Method SnakeGauge::InspectRibbon: inspection of a pair of edges, which should follow the snake axis and respect a nominal width

void InspectRibbon(const Image& Src, bool Fit = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

bool Fit: when true, the section axis are fitted to the local edges before conformity assessment; otherwise, the snake axis remains rigid; CAUTION: currently does not apply to spline sections


Member of the class SnakeGauge - Inspection results

Property int SnakeGauge::NumSections: number of sections (segment, arc, spline) of the snake


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::Type: type of the current section

SectionType Type(int SectionIndex);

returned SectionType: the type, as defined by the enumeration SectionType

int SectionIndex: index of the desired section, or All


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::NumProfiles: number of profiles in this section, or in total

int NumProfiles(int SectionIndex = All);

returned int: number of profiles

BlobSelection SectionIndex: index of the desired section, or All


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::Intrusions: an intrusion is a lack of matter

double Intrusions(int SectionIndex = All);

returned double: percentage of the profiles showing intrusions

BlobSelection SectionIndex: index of the section, in range [0..NumSections], or All


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::Protrusions: a protrusion is an excess of matter

double Protrusions(int SectionIndex = All);

returned double: percentage of the profiles showing protrusions

BlobSelection SectionIndex: index of the desired section, or All


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::Deviation: deviation for a snake section or the complete snake

double Deviation(int SectionIndex = All);

returned double: RMS or absolute mean deviation

BlobSelection SectionIndex: index of the desired section, or All


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::SectionSegment: get the descriptive parameters of the line segment fitted to this section; must be a Corner type

void SectionSegment(int SectionIndex, XY& Beg, XY& End);

int SectionIndex: index of the desired section, in range [0..NumSections-1]

XY& Beg: starting point of the segment

XY& End: ending point of the segment


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::SectionArc: get the descriptive parameters of the circular arc fitted to this section; must be a Circular type

void SectionArc(int SectionIndex, XY& Center, double& Radius, XY& Beg, XY& End);

int SectionIndex: index of the desired section, in range [0..NumSections-1]

XY& Center: arc center

double& Radius: arc radius

XY& Beg: starting point of the arc

XY& End: ending point of the arc


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::EdgePoint: returns a given edge point after edge inspection

bool EdgePoint(int Index, XY& P, bool& Protrusion, bool& Intrusion);

returned bool: false if no suitable edge point was found in this profile; the other arguments remain unchanged

int Index: index of the profile, in range [0..NumProfiles] (obtained from NumProfiles(All))

XY& P: coordinates of the point, in pixels

bool& Protrusion: true if that point protrudes

bool& Intrusion: true if that point intrudes


Member of the class SnakeGauge - Inspection results

Method SnakeGauge::RibbonPoint: returns a given edge point after ribbon inspection

bool RibbonPoint(int Index, bool Left, XY& P, bool& Protrusion, bool& Intrusion);

returned bool: false if no suitable edge point was found in this profile; the other arguments remain unchanged

int Index: index of the profile, in range [0..NumProfiles] (obtained from NumProfiles(All))

bool Left: tells the side for which the point is retrived; true for left side of the snake, false for right

XY& P: coordinates of the point, in pixels

bool& Protrusion: true if that point protrudes

bool& Intrusion: true if that point intrudes


Member of the class SnakeGauge - Sampling

Method SnakeGauge::Sample: sample an image along a snake ribbon, in a uniform way

void Sample(const Image& Src, Image& Dst, bool Interpolate = true);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

Image& Dst: the destination image, which is computed by this operation

bool Interpolate: when true, bilinear interpolation is used to resample the pixels; otherwise nearest neighbor resampling is used


Member of the class SnakeGauge - Storage

Method SnakeGauge::Read: loads the snake description and parameters from a file (ASCII path and name)

void Read(const char* PathName);

char* PathName: full file path and name; .sng extension recommended

Method SnakeGauge::Read: loads the snake description and parameters from a file (UNICODE path and name)

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .sng extension recommended


Member of the class SnakeGauge - Storage

Method SnakeGauge::Write: saves the snake description and parameters for later reuse to a file (ASCII path and name)

void Write(const char* PathName);

char* PathName: full file path and name; .sng extension recommended

Method SnakeGauge::Write: saves the snake description and parameters for later reuse to a file (UNICODE path and name)

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .sng extension recommended


Member of the class SnakeGauge - Axis edition

Method SnakeGauge::ClosestTo: find the vertex or edges closest to the cursor

void ClosestTo(XY Cursor);

XY Cursor: cursor coordinates


Member of the class SnakeGauge - Axis edition

Method SnakeGauge::Drag: move the current point to another location

void Drag(XY Cursor);

XY Cursor: cursor coordinates


Member of the class SnakeGauge - Graphics

Property bool SnakeGauge::PreciseDrawing: when true, exact drawing of the ribbon edges is done; otherwise, a fast but inaccruate method is used


Member of the class SnakeGauge - Graphics

Method SnakeGauge::Draw: draws the snake gauge geometry

void Draw(bool Axis = true, bool Handles = true, bool BreadthHandles = false);

bool Axis: if true, the snake axis is drawn

bool Handles: when true, the dragging handles are drawn too

bool BreadthHandles: if true, dragging handles to adjust the breadth are also drawn


Member of the class SnakeGauge - Graphics

Method SnakeGauge::DrawEdge: if true,draws the detected edge points

void DrawEdge(bool Profiles = false, bool Crosses = false);

bool Profiles: draws the segments along which the image is sampled

bool Crosses: when true, crosses drawn on the edge points rather than edge curves


Member of the class SnakeGauge - Graphics

Method SnakeGauge::DrawRibbon: draw the geometry of the snake gauge, including outer edges

void DrawRibbon(bool Profiles = false, bool Crosses = false);

bool Profiles: draws the segments along which the image is sampled

bool Crosses: when true, crosses drawn on the edge points rather than edge curves


Member of the class SnakeGauge - Graphics

Method SnakeGauge::DrawFit: draws the fitted sections; CAUTION: currently does not apply to spline sections

void DrawFit();


Struct SectionData

Description of a Snake section; reserved for internal use

Property Type: section type, as defined by the enumeration SectionType

Property BegSubsection: RESERVED; index of the initial subsection of this section

Property NumSubsections: RESERVED; number of subsections of this section

Property BegProfile: starting index of a profile; reserved for internal use

Property NumProfiles: number of profiles for this section; reserved for internal use

Property NumPoints: RESERVED; total number of points in this section

Property NumIntrusions: number of intrusions for this section; reserved for internal use

Property NumProtrusions: number of protrusions for this section; reserved for internal use

Property Deviation: standard deviation for this section; reserved for internal use

Property Beg: starting point of the clipped curve

Property End: ending point of the clipped curve

Property Center: center - Circular section only

Property Radius: radius - Circular section only


Member of the class SectionData

Property SectionType SectionData::Type: section type, as defined by the enumeration SectionType


Member of the class SectionData

Property int SectionData::BegSubsection: RESERVED; index of the initial subsection of this section


Member of the class SectionData

Property int SectionData::NumSubsections: RESERVED; number of subsections of this section


Member of the class SectionData

Property int SectionData::BegProfile: starting index of a profile; reserved for internal use


Member of the class SectionData

Property int SectionData::NumProfiles: number of profiles for this section; reserved for internal use


Member of the class SectionData

Property int SectionData::NumPoints: RESERVED; total number of points in this section


Member of the class SectionData

Property int SectionData::NumIntrusions: number of intrusions for this section; reserved for internal use


Member of the class SectionData

Property int SectionData::NumProtrusions: number of protrusions for this section; reserved for internal use


Member of the class SectionData

Property double SectionData::Deviation: standard deviation for this section; reserved for internal use


Member of the class SectionData

Property XY SectionData::Beg: starting point of the clipped curve


Member of the class SectionData

Property XY SectionData::End: ending point of the clipped curve


Member of the class SectionData

Property XY SectionData::Center: center - Circular section only


Member of the class SectionData

Property double SectionData::Radius: radius - Circular section only


Class CloudInspector

Comparison of a point cloud to a template

Constructor CloudInspector: creates a void CloudInspector object

Destructor ~CloudInspector: destroys the object

Matching

Property Inliers: proportion of the points considered inliers for robust matching; by default 1 (100%) means all (no outliers)

Property MaxIterations: maximum number of iterations in the fine search

Property Progressive: when true, as by default, the early iterations are made with less points to accelerate the processing

Property UseNormals: when true, as by default, normals are computed at every vertex of the cloud; this gives a better accuracy for smooth surfaces

Method Match: Locate a template over the source from a close position

Property MaxLocations: Maximum number of instances to look for

Method Find: Locate one or more templates over the source

Property NumLocations: Number of instances found

Found Locations

Method Location: Pose information of the template wrt the source

Comparison

Method Compare: evaluates the distances between all points of the template and the source cloud and reports statistics on them

File storage

Method ReadCloud: read the point cloud from a 3D file; currently the STL format is supported

Method WriteCloud: write the point cloud to a file; currently the STL format is supported; only possible for a mesh

Method Read: read a 3D inspection context from a file; that includes the object template

Method Write: write a 3D inspection context to a file; that includes the object template


Member of the class CloudInspector

Constructor CloudInspector::CloudInspector: creates a void CloudInspector object

CloudInspector();


Member of the class CloudInspector - Comparison

Method CloudInspector::Compare: evaluates the distances between all points of the template and the source cloud and reports statistics on them

void Compare(PointCloud& Src, double Tolerance, int LocationIndex = 0, bool MeshDeviations = true, bool TemplateDeviations = false);

PointCloud& Src: subject of the search

double Tolerance: distance threshold to detect points out of tolerance

int LocationIndex: Index of the matched template instance

bool MeshDeviations: when true, as by default, the deviating points of the Mesh are set to the Deselected state

bool TemplateDeviations: when false, as by default, the deviating points of the Template are set to the Deselected state


Member of the class CloudInspector - Matching

Method CloudInspector::Find: Locate one or more templates over the source

void Find(PointCloud& Src, SearchingPolicy Policy = VolumeSearch);

PointCloud& Src: Source point cloud

SearchingPolicy Policy: method used to search for template instances


Member of the class CloudInspector - Matching

Property double CloudInspector::Inliers: proportion of the points considered inliers for robust matching; by default 1 (100%) means all (no outliers)


Member of the class CloudInspector - Found Locations

Method CloudInspector::Location: Pose information of the template wrt the source

Pose3& Location(int LocationIndex = 0);

returned Pose3&: Pose information

int LocationIndex: Index of the found template instance


Member of the class CloudInspector - Matching

Method CloudInspector::Match: Locate a template over the source from a close position

void Match(PointCloud& Src);

PointCloud& Src: Source point cloud


Member of the class CloudInspector - Matching

Property int CloudInspector::MaxIterations: maximum number of iterations in the fine search


Member of the class CloudInspector - Matching

Property int CloudInspector::MaxLocations: Maximum number of instances to look for


Member of the class CloudInspector - Matching

Property int CloudInspector::NumLocations: Number of instances found


Member of the class CloudInspector - Matching

Property bool CloudInspector::Progressive: when true, as by default, the early iterations are made with less points to accelerate the processing


Member of the class CloudInspector - File storage

Method CloudInspector::Read: read a 3D inspection context from a file; that includes the object template

void Read(const char* PathName);

char* PathName: full file path and name; .ci3 extension recommended

Method CloudInspector::Read: read a 3D inspection context from a file; that includes the object template

void Read(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .ci3 extension recommended


Member of the class CloudInspector - File storage

Method CloudInspector::ReadCloud: read the point cloud from a 3D file; currently the STL format is supported

void ReadCloud(const char* PathName, bool PointsOnly = false);

char* PathName: full ANSI or UNICODE path and name of the file

bool PointsOnly: when true, only points are read; faces are ignored and the result is not a mesh

Method CloudInspector::ReadCloud: read the point cloud from a 3D file; currently the STL format is supported

void ReadCloud(const wchar_t* PathName, bool PointsOnly = false);

wchar_t* PathName: full ANSI or UNICODE path and name of the file

bool PointsOnly: when true, only points are read; faces are ignored and the result is not a mesh


Member of the class CloudInspector - Matching

Property bool CloudInspector::UseNormals: when true, as by default, normals are computed at every vertex of the cloud; this gives a better accuracy for smooth surfaces


Member of the class CloudInspector - File storage

Method CloudInspector::Write: write a 3D inspection context to a file; that includes the object template

void Write(const char* PathName);

char* PathName: full file path and name; .ci3 extension recommended

Method CloudInspector::Write: write a 3D inspection context to a file; that includes the object template

void Write(const wchar_t* PathName);

wchar_t* PathName: full file path and name; .ci3 extension recommended


Member of the class CloudInspector - File storage

Method CloudInspector::WriteCloud: write the point cloud to a file; currently the STL format is supported; only possible for a mesh

void WriteCloud(const char* PathName, bool AsciiFormat = false);

char* PathName: full ANSI or UNICODE path and name of the file

bool AsciiFormat: encodes data in a human-readable format (less compact)

Method CloudInspector::WriteCloud: write the point cloud to a file; currently the STL format is supported; only possible for a mesh

void WriteCloud(const wchar_t* PathName, bool AsciiFormat = false);

wchar_t* PathName: full ANSI or UNICODE path and name of the file

bool AsciiFormat: encodes data in a human-readable format (less compact)


Member of the class CloudInspector

Destructor CloudInspector::~CloudInspector: destroys the object

~CloudInspector();


Class PointCloud

Unstructured set of 3D points representing a surface; it can be augmented with triangular faces to form a mesh

Constructor PointCloud: creates a void PointCloud object

Destructor ~PointCloud: destroys the object

Point/face storage

Method Clear: Delete all points and faces from the cloud

Method AppendPoint: Add a single point to the cloud

Method fPoint: Add a single point of given coordinates

Method fNormal: tell the normal vector at the given point; the vector is of type fXYZ

Method AppendFace: add a trianglular face, specified by three point indexes

Method AppendPoints: Add the points from another cloud; no face is transferred

Method AppendMesh: Add the points from another cloud; the faces are transferred as well

Property NumSelectedFaces: total number of faces currently selected

Property NumFaces: total number of faces; nonzero for a mesh

Measurement

Method MinMax: compute the axis-aligned bounding box of the cloud

Property Centroid: computes the gravity center of the cloud, where all points have a unit weight

Method Ellipsoid: computes the equivalent ellipsoid of inertia of the cloud, where all points have a unit weight

Method Length: distance between the farthest points in a given direction

Property Area: surface area, evaluated as the sum of the areas of the faces

Property Volume: total enclosed volume, assuming a closed surface

Point/face selection

Method SelectAll: set all points/faces to the selected state

Method ByPathSelect: selects points and whole faces based on their 2D projection, using a polygonal windows

Transformation

Method Triangulate: automatically build a surface made of connected triangles, from a raw point cloud

Method Move: applies a rotation and a translation to all points of the cloud

File storage

Method FromRangeImage: creates a point cloud or mesh from an image by taking the pixel values for an elevation component (Z)

Method Read: read the point cloud from a 3D file; currently the STL format is supported

Method Write: write the point cloud to a file; currently the STL format is supported; only possible for a mesh

Graphics

Property NoFrame: placeholder argument to avoid the drawing of a fame around the cloud

Method Draw: Draw a representation of the cloud to an image; the points/faces are drawn in the current FillColor

Method Dump: output a textual description of the content


Member of the class PointCloud - Point/face storage

Method PointCloud::AppendFace: add a trianglular face, specified by three point indexes

void AppendFace(int I0, int I1, int I2);

int I0: first vertex index

int I1: second vertex index

int I2: third vertex index


Member of the class PointCloud - Point/face storage

Method PointCloud::AppendMesh: Add the points from another cloud; the faces are transferred as well

void AppendMesh(const PointCloud& Cloud);

PointCloud& Cloud: source point cloud


Member of the class PointCloud - Point/face storage

Method PointCloud::AppendPoint: Add a single point to the cloud

void AppendPoint(fXYZ Point);

fXYZ Point: point coordinates


Member of the class PointCloud - Point/face storage

Method PointCloud::AppendPoints: Add the points from another cloud; no face is transferred

void AppendPoints(const PointCloud& Cloud, int PointIndex = AllSelected);

PointCloud& Cloud: source point cloud

BlobSelection PointIndex: index of the desired point, or one of All, AllSelected, AllDeselected


Member of the class PointCloud - Measurement

Property double PointCloud::Area(): surface area, evaluated as the sum of the areas of the faces


Member of the class PointCloud - Point/face selection

Method PointCloud::ByPathSelect: selects points and whole faces based on their 2D projection, using a polygonal windows

void ByPathSelect(double Phi, double Psi, dXYZ Viewed, double Scale, int Width, int Height, const Path& Outline, enum SelectionMode Selection = Select, enum RangeMode Range = Inside);

double Phi: azimuthal viewing angle

double Psi: elevation viewing angle

dXYZ Viewed: coordinates of the viewed point (maps to the center of the screen)

double Scale: viewing magnification; can be anisotropic

int Width: number of pixels, horizontally

int Height: number of pixels, vertically

Path& Outline: polygon that defines the clipping windows

SelectionMode Selection: the rule to update the selected objects list, an enumerated value in SelectionMode; one of Add, Select, Remove, Deselect

RangeMode Range: the rule to compare the feature value to the selection range, an enumerated value in RangeMode; one of Inside, Outside


Member of the class PointCloud - Measurement

Property dXYZ PointCloud::Centroid(): computes the gravity center of the cloud, where all points have a unit weight


Member of the class PointCloud - Point/face storage

Method PointCloud::Clear: Delete all points and faces from the cloud

void Clear();


Member of the class PointCloud - Graphics

Method PointCloud::Draw: Draw a representation of the cloud to an image; the points/faces are drawn in the current FillColor

void Draw(double Phi, double Psi, dXYZ Viewed, double Scale, Image& Dst, bool Reset = true, int PointIndex = All, dXYZ FrameSize = NoFrame);

double Phi: First viewing angle

double Psi: Second viewing angle

dXYZ Viewed: coordinates of the viewed point, which will project in the center of the image

double Scale: scale factor applied to the points before projection, to adjust framing; typically the image size over the cloud size

Image& Dst: the destination image, which is computed by this operation

bool Reset: when true, as by default, the image is cleared before rendering; otherwise the current cloud is added, allowing to draw multiple clouds

BlobSelection PointIndex: zero-based index of a point in range [0..NumSamples-1] or one of All, AllSelected, AllDeselected; the default is All

dXYZ FrameSize: size of a frame to be drawn around the cloud, using the current LineColor; the default NoFrame disables

Method PointCloud::Draw: Draw a representation of the cloud to an image; the points/faces are drawn in the current FillColor

void Draw(double Phi, double Psi, dXYZ Viewed, double Scale, Image& Dst, Image& Z, bool Reset = true, int FaceIndex = All, dXYZ FrameSize = NoFrame, bool Wireframe = false);

double Phi: First viewing angle

double Psi: Second viewing angle

dXYZ Viewed: coordinates of the viewed point, which will project in the center of the image

double Scale: scale factor applied to the points before projection, to adjust framing; typically the image size over the cloud size

Image& Dst: the destination image, which is computed by this operation

Image& Z: image used internally as a Z buffer

bool Reset: when true, as by default, the image is cleared before rendering; otherwise the current cloud is added, allowing to draw multiple clouds

BlobSelection FaceIndex: index of a face to be drawn, in range [0..NumFaces-1], or one of All, AllSelected, AllDeselected

dXYZ FrameSize: size of a frame to be drawn around the cloud, using the current LineColor; the default NoFrame disables

bool Wireframe: if false, as by default, the faces of the mesh are filled; otherwise only edges


Member of the class PointCloud - Graphics

Method PointCloud::Dump: output a textual description of the content

void Dump(char* Name, bool Internal = false);

char* Name: name the point cloud in this output

bool Internal: output the internal data (Reserved use)


Member of the class PointCloud - Measurement

Method PointCloud::Ellipsoid: computes the equivalent ellipsoid of inertia of the cloud, where all points have a unit weight

void Ellipsoid(dXYZ& Center, dXYZ& AxisLength, dXYZ& Axis0, dXYZ& Axis1, dXYZ& Axis2);

dXYZ& Center: gravity center coordinates

dXYZ& AxisLength: lengths of the three main axis

dXYZ& Axis0: vectors from the center to the end of the longest axis

dXYZ& Axis1: vectors from the center to the end of the middle axis

dXYZ& Axis2: vectors from the center to the end of the shortest axis


Member of the class PointCloud - Point/face storage

Method PointCloud::fNormal: tell the normal vector at the given point; the vector is of type fXYZ

fXYZ& fNormal(int Index);

returned fXYZ&: the normal vector

int Index: zero-based index value to access a list of items


Member of the class PointCloud - Point/face storage

Method PointCloud::fPoint: Add a single point of given coordinates

fXYZ& fPoint(int Index);

returned fXYZ&: coordinates of the desired point

int Index: zero-based index value to access a list of items


Member of the class PointCloud - File storage

Method PointCloud::FromRangeImage: creates a point cloud or mesh from an image by taking the pixel values for an elevation component (Z)

void FromRangeImage(const Image& Src, double ZScale, int MinLevel = 0, bool PointsOnly = false);

Image& Src: the source image for this operation - remains unchanged after the operation, unless Src = Dst

double ZScale: scaling coefficients to apply to the pixel values

int MinLevel: a threshold on the values below which the pixels are ignored; the value 0 causes no pixel to be ignored

bool PointsOnly: if true, only points are added to the cloud; otherwise, faces are created between them to form a mesh


Member of the class PointCloud - Measurement

Method PointCloud::Length: distance between the farthest points in a given direction

double Length(dXYZ& Direction);

returned double: distance

dXYZ& Direction: vector in the desired version; it does not need to be unit


Member of the class PointCloud - Measurement

Method PointCloud::MinMax: compute the axis-aligned bounding box of the cloud

void MinMax(dXYZ& Center, dXYZ& Size);

dXYZ& Center: center of the bounding box

dXYZ& Size: size of the bounding box of the cloud (X = width, Y = height, Z = depth)

Method PointCloud::MinMax: compute the axis-aligned bounding box of the cloud

void MinMax(dXYZ Extreme[6]);

dXYZ Extreme[6]: coordinates of the six points that touch the axis-aligned bounding box


Member of the class PointCloud - Transformation

Method PointCloud::Move: applies a rotation and a translation to all points of the cloud

void Move(dXYZ XForm[4], bool Direct = true);

dXYZ XForm[4]: pose transformation, defined by three column vectors for a rotation and one for a translation

bool Direct: when true, as by default, the transformation is applied as is; when false, the transformation is reversed


Member of the class PointCloud - Graphics

Property dXYZ PointCloud::NoFrame: placeholder argument to avoid the drawing of a fame around the cloud


Member of the class PointCloud - Point/face storage

Property int PointCloud::NumFaces: total number of faces; nonzero for a mesh


Member of the class PointCloud - Point/face storage

Property int PointCloud::NumSelectedFaces: total number of faces currently selected


Member of the class PointCloud - 3D Inspect

Constructor PointCloud::PointCloud: creates a void PointCloud object

PointCloud();


Member of the class PointCloud - File storage

Method PointCloud::Read: read the point cloud from a 3D file; currently the STL format is supported

void Read(const char* PathName, bool PointsOnly = false);

char* PathName: full ANSI or UNICODE path and name of the file

bool PointsOnly: when true, only points are read; faces are ignored and the result is not a mesh

Method PointCloud::Read: read the point cloud from a 3D file; currently the STL format is supported

void Read(const wchar_t* PathName, bool PointsOnly = false);

wchar_t* PathName: full ANSI or UNICODE path and name of the file

bool PointsOnly: when true, only points are read; faces are ignored and the result is not a mesh


Member of the class PointCloud - Point/face selection

Method PointCloud::SelectAll: set all points/faces to the selected state

void SelectAll();


Member of the class PointCloud - Transformation

Method PointCloud::Triangulate: automatically build a surface made of connected triangles, from a raw point cloud

void Triangulate();


Member of the class PointCloud - Measurement

Property double PointCloud::Volume(): total enclosed volume, assuming a closed surface


Member of the class PointCloud - File storage

Method PointCloud::Write: write the point cloud to a file; currently the STL format is supported; only possible for a mesh

void Write(const char* PathName, bool AsciiFormat = false);

char* PathName: full ANSI or UNICODE path and name of the file

bool AsciiFormat: encodes data in a human-readable format (less compact)

Method PointCloud::Write: write the point cloud to a file; currently the STL format is supported; only possible for a mesh

void Write(const wchar_t* PathName, bool AsciiFormat = false);

wchar_t* PathName: full ANSI or UNICODE path and name of the file

bool AsciiFormat: encodes data in a human-readable format (less compact)


Member of the class PointCloud - 3D Inspect

Destructor PointCloud::~PointCloud: destroys the object

~PointCloud();


Enumeration

Enum SearchingPolicy: method used to find matching template instances

Case RandomSearch: try random positions

Case PlanarSearch: scan the surface of the subject point cloud

Case VolumeSearch: scan the whole volume of the subject point cloud

Case OverlapSearch: extend the searched volume to allow partial overlaps