CImage:Expand

The Expand method enlarges an n-dimensional image in one or more dimensions. An offset also can be specified along the direction of expansion in order to shift the array elements in the direction being offset. By default, new pixels are filled with value 0. You also can specify a fill value and a noise sigma for the new pixels. Several versions are provided to allow different parameters to be specified. To work explusively with 1- and 2-dimensional images, consider using the faster methods, Expand1d and Expand2d.

Syntax

Forms in which a single axis is specified:

bSuccess = CImage:Expand( nAxis, nLength )

bSuccess = CImage:Expand( nAxis, nLength, nOffset )

bSuccess = CImage:Expand( nAxis, nLength, nOffset, sValue )

bSuccess = CImage:Expand( nAxis, nLength, nOffset, sValue, sSigma )

Forms in which multiple axes can be specified:

bSuccess = CImage:Expand( nAxis[], nLength[] )

bSuccess = CImage:Expand( nAxis[], nLength[], nOffset[] )

bSuccess = CImage:Expand( nAxis[], nLength[], nOffset[], sSigma )

bSuccess = CImage:Expand( nAxis[], nLength[], nOffset[], sValue, sSigma )

where

nAxis and nAxis[] specify the axis or a list of axes to expand.

nLength and nLength[] are the new number of elements (pixels) along the expansion axis or axes.

nOffset and nOffset[] are the number of elements (pixels) to offset the existing data along the expansion axis or axes. If not specified, no offset is applied.

sValue is the noise sigma used for blank pixels created by the expansion or offset.

sSigma is the optional noise sigma for blank pixels created by the expansion or offset.

bSuccess is the returned success code. On success it is true, otherwise false.

This method creates a new, larger image that extends the borders with a value and optional random noise. The scale of the image is not changed, but the existing image is imbedded into a larger canvas. The new size and the position of the current image are encoded in the members of a CRect as follows:

Let xmax = new column dimension, in pixels.

Let ymax = new row dimension, in pixels.

Let xmin = X (column) offset in the expanded image.

Let ymin = Y (row) offset in the expanded image.

Use CRect:Set( xmin, xmax, ymin, ymax ) or an equivalent method to initialize the CRect.

If you do not want to add random noise to the border region, set noise=0 or omit the value from the argument list.

Example

Suppose that a CImage I exists. The following script doubles its width and height and centers the current image in the new image. The new background value is 1000 and the noise sigma is 8.25:

nCols = I:Cols() * 2	-- new width in pixels
nRows = I:Rows() * 2	-- new height in pixels
cOff = I:Cols() / 4	-- new edge at 1/4 of column dimension
rOff = I:Rows() / 4	-- new edge at 1/4 of row dimension
R = NewRect()	-- create a rectangle
R:Set(cOff,nCols,rOff,nRows)
I:Expand( R, "100", 8.25 )	-- perform the operation on image I