CImage:Class Description

CImage Class

he CImage class encapsulates functionality for working with images and CImage objects derived from other data arrays such as lua tables as well as instances of CArray and CMatrix objects. The CImage class consists of a multi-dimensional data array and properties that describe the data. Included in this rich class are tools for working with image files, doing image math operations, changing image geometry, making measurements, and working with header data. Additional methods for combining and merging images are found in the CImCombine class. Many class methods also can convert between the native table type and a CImage object.

The CImage class supports numerous Operators as a shorthand for several common operations between images and numbers In this version of MX Script, some class methods are obsolete; see Deprecated CImage Methods.

Usage

Construction

Object = CImage:new()

Object = CImage:newarray()

Destruction

Object:delete()

CImage Operators

The CImage class contains a rich collection of operators that cab greatly simply scripts. For example, assume these exist two CImage objects, I and I2. Then you might write the following: I = (I+5)^1.25 / I2.

Master Directory of CImage Methods

Construction	Create and Copy new CImage objects.
Coordinate Methods	Work with pixel and world coordinates.
Filtering Methods	Perform filtering operations such as smoothing and enhancing.
General Methods	Open files, Create, Save, and Attach images.
Geometry Methods	Perform geometric operations such as scale, rotate, expand, etc.
Image Calibration	Perform high level operations for calibrating CCD images.
Keyword Methods	Work with image headers, retrieve, and set header keywords.
Math Methods	Perform math operations such as add, exp, pow, etc.
Measurements	Perform image measurements including distance, angle, and luminance.
Pixel and Array Operations	Work with the image array, such as setting values of pixels, rows, or regions.
Synthetic Images	Create and work with synthetic images.
Accessors
Array Properties	Retrieve properties of the image array such as number of axes, data type, number of rows, etc.
Image Properties	Retrieve image properties such as name, exposure time, filter, etc.

Construction

new	Creates a new instance of a CImage object.
newarray	Creates a CImage from a Lua array (table).
Array	Extracts the CImage data into a Lua array (table).
Copy	Copies an existing CImage object into this object.
Dup	Duplicates this CImage object to a new CImage.
Attach	Attaches the pointer from an image in a CImageView.
AttachFromList	Creates a new CImage and attaches an image selected from the list of images in a CImageView.
delete	Deletes the instance of the CImage object and deletes its image from memory.

General Methods

Also see the list of methods for working with synthetic images, below.

Close	Closes the image to free memory but does not delete this CImage object.
Create	Creates an image of specified size and data type.
Display	Displays an image in a new image view window.
GetImagePtr	Returns a pointer to the Mira image object.
Open	Opens an image from a file.
Save	Saves the image to its file.
SaveAs	Saves the image to a new file name by prompting the user.
SaveTo	Saves the image to a new file name without prompting.

Synthetic Images

These methods create and manipulate synthetic images.

CreateSynth	Creates a new synthetic image using properties from an CImSynthInfo object.
SynthStarCount	Returns the number of stars created in the synthetic image.
SynthGetStar	Returns a table of data for each star created in the synthetic image.

Measurements

Angle	Returns the angle formed by the line between 2 pixel coordinates.
AngleWcs	Returns the angle formed by the line between 2 world coordinates.
AreaUnits	Returns the worldcoordinate units for area measurements.
DistanceWcs	Returns the distance between 2 worldcoordinates.
Distance	Returns the distance between 2 pixel coordinates.
DistanceUnits	Returns the world coordinate units for distance measurements.
DistanceWcsStr	Returns as a string the distance between 2 world coordinates.

Coordinate Methods

