GraphicsMagick

- Home
- Project
- Download
- Install
- Source
- News
- Utilities
- Programming
- Reference

# compare

## Compare images

Contents

- DifferenceImage
- GetImageChannelDifference
- GetImageChannelDistortion
- GetImageDistortion
- IsImagesEqual
- InitializeDifferenceImageOptions
- InitializeDifferenceStatistics

# DifferenceImage

## Synopsis

    Image *DifferenceImage( const Image *reference_image, const Image *compare_image,
                            const DifferenceImageOptions *difference_options,
                            ExceptionInfo *exception );

## Description

DifferenceImage() returns an annotated difference image based on the the difference between a reference image and a compare image.

The format of the DifferenceImage method is:

    Image *DifferenceImage( const Image *reference_image, const Image *compare_image,
                            const DifferenceImageOptions *difference_options,
                            ExceptionInfo *exception );

reference_image:
  the reference image.
compare_image:
  the comparison image.
difference_options:
  options to use when differencing.
channel:
  the channel(s) to compare.
exception:
  Return any errors or warnings in this structure.

# GetImageChannelDifference

## Synopsis

    MagickPassFail GetImageChannelDifference( const Image *reference_image,
                                              const Image *compare_image,
                                              const MetricType metric,
                                              DifferenceStatistics *statistics,
                                              ExceptionInfo *exception );

## Description

GetImageChannelDifference() updates a user provided statistics structure with per-channel, and totalized, difference statistics corresponding to a specified comparison metric.

The format of the GetImageChannelDifference method is:

    MagickPassFail GetImageChannelDifference( const Image *reference_image,
                                              const Image *compare_image,
                                              const MetricType metric,
                                              DifferenceStatistics *statistics,
                                              ExceptionInfo *exception );

reference_image:
  the reference image.
compare_image:
  the comparison image.
metric:
  metric to use when differencing.
statistics:
  the statistics structure to populate.
exception:
  Return any errors or warnings in this structure.

# GetImageChannelDistortion

## Synopsis

    MagickPassFail GetImageChannelDistortion( const Image *reference_image,
                                              const Image *compare_image,
                                              const ChannelType channel,
                                              const MetricType metric, double *distortion,
                                              ExceptionInfo *exception );

## Description

GetImageChannelDistortion() updates a distortion parameter with the distortion (error) computed according to the specified comparison metric. The value returned is only for the channel specified.

The format of the GetImageChannelDistortion method is:

    MagickPassFail GetImageChannelDistortion( const Image *reference_image,
                                              const Image *compare_image,
                                              const ChannelType channel,
                                              const MetricType metric, double *distortion,
                                              ExceptionInfo *exception );

reference_image:
  the reference image.
compare_image:
  the comparison image.
channel:
  the channel to obtain error data for.
metric:
  metric to use when differencing.
distortion:
  updated with the computed distortion.
exception:
  Return any errors or warnings in this structure.

# GetImageDistortion

## Synopsis

    MagickPassFail GetImageDistortion( const Image *reference_image,
                                       const Image *compare_image, const MetricType metric,
                                       double *distortion, ExceptionInfo *exception );

## Description

GetImageDistortion() updates a distortion parameter with the distortion (error) computed according to the specified comparison metric. The value returned reflects all enabled channels.

The format of the GetImageDistortion method is:

    MagickPassFail GetImageDistortion( const Image *reference_image,
                                       const Image *compare_image, const MetricType metric,
                                       double *distortion, ExceptionInfo *exception );

reference_image:
  the reference image.
compare_image:
  the comparison image.
channel:
  the channel to obtain error data for.
metric:
  metric to use when differencing.
distortion:
  updated with the computed distortion.
exception:
  Return any errors or warnings in this structure.

# IsImagesEqual

## Synopsis

    MagickBool IsImagesEqual( Image *image, const Image *reference );

## Description

IsImagesEqual() measures the difference between colors at each pixel location of two images. A value other than 0 means the colors match exactly. Otherwise an error measure is computed by summing over all pixels in an image the distance squared in RGB space between each image pixel and its corresponding pixel in the reference image. The error measure is assigned to these image members:

o mean_error_per_pixel: The mean error for any single pixel in the image.

o normalized_mean_error: The normalized mean quantization error for any single pixel in the image. This distance measure is normalized to a range between 0 and 1. It is independent of the range of red, green, and blue values in the image.

o normalized_maximum_error: The normalized maximum quantization error for any single pixel in the image. This distance measure is normalized to a range between 0 and 1. It is independent of the range of red, green, and blue values in your image.

A small normalized mean square error, accessed as image->normalized_mean_error, suggests the images are very similiar in spatial layout and color.

The format of the IsImagesEqual method is:

    MagickBool IsImagesEqual( Image *image, const Image *reference );

A description of each parameter follows.

image:
  The image.
reference:
  The reference image.

# InitializeDifferenceImageOptions

## Synopsis

    void InitializeDifferenceImageOptions( DifferenceImageOptions *options,
                                           ExceptionInfo *exception );

## Description

InitializeDifferenceImageOptions() assigns default options to a user-provided DifferenceImageOptions structure. This function should always be used to initialize the DifferenceImageOptions structure prior to making any changes to it.

The format of the InitializeDifferenceImageOptions method is:

    void InitializeDifferenceImageOptions( DifferenceImageOptions *options,
                                           ExceptionInfo *exception );

options:
  pointer to DifferenceImageOptions structure to initialize.
exception:
  Return any errors or warnings in this structure.

# InitializeDifferenceStatistics

## Synopsis

    void InitializeDifferenceStatistics( DifferenceStatistics *options,
                                         ExceptionInfo *exception );

## Description

InitializeDifferenceStatistics() assigns default options to a user-provided DifferenceStatistics structure.

The format of the InitializeDifferenceStatistics method is:

    void InitializeDifferenceStatistics( DifferenceStatistics *options,
                                         ExceptionInfo *exception );

options:
  pointer to DifferenceStatistics structure to initialize.
exception:
  Return any errors or warnings in this structure.