Last update Sun May 11 01:02:37 2014

# dmagick.c.distort

enum DistortImageMethod: int;

The distortion method to use when distorting an image.

UndefinedDistortion

AffineDistortion

Distort the image linearly by moving a list of at least 3 or more sets of control points (as defined below). Ideally 3 sets or 12 floating point values are given allowing the image to be linearly scaled, rotated, sheared, and translated, according to those three points. See also the related AffineProjection and ScaleRotateTranslateDistortion distortions.

More than 3 sets given control point pairs (12 numbers) is least squares fitted to best match a lineary affine distortion. If only 2 control point pairs (8 numbers) are given a two point image translation rotation and scaling is performed, without any possible shearing, flipping or changes in aspect ratio to the resulting image. If only one control point pair is provides the image is only translated, (which may be a floating point non-integer translation).

This distortion does not include any form of perspective distortion.

AffineProjectionDistortion

Linearly distort an image using the given Affine Matrix of 6 pre-calculated coefficients forming a set of Affine Equations to map the source image to the destination image.

Sx,Rx,Ry,Sy,Tx,Ty

ScaleRotateTranslateDistortion

Distort image by first scaling and rotating about a given 'center', before translating that 'center' to the new location, in that order. It is an alternative method of specifying a 'Affine' type of distortion, but without shearing effects. It also provides a good way of rotating and displacing a smaller image for tiling onto a larger background (IE 2-dimensional animations).

The number of arguments determine the specific meaning of each argument for the scales, rotation, and translation operations.

#arguments meaning
1:Angle_of_Rotation
2:Scale Angle
3:X,Y Angle
4:X,Y Scale Angle
5:X,Y ScaleX,ScaleY Angle
6:X,Y Scale Angle NewX,NewY
7:X,Y ScaleX,ScaleY Angle NewX,NewY

This is actually an alternative way of specifying a 2 dimensional linear 'Affine' or 'AffineProjection' distortion.

PerspectiveDistortion

Perspective distort the images, using a list of 4 or more sets of control points (as defined below). More that 4 sets (16 numbers) of control points provide least squares fitting for more accurate distortions (for the purposes of image registration and panarama effects). Less than 4 sets will fall back to a 'Affine' linear distortion.

Perspective Distorted images ensures that straight lines remain straight, but the scale of the distorted image will vary. The horizon is anti-aliased, and the 'sky' color may be set using the -mattecolor setting.

PerspectiveProjectionDistortion

Do a Perspective distortion biased on a set of 8 pre-calculated coefficients. If the last two perspective scaling coefficients are zero, the remaining 6 represents a transposed 'Affine Matrix'.

BilinearForwardDistortion
BilinearDistortion
BilinearReverseDistortion

Bilinear Distortion, given a minimum of 4 sets of coordinate pairs, or 16 values (see below). Not that lines may not appear straight after distortion, though the distance between coordinates will remain consistent.

The BilinearForward is used to map rectangles to any quadrilateral, while the BilinearReverse form maps any quadrilateral to a rectangle, while preserving the straigth line edges in each case.

Note that BilinearForward can generate invalid pixels which will be colored using the -mattecolor color setting. Also if the quadraterial becomes 'flipped' the image may dissappear.

There are future plans to produce a true Bilinear distortion that will attempt to map any quadrilateral to any other quadrilateral, while preserving edges (and edge distance ratios).

PolynomialDistortion

ArcDistortion

Arc the image (variation of polar mapping) over the angle given around a circle.

ArgumentMeaning
arc_angle The angle over which to arc the image side-to-side
rotate_angleAngle to rotate resulting image from vertical center

The resulting image is always resized to best fit the resulting image, while attempting to preserve scale and aspect ratio of the original image as much as possible with the arguments given by the user. All four arguments will be needed to change the overall aspect ratio of an 'Arc'ed image.

This a variation of a polar distortion designed to try to preserve the aspect ratio of the image rather than direct Cartesian to Polar conversion.

PolarDistortion

Like ArcDistortion but do a complete Cartesian to Polar mapping of the image. that is the height of the input image is mapped to the radius limits, while the width is wrapped around between the angle limits.

Arguments : Rmax,Rmin CenterX,CenterY, start,end_angle

All arguments are optional. With Rmin defaulting to zero, the center to the center of the image, and the angles going from -180 (top) to +180 (top). If Rmax is given the special value of '0', the the distance from the center to the nearest edge is used for the radius of the output image, which will ensure the whole image is visible (though scaled smaller). However a special value of '-1' will use the distance from the center to the furthest corner, This may 'clip' the corners from the input rectangular image, but will generate the exact reverse of a 'DePolar' with the same arguments.

DePolarDistortion

Uses the same arguments and meanings as a Polar distortion but generates the reverse Polar to Cartesian distortion.

The special Rmax setting of '0' may however clip the corners of the input image. However using the special Rmax setting of '-1' (maximum center to corner distance) will ensure the whole distorted image is preserved in the generated result, so that the same argument to 'Polar' will reverse the distortion re-producing the original. Note that as this distortion requires the area resampling of a circular arc, which can not be handled by the builtin EWA resampling function. As such the normal EWA filters are turned off. It is recommended some form of 'super-sampling' image processing technique be used to produce a high quality result.

Cylinder2PlaneDistortion

Plane2CylinderDistortion

BarrelDistortion

Given the four coefficients (A,B,C,D) as defined by Helmut Dersch, perform a barrell or pin-cushion distortion appropriate to correct radial lens distortions. That is in photographs, make straight lines straight again.

Arguments : A B C [D [X,Y]]
or Ax Bx Cx Dx Ay By Cy Dy [X,Y]
So that it forms the function
Rsrc = r * ( A*r³ + B*r² + C*r + D )

Where X,Y is the optional center of the distortion (defaulting to the center of the image). The second form is typically used to distort images, rather than correct lens distortions.

BarrelInverseDistortion

This is very simular to BarrelDistortion with the same set of arguments, and argument handling. However it uses the inverse of the radial polynomial, so that it forms the function

Rsrc = r / ( A*r³ + B*r² + C*r + D )

Note that this is not the reverse of the Barrel distortion, just a different barrel-like radial distortion method.

ShepardsDistortion

Distort the given list control points (any number) using an Inverse Squared Distance Interpolation Method (Shepards Method). The control points in effect do 'localized' displacement of the image around the given control point (preserving the look and the rotation of the area near the control points. For best results extra control points should be added to 'lock' the positions of the corners, edges and other unchanging parts of the image, to prevent their movement.

The distortion has been likened to 'taffy pulling' using nails, or pins' stuck in a block of 'jelly' which is then moved to the new position, distorting te surface of the jelly.

ResizeDistortion

enum SparseColorMethod: int;

Determines how to fill intervening colors.

UndefinedColorInterpolate

BarycentricColorInterpolate

three point triangle of color given 3 points. Giving only 2 points will form a linear gradient between those points. The gradient generated extends beyond the triangle created by those 3 points.

BilinearColorInterpolate

Like barycentric but for 4 points. Less than 4 points fall back to barycentric.

PolynomialColorInterpolate

ShepardsColorInterpolate

Colors points biased on the ratio of inverse distance squared. Generating spots of color in a sea of the average of colors.

VoronoiColorInterpolate

Simply map each pixel to the to nearest color point given. The result are polygonal cells of solid color.

InverseColorInterpolate

Colors points biased on the ratio of inverse distance. This generates sharper points of color rather than rounded spots of ShepardsColorInterpolate Generating spots of color in a sea of the average of colors.