CoordOf	Returns the 1-based coordinates of alinear pixel offset into the image array. This is the inverse of the Pos method.
CoordUnits	Returns the coordinate units for an image axis.
GetAxisLabel	Returns the coordinate label for an image axis.
GetImageScale	Returns the image scale in world coordinates per pixel.
GetImageScaleXy	Returns the x and y axis image scale of the x and y axis in world coordinates per pixel.
Pos	Returns the linear array position of the specified pixel coordinates. This is the inverse of the CoordOf method.
FindFirst	Returns the linear array position of the first element satisfying a comparison with threshold values.
PixGE	Returns the coordinates of the first pixel with value >= target value.
PixGELE	Returns the coordinates of the first pixel with value >= value1 or <= value2.
PtInside	Returns true if a pixel coordinate is inside the image.
WcsToXy	For a worldcoordinate, returns the pixel coordinate.
WcsIsEq	Returns true if the image has an equatorial world coordinate calibration.
XyToWcs	For a pixel coordinate, returns the world coordinate in numeric form.
XyToWcsStr	For a pixel coordinate, returns the world coordinate in string form.

Pixel and Array Operations

CompareEQ	Compares whether all the image pixels are equal to the values of another other image. Also see the == operator in Math Operators.
CompareLE	Compares whether all the image pixels are less than or equal to the values of another image. Also see the <= operator in Math Operators.
CompareLT	Compares whether all the image pixels are less than the values of another image. Also see the < operator in Math Operators.
ExtractByte	Extracts an image consisting of a specific byte plane.
ExtractChan	Creates an image consisting of a color channel from an RGB image.
Get	Returns the pixel value at a pixel coordinate in the form of a number. This works for images of any data type.
Getn	Returns the pixel value from a numeric image at a pixel coordinate in the form of a number.
Getr	Returns the pixel value from an RGB image at a pixel coordinate in the form of a string.
Gets	Returns the image value at a pixel coordinate in the form of a string. This works for images of any data type.
ExtractChan	Creates an image consisting of a color channel from an RGB image.
SetColumn	Sets the values in an image column to those in a table or to a single value.
SetRegion	Sets the pixels in a rectangular region to the values in a Lua table or to a value with or without noise.
SetRegionVal	Sets the values of pixels inside a rectangular region.
SetRow	Sets the values in an image row to those in a table or to a single value.
Set	Sets a pixel value at a pixel coordinate.
Setn	Sets a pixel value for a numeric data type image.
Setr	Sets a pixel value for an RGB data type image.

Math Methods

Abs	Computes the absolute value of the image pixels.
Add	Adds an image or value.
AddNoise	Adds Gaussian random noise to a region.
Blend	Blends the values of the image with an operand image.
Byteswap	Swaps the byte order of the pixels.
Chs	Changes the sign of the image values.
Div	Divides by another image or value.
Exp	Raises the base e to powers defined by the image pixels.
ExtractByte	Extracts an image consisting of a specific byte plane.
Log	Computes the base e logarithm of the pixel values.
Log10	Computes the base 10 logarithm of the pixel values.
Mod	Calculates the remainder of division by an image or value.
Mul	Multiplies by an image or value.
PixGE	Returns the coordinate of the first pixel with value >= target value.
PixGELE	Returns the coordinate of the first pixel with value >= value or <= value 2.
PolyFitSub	Fits and subtracts a polynomial from the image.
PolyFitDiv	Fits and divides a polynomial into the image.
PolyFitImage	Fit a polynomial and evaluate it in the image.
Pow	Raises the image values to a power. The power may be a number or the pixels of another image of identical dimensions.
Powa	Raises a base value to powers defined by the image pixels.
Recip	Computes the reciprocal of the pixel values.
ExtractChan	Creates an image consisting of a color channel from an RGB image.
ScaleLinVal	Applies a linear scaling to the pixel values.
ScalePolyVal	Applies a polynomial intensity correction.
SetColumn	Sets the values in an image column to those in a table or to a single value.
SetDatatype	Changes the image Data type specified by an index value.
SetRegion	Sets the pixels in a rectangular region to the values in a Lua table or to a value with or without noise.
SetRegionVal	Sets the values of pixels inside a rectangular region.
SetRow	Sets the values in an image row to those in a table or to a single value.
Set	Sets the value at the specified pixel coordinates.
Sqrt	Computes the square root of the image values.
Sub	Subtracts an image or value.
Xdiv	Divides the image values into a numeric value.
Xsub	Subtracts the image values from a numeric value.

