Image Alignment

Image Alignment.

Public Functions

Type	Name
int	SaigeInitializeAlignModule (const int gpuIndex, const int sourceWidth, const int sourceHeight, const int targetWidth, const int targetHeight) Function to activate the Saige Alignment function with the default preset (prototype_a).
int	SaigeInitializeAlignModuleWithPreset (const int gpuIndex, const int sourceWidth, const int sourceHeight, const int targetWidth, const int targetHeight, const char * preset) Function to activate the Saige Alignment function with a specified alignment preset.
int	SaigeFinalizeAlignModule () Function to terminate the Saige Alignment function. Releases the GPU memory used by the function.
int	SaigeAlignImageFromByteArray (const unsigned char * sourceImage, const int sourceWidth, const int sourceHeight, const int sourceChannel, const unsigned char * targetImage, const int targetWidht, const int targetHeight, const int targetChannel, unsigned int flag, unsigned char * croppedSourceImage) Function to adjust the position of the Source image to match the Target image.
int	SaigeAlignImageFromByteArrayWithCoord (const unsigned char * sourceImage, const int sourceWidth, const int sourceHeight, const int sourceChannel, const unsigned char * targetImage, const int targetWidht, const int targetHeight, const int targetChannel, unsigned int flag, unsigned char * croppedSourceImage, int * cropCoords) Extended variant of SaigeAlignImageFromByteArray that also returns the pixel coordinates of the crop box applied to the Source image.
int	SaigeAlignImageFromFile (const char * sourceImagePath, const char * targetImagePath, int * cropWidth, int * cropHeight, int * cropChannel, unsigned char * croppedSourceImage) Not Implemented.

Public Functions Documentation

SaigeInitializeAlignModule

Function to activate the Saige Alignment function with the default preset (prototype_a).

int SaigeInitializeAlignModule (
    const int gpuIndex,
    const int sourceWidth,
    const int sourceHeight,
    const int targetWidth,
    const int targetHeight
) 

Equivalent to SaigeInitializeAlignModuleWithPreset(gpuIndex, ..., nullptr). prototype_a adjusts the position of the Source image to match the Target image and crops it, so the Source image must be larger than the Target image. Use SaigeInitializeAlignModuleWithPreset for other alignment methods.

Parameters:

• gpuIndex Index of the GPU to use. Pass -1 to use the CPU.
• sourceWidth Width of the Source image.
• sourceHeight Height of the Source image.
• targetWidth Width of the Target image.
• targetHeight Height of the Target image.

Returns:

errorCode Returns 0 on success, or an error code if there is a failure.

SaigeInitializeAlignModuleWithPreset

Function to activate the Saige Alignment function with a specified alignment preset.

int SaigeInitializeAlignModuleWithPreset (
    const int gpuIndex,
    const int sourceWidth,
    const int sourceHeight,
    const int targetWidth,
    const int targetHeight,
    const char * preset
) 

Behavior per preset: * prototype_a (default): scan↔ODB, Source > Target. Crops a Target-sized region from the Source (GPU capable) * scan_odb_mutual_information: img↔odb, Source = Target. Mutual-information based translation * scan_scan_correlation: img↔img (different lighting), Source = Target. Correlation based translation

The translation presets (scan_odb_mutual_information, scan_scan_correlation) do not use a model and run on the CPU regardless of gpuIndex. If the Source and Target sizes differ, error code -419302 is returned. See SaigeAlignImageFromByteArrayWithCoord for the meaning of the aligned image and coordinates. The alignment module keeps a single preset per process; calling this function again releases the previous configuration and initializes the new preset.

Parameters:

• gpuIndex Index of the GPU to use. Pass -1 to use the CPU.
• sourceWidth Width of the Source image.
• sourceHeight Height of the Source image.
• targetWidth Width of the Target image.
• targetHeight Height of the Target image.
• preset Preset name or path to a .saigealign file. A name resolves to SAIGE_HOME/SaigeVision/module/SaigeAlignment/checkpoint/<preset>.saigealign. nullptr or an empty string selects prototype_a.

Returns:

errorCode Returns 0 on success, or an error code if there is a failure. Returns FILE_NOT_FOUND if the preset file does not exist.

SaigeFinalizeAlignModule

Function to terminate the Saige Alignment function. Releases the GPU memory used by the function.

int SaigeFinalizeAlignModule () 

Returns:

errorCode Returns 0 on success, or an error code if there is a failure.

SaigeAlignImageFromByteArray

Function to adjust the position of the Source image to match the Target image.

int SaigeAlignImageFromByteArray (
    const unsigned char * sourceImage,
    const int sourceWidth,
    const int sourceHeight,
    const int sourceChannel,
    const unsigned char * targetImage,
    const int targetWidht,
    const int targetHeight,
    const int targetChannel,
    unsigned int flag,
    unsigned char * croppedSourceImage
) 

The result has the Target size, so croppedSourceImage must hold targetWidth * targetHeight * sourceChannel bytes. The result is returned in RGB order regardless of the input channel order. See SaigeInitializeAlignModuleWithPreset for the behavior of each preset.

Parameters:

• sourceImage The byte array of the Source image.
• sourceWidth The width of the Source image.
• sourceHeight The height of the Source image.
• sourceChannel The channel of the Source image.
• targetImage The byte array of the Target image.
• targetWidht The width of the Target image.
• targetHeight The height of the Target image.
• targetChannel The channel of the Target image.
• flag Input image flag. Specify SAIGE_IMAGE_BGR when the inputs are in BGR order (e.g. OpenCV cv::imread); otherwise RGB order is assumed.
• croppedSourceImage The byte array that receives the Source image aligned to the Target.

Returns:

errorCode Returns 0 on success, or an error code if there is a failure.

SaigeAlignImageFromByteArrayWithCoord

Extended variant of SaigeAlignImageFromByteArray that also returns the pixel coordinates of the crop box applied to the Source image.

int SaigeAlignImageFromByteArrayWithCoord (
    const unsigned char * sourceImage,
    const int sourceWidth,
    const int sourceHeight,
    const int sourceChannel,
    const unsigned char * targetImage,
    const int targetWidht,
    const int targetHeight,
    const int targetChannel,
    unsigned int flag,
    unsigned char * croppedSourceImage,
    int * cropCoords
) 

Alignment behaves identically to SaigeAlignImageFromByteArray; additionally, the Source region placed in the result image is written to cropCoords as (x1, y1, x2, y2) in Source-image coordinates. The legacy symbol is kept for backward compatibility — use this variant only when coordinates are required. * prototype_a: the region cropped from the Source; always inside the Source bounds. * scan_odb_mutual_information / scan_scan_correlation: the Source is translated by (dx, dy), and the coordinates are (-dx, -dy, W - dx, H - dy), which may be negative or exceed W, H. Parts shifted out of the result are clipped and empty areas are filled with 0. If alignment fails, the original Source and (0, 0, W, H) are returned, which cannot be distinguished from an actual zero shift.

Parameters:

• cropCoords An int[4] output array that receives the pixel coordinates (x1, y1, x2, y2) of the Source region placed in the result image. Pass nullptr if the coordinates are not needed.

Returns:

errorCode Returns 0 on success, or an error code if there is a failure.

SaigeAlignImageFromFile

Not Implemented.

int SaigeAlignImageFromFile (
    const char * sourceImagePath,
    const char * targetImagePath,
    int * cropWidth,
    int * cropHeight,
    int * cropChannel,
    unsigned char * croppedSourceImage
)