Image

`Image`

Bases: ndarray

A representation of an image as a 2D array

Images can be constructed in several ways:

from numpy arrays using
```
img = Image(array)
```
loaded from an image file using
```
img = Image.load(filename)
```
pulled from a video file using
```
vidcap = cv2.VideoCapture(inputfilename)
...
img = Image.readframe(vidcap)
```
In this case, a RuntimeError is raised at end-of-file.

Our native data format is np.float32. For convenience, np.uint8 or np.uint16 is also accepted. The intensity of such images is scaled by a factor of 255 or 65535, respectively.

We do not keep color information. If YxXxC images are provided, the color channel is averaged away with equal weights for each channel.

An Image is just a numpy array with some additional methods:

Methods:

Name	Description
`apodize`	Multiply a windowing function into an image in place
`apodized`	Apodized copy of an image
`ascii`	ASCII-art copy of an image
`braille`	Braille-art copy of an image
`delta`	Difference between images
`rmsdelta`	RMS difference between images
`roi`	Extract rectangular window from an image
`save`	Save an image to a file
`scaled`	SCALED - Geometrically scale an image down by integer factor
`straightwindow`	Extract a window from an image
`stretch`	STRETCH - Stretch contrast of an image in place
`stretched`	STRETCHED - Contrast-stretched copy of an image
`transformedwindow`	Extract a window with transformation

`apodize(gray=None, force=False)`

Multiply a windowing function into an image in place

Parameters:

Name	Type	Description	Default
`gray`	`Optional[float]`	optional value to fade toward	`None`
`force`	`bool`	force an already apodized image to be apodized again.	`False`

img.apodize() multiplies the outer 1/4 of the image with a cosine fadeout to gray (defined as the mean of the image, unless specifically given as optional argument).

The call has no effect if the image has already been apodized, unless force is given as True.

This function is not threadsafe, as it stores the most recent apodization kernel for reuse.

`apodized(gray=None, force=False)`

Apodized copy of an image

im1 = img.apodized() copies the image and then applies the apodize function. If the image is already apodized, the original image is returned without copying.

`ascii(height=22)`

ASCII-art copy of an image

Parameters:

Name	Type	Description	Default
`height`	`int`	number of lines in returned image	`22`

Returns:

Name	Type	Description
`pic`	`List[str]`	a list of strings representing the image as ASCII art

img.ascii() returns a copy of the image converted to ascii art at low resolution.

Optional parameter height specifies the desired height of the output. Intended to get a quick overview for use in terminals that do not support unicode. Otherwise, braille is better.

`braille(height=88)`

Braille-art copy of an image

Parameters:

Name	Type	Description	Default
`height`	`int`	number of lines in returned image	`88`

Returns:

Name	Type	Description
`pic`	`List[str]`	a list of strings representing the image as Braille art

img.braille() returns a copy of the image converted to Braille art at low resolution.

Optional parameter height specifies the desired height of the output. Intended to get a quick overview for use in terminals that support unicode. See also ascii.

`delta(img2, margin=0.05)`

Difference between images

Parameters:

Name	Type	Description	Default
`img2`	`Image`	the image to compare to	required
`margin`	`float`	fraction of image near borders to ignore	`0.05`

Returns:

Type	Description
`Image`	The difference image

Note that the result is an image, not an average across compared pixels. To get that average, use img1.delta(img2).mean()

`rmsdelta(img2, margin=0.05)`

RMS difference between images

Parameters:

Name	Type	Description	Default
`img2`	`Image`	the image to compare to	required
`margin`	`float`	fraction of image near borders to ignore	`0.05`

Returns:

Type	Description
`float`	RMS difference across all compared pixels

rms = img1.rmsdelta(img2) calculates the RMS difference between a pair of images, ignoring edge pixels.

By default, each of the four edges is 5% of the corresponding image dimension. The margin parameter overrides the default.

`roi(rect)`

Extract rectangular window from an image win = img.roi((x0, y0, w, h)) extracts a rectangular window from an image.

x0, y0, w, and h must be integers. ROIs must fit inside the image.

`save(path, qual=None)`

Save an image to a file

Parameters:

Name	Type	Description	Default
`path`	`str`	filename to save into	required
`qual`	`int`	optional quality for jpeg files	`None`

img.save(path) saves the image img to the file named path. Optional argument qual specifies jpeg quality as a number between 0 and 100, and must only be given if path ends in ".jpg".

`scaled(fac=2)`

SCALED - Geometrically scale an image down by integer factor im1 = img.SCALED(fac) returns a version of the image IMG scaled down by the given factor in both dimensions. FAC is optional and defaults to 2. FAC must be integer. Before scaling, the image is trimmed on the right and bottom so that the width and height are a multiple of FAC. Pixels in the output image are the average of all underlying pixels in the input image.

`straightwindow(xy=None, siz=512, border=None)`

Extract a window from an image

Parameters:

Name	Type	Description	Default
`xy`	`ArrayLike`	center location of window as an (x, y)-pair	`None`
`siz`	`int`	size of the window to extract	`512`
`border`	`float`	value for pixels outside of the source image	`None`

Returns:

Type	Description
`Image`	the extracted sub image

win = img.straightwindow(xy, siz) extracts a window of size siz, centered on xy, from the given image. xy do not have to be integer-valued.

siz may be a scalar or a pair of numbers (width, height). siz defaults to 512.

If xy is not given, the window is taken from the center of the image. It is OK if the window does not fit fully inside of the image. In that case, undefined pixels are given the value of the optional border argument, or of the average of the image if not specified.

`stretch(percent=0.1)`

STRETCH - Stretch contrast of an image in place STRETCH(perc) stretches the contrast of an image in-place. PERC specifies what percentage of pixels become white or black.

`stretched(percent=0.1)`

STRETCHED - Contrast-stretched copy of an image img.STRETCHED(perc) returns a contrast-stretched copy of an image. PERC specifies what percentage of pixels become white or black.

`transformedwindow(xy=None, tfm=None, siz=512)`

Extract a window with transformation

Parameters:

Name	Type	Description	Default
`xy`	`ArrayLike`	center location of window as an (x, y)-pair	`None`
`tfm`	`ArrayLike`	transformation to apply	`None`
`siz`	`int`	size of the window to extract	`512`
`border`		value for pixels outside of the source image	required

Returns:

Type	Description
`Image`	the extracted sub image

win = img.transformedwindow(xy, tfm, siz) extracts a window of size SIZ, centered on XY, from the given image.

tfm must be a 2x2 transformation matrix. It is internally modified with a translation T such that the center point XY is not moved by the combination of translation and transformation.

siz may be a scalar or a pair of numbers (width, height). siz defaults to 512.

If tfm is not given, an identity matrix is used.

If xy is not given, the window is taken from the center of the image.

To transform an entire image, Affine.apply may be easier to use.