Geometry Methods

Affine	Applies an affine transformation of shift, scale, and rotation.
BlockAvg	Averages pixel values into m x n super-pixels.
BlockSum	Sums pixel values into m x n super-pixels.
Crop	Crops the image to a smaller size along one or more axes.
DimEq	Tests whether two images have the same dimensions.
Expand	Expands the image to larger dinension along one or more axes. The image also can be shifted along the expansion axis as part of the operation.
Expand1d	Expands a 1-D image. The image also can be shifted along the column direction as part of the operation.
Expand2d	Expands a 2-D image along an axis. The image also can be shifted as part of the operation.
Hflip	Flips the image horizontally.
Imbed	Imbeds another image at a specified location.
Mirror	Reverses the image about one or more axes.
Offset	Offsets the image by an integral number of elements along one or more axes.
Offset1d	Offsets the image by an integral number of elements along the column axis.
Offset2d	Offsets the image by an integral number of elements along the column and row axes.
Reorient	Reorients the image in various quadrant transformations.
Rot180	Rotates the image 180 degrees about the chosen axes.
Rot270	Rotates the image 270 degrees about the chosen axes.
Rot90	Rotates the image 90 degrees about the chosen axes.
Rotate	Rotates the image by an angle about its center.
RotatePt	Rotates the image by an angle about a point.
Scale	Scales the image by a magnification factor.
ScaleXy	Scales the image independently by magnification factors in the x and y directions.
Shift	Shifts the image about the chosen axes.
Transpose	Flips the image about the main diagonal of the chosen axes.
Vflip	Flips the image vertically.

Keyword Methods

KwdDelete	Deletes a keyword from the image header.
KwdExists	Returns true if the named keyword exists in the image header.
KwdGetDMS	Returns a properly formatted angle string for a keyword value given in degrees, minutes, and seconds. Use this for keywords not in the standard format using : as a field delimiter.
KwdGetDmsEx	Returns a DMS angle for a string keyword plus a boolean flag indicating that the keyword is in the image header.
KwdGetHMS	Returns a MHS time string for a string keyword value given in hours, minutes, and seconds. Use this for keywords not in the standard format using : as a field delimiter.
KwdGetHmsEx	Returns an HMS time for a string keyword plus a boolean flag indicating that the keyword is in the image header.
KwdGetNum	Returns a numeric value keyword.
KwdGetNumEx	Returns a numeric value keyword plus a boolean flag indicating that the keyword is in the image header.
KwdGetSect	Returns the 4 column and row limits stored in a region section keyword, like BIASSEC.
KwdGetSectEx	Returns the 4 column and row limits stored in a region section keyword (e.g., BIASSEC), plus a boolean flag indicating that the keyword is in the image header.
KwdGetStr	Returns a string value keyword.
KwdGetStrEx	Returns a string value keyword plus a boolean flag indicating that the keyword is in the image header.
KwdGetVal	Returns the value of a keyword in any format (string, number, etc.) as a string.
KwdGetValEx	Returns the value of a keyword in any format (string, number, etc.) as a string and also a boolean flag indicating that the keyword is in the header.
KwdSetBlank	Adds a blank keyword to the image header.
KwdSetBlankStr	Adds a blank keyword with string value to the image header.
KwdSetBool	Sets the value of a boolean T/F keyword or adds the keyword to the image header.
KwdSetComment	Adds a comment keyword to the image header.
KwdSetDate	Sets the value of a date keyword or adds the keyword to the image header.
KwdSetHistory	Adds a history keyword to the image header.
KwdSetNum	Sets the value of a numeric keyword or adds the keyword to the image header.
KwdSetSect	Sets a region section keyword (e.g., BIASSEC) using the 4 column and row limits passed as numbers
KwdSetStr	Sets the value of a string keyword or adds the keyword to the image header.
KwdSetTime	Sets the value of a time keyword or adds the keyword to the image header.
KwdSetVal	Sets the value of a keyword or adds the keyword to the image header.

Image Calibration Methods

ApplyPixelMask	Applies a pixel mask to repair image blemishes.
CreatePixelMask	Creates a mask file for pixels above or below threshold values.
CreatePixelMaskHigh	Creates a mask file for pixels above a threshold value.
CreatePixelMaskLow	Creates a mask file for pixels below a threshold value.
SetMaskedValue	Sets pixel values at coordinates identified in a pixel mask.
SubBiasFrame	Subtract a bias frame from the image.
SubBiasVal	Subtract a bias value from the image.
SubBiasRef	Subtract a reference bias value stored in a header keyword.
SubBiasCol	Compute and apply a column bias correction.
SubBiasRow	Compute and apply a row bias correction.
SubDarkFrame	Subtracts a dark frame from the image.
SubDarkScaled	Subtracts a time-scaled dark frame from the image.
SubDarkOpt	Subtracts a statistically optimized dark frame from the image.
DivFlatFrame	Divides the image by a flat field frame.
DivFlatNorm	Divides the image by a flat field frame while normalizing the flat during the calculation.

Filtering Methods

FiltBinomial	Smooths the image using a binomial weight rectangular kernel.
FiltClipHigh	Replaces pixel values above a threshold value.
FiltClipLow	Replaces pixel values below a threshold value.
FiltEllipse	Smooths the image using an equal weight elliptical kernel.
FiltGaussian	Smooths the image using a Gaussian weight elliptical kernel.
FiltGradien	Applies a directional derivative gradient filter.
FiltKernel	Applies a user-defined kernel.
FiltLaplacian	Applies a Laplacian filter, usually for edge detection.
FiltLine	Applies a directional line selection kernel.
FiltMax	Applies a maximum value filter.
FiltMedian	Applies a median filter.
FiltMin	Applies a minimum value filter.
FiltPrewitt	Applies a Prewitt directional gradient mask.
FiltRank	Applies a rank value filter.
FiltRect	Smooths the image using an equal weight rectangular kernel.
FiltRotGrad	Applies a rotational gradient filter to enhance rotational or "spoked" features.
FiltSharpen	Sharpens the image using a crispening filter.
FiltSobel	Applies a Sobel edge filter.
FiltUnsharpMask	Sharpens the image using unsharp masking.

Accessor Methods

These methods return properties associated with the CImage including general properties and properties of the image data array.

Array Properties

Axes	Returns the number of image axes.
Bytes	Returns the number of bytes in the image pixel data.
Cols	Returns the number of image columns (also see Axes ).
Datatype	Returns the image data type as a string, like "double".
IsColor	Returns true if the image is a color data type.
IsInteger	Returns true if the image is an integer data type.
IsNumeric	Returns true if the image is a numeric data type.
IsReal	Returns true if the image is a real (floating point) data type.
Len	Returns the length of the specified image axis.
PixelBytes	Returns the number of bytes per pixel.
Pixels	Returns the number of pixels in the image.
Planes	Returns the number of planes in the image (also see Axes).
Rows	Returns the number of image rows (also see Axes).

Image Properties

Darktime	Returns the dark integration time for the image.
Date	Returns the date the image was acquired, in days.
DateStr	Returns the date of image acquisition as a string.
Exptime	Returns the image exposure time in seconds.
Filter	Returns the name of the filter used for image acquisition.
Gain	Returns the inverse gain in electrons per ADU.
ImageType	Returns the type of image, usually the value of the IMAGETYP keyword.
Object	Returns the object description.
Path	Returns the image file path.
Time	Returns the time of image acquisition as a number of seconds.
TimeStr	Returns the time of image acquisition as a string.

Usage

Master Directory of CImage Methods

Accessors

Construction

General Methods

Synthetic Images

Measurements

Coordinate Methods

Pixel and Array Operations

Math Methods

Geometry Methods

Keyword Methods

Image Calibration Methods

Filtering Methods

Accessor Methods

Array Properties

Image Properties