pts.visual.rgbimage.RGBImage Class Reference

An instance of the RGBImage class represents a single RGB color image, i.e. More...

Public Member Functions
	__init__ (self, source, frameIndices=None)
	The constructor creates a new RGBImage from the source specified by the sole argument, as follows:
	addBelow (self, image)
	This function places the specified RGBImage below the receiving image.
	addRight (self, image)
	This function places the specified RGBImage to the right of the receiving image.
	applyColorMap (self, cmap)
	This function applies the specified color map to the (scaled) pixel values of the red channel, and replaces the image data with the result.
	applyCurve (self, point1=(0.25, 0.16), point2=(0.80, 0.86))
	This function applies a transformation defined by a cubic spline curve to the (scaled) pixel values, and replaces the image data with the result.
	applyLog (self)
	This function applies the natural logarithm function to the pixel values of the image, and adjusts the pixel range accordingly.
	applySqrt (self)
	This function applies the square root function to the pixel values of the image, and adjusts the pixel range accordingly.
	bytesArray (self)
	This function returns the image's pixel data as a bytes object in the rgba format that can also be obtained from mtplotlib (3 RGB channels plus a dummy alpha channel, 8 bits each).
	enlargeCanvas (self, shape)
	This function adds pixel rows and/or columns to the receiving image if needed to match a given shape.
	percentilePixelRange (self, from_percentile=0, to_percentile=100)
	This function determines the range of the image's pixel values, ignoring zero and negative values, and omitting outliers on both sides of the scale as specified by the from and to percentiles.
	pixelArray (self)
	This function returns the image's pixeldata as a 3D numpy array with shape (nx, ny, 3).
	pixelRange (self)
	This function returns the range of the image's pixel values as a tuple (min, max).
	plot (self, fill=False)
	This function plots the image to the current axes in the current matplotlib figure.
	saveTo (self, outFilePath, tiff16bit=False)
	This function saves the image to a file with the specified /em outFilePath in one of the supported formats.
	scaledPixelArray (self, newmin, newmax)
	This function returns the image's pixel data as a 3D numpy array with shape (nx, ny, 3), after scaling the data to the specified range, but without affecting the data in the image itself.
	scaleValues (self, newmin, newmax)
	This function applies a linear transformation to the pixel values and to the pixel value range, such that the previous range is exactly mapped onto the new specified range.
	setRange (self, newmin=None, newmax=None)
	This function changes the pixel value range without affecting the actual pixel values except that, if the new range is smaller than the previous range, the pixel values are clipped to the new range.
	shape (self)
	This function returns the image's shape as a tuple (nx, ny).

Protected Member Functions
	_ensureArr (self, invalidate=True)
	This private function ensures that there is a valid numpy array representation, converting from one of the other representations if necessary, and invalidating the other representations if requested.
	_ensureBuf (self, invalidate=True)
	This private function ensures that there is a valid buffer representation, converting from one of the other representations if necessary, and invalidating the other representations if requested.
	_ensurePil (self, invalidate=True)
	This private function ensures that there is a valid PIL image representation, converting from one of the other representations if necessary, and invalidating the other representations if requested.
	_setArr (self, arr)
	This private function sets the specified numpy array as internal representation, invalidating the other representations.
	_setBuf (self, buf)
	This private function sets the specified RGBA buffer or string as internal representation, invalidating the other representations.
	_setPil (self, pil)
	This private function sets the specified PIL image as internal representation, invalidating the other representations.

Protected Attributes
	_darr
	_dbuf
	_dpil
tuple	_rangearr
	_shape

Detailed Description

An instance of the RGBImage class represents a single RGB color image, i.e.

a 2D array of pixels with three color values per pixel. The class allows arbitrary floating point color values, and supports conversion to and from more standard image representations using 8-bit or 16-bit integer values. The floating point representation offers a wide dynamic range and enables computations on pixel values, such as rescaling by applying a log function. It is the natural representation for working with color planes loaded from frames in a FITS file. The integer representation is relevant to standard image processing, for example to load or store a color image as a PNG file.

RGBImage properties include the shape of the image (number of horizontal pixels, number of vertical pixels), the range of the pixel values (minimum value, maximum value), and some representation of the pixel data itself. To avoid unnecessary conversions, and to keep the image representation as general as possible, an RGBImage maintains several variants of the pixel data. Conversions between these data types happen only when needed and are transparent to the user.

The implementation maintains the following variants of the pixel data:

• a PIL.Image instance representing a standard pixel image, used to support various image file formats;
• a buffer with RGBA pixels, as can be extracted from a matplotlib Figure instance;
• a numpy array with shape (nx, ny, 3) of floating point value type.

An RGBImage can be created from the following sources:

• an image file in one of these formats: JPEG, PNG, TIFF;
• a FITS file with one or more data frames;
• a matplotlib figure generated using an AGG back-end;
• a 3D numpy array with shape (nx, ny, 3).

An RGBImage can be repurposed as follows:

• save to an image file in one of these formats: JPEG, PNG, TIFF, PDF;
• save to a FITS file with three data frames;
• plot to the current matplotlib figure;
• get pixeldata as a 3D numpy array with shape (nx, ny, 3).

Other functions include:

• apply the log function to the pixel values and their range;
• change the pixel range without scaling the values, but clipping the values where needed;
• scale pixel values to a new range (this happens automatically during some conversions).

There are several private properties:

• shape: a 2-tuple of integer numbers specifying the number of horizontal and vertical pixels in the image;
• data properties dpil, dbuf, darr: representation of the pixel data, each in its own specific way;
• rangearr: a 2-tuple of floating point numbers specifying the minimum and maximum allowed pixel value.

A data property either holds a relevant value or it set to None. At all times, at least one data property holds a relevant value; if multiple data properties hold a relevant value, they represent the exact same image.

The allowed range for pixel values in the dpil and dbuf representations is fixed to 0..255 and thus does not need to be explicitly stored. For pixel data in the form of a numpy array however, the allowed range is flexible, and may be larger than the range actually used by pixel values. Thus the allowed range cannot be derived from darr.min()/darr.max() and must be explicitly stored. In other words, if darr is not None, then rangearr specifies the minimum and maximum allowed pixel values, and if darr is None, rangearr is also None.

Constructor & Destructor Documentation

__init__()

pts.visual.rgbimage.RGBImage.__init__	(		self,
			source,
			frameIndices = None )

The constructor creates a new RGBImage from the source specified by the sole argument, as follows:

• A pathlib.Path or string with the filepath of an image file in one of the supported formats (JPEG, PNG, TIFF); the filename extension must be one of .jpg, .jpeg, .png, .tif, or .tiff (case insensitive).
• A pathlib.Path or string with the filepath of a FITS file; the filename extension must be .fits (case insensitive). By default, matching the SKIRT convention of storing data cube frames in order of increasing wavelength, the R channel receives the last frame in the fits file, the G channel the middle frame, and the B channel the first frame. If there is only one frame, the resulting image is effectively greyscale. If there are more than three frames, the RGB image is constructed from widely separated frames. You can override this default behavior by explicitly specifying the frames to be loaded in the RGB channels with the frameIndices argument. Provide a 3-tuple (R,G,B) containing the zero-based frame indices for respectively the red, green and blue channels; for example: frameIndices=(34,12,0).
• A matplotlib Figure instance generated using an AGG back-end (use plt.get_backend() to verify).
• A three-dimensional numpy array with shape (nx, ny, 3), using any numeric value type. The first two indices of the array respectively correspond to the x and y axes, so that arr[0,0,:] represents the lower left pixel, and arr[nx-1,ny-1,:] the upper right pixel. Furthermore arr[:,:,0] is the red plane, arr[:,:,1] the green plane, and arr[:,:,2] the blue plane.

Member Function Documentation

_ensureArr()

pts.visual.rgbimage.RGBImage._ensureArr ( self, invalidate = True )

protected

This private function ensures that there is a valid numpy array representation, converting from one of the other representations if necessary, and invalidating the other representations if requested.

_ensureBuf()

pts.visual.rgbimage.RGBImage._ensureBuf ( self, invalidate = True )

protected

This private function ensures that there is a valid buffer representation, converting from one of the other representations if necessary, and invalidating the other representations if requested.

_ensurePil()

pts.visual.rgbimage.RGBImage._ensurePil ( self, invalidate = True )

protected

This private function ensures that there is a valid PIL image representation, converting from one of the other representations if necessary, and invalidating the other representations if requested.

_setArr()

pts.visual.rgbimage.RGBImage._setArr ( self, arr )

protected

This private function sets the specified numpy array as internal representation, invalidating the other representations.

The array values are converted to 8-byte floating point if needed.

_setBuf()

pts.visual.rgbimage.RGBImage._setBuf ( self, buf )

protected

This private function sets the specified RGBA buffer or string as internal representation, invalidating the other representations.

_setPil()

pts.visual.rgbimage.RGBImage._setPil ( self, pil )

protected

This private function sets the specified PIL image as internal representation, invalidating the other representations.

The image is converted to RGB mode if needed.

addBelow()

pts.visual.rgbimage.RGBImage.addBelow	(		self,
			image )

This function places the specified RGBImage below the receiving image.

It is the caller's responsibility to ensure that both images have the same width (in pixels).

addRight()

pts.visual.rgbimage.RGBImage.addRight	(		self,
			image )

This function places the specified RGBImage to the right of the receiving image.

It is the caller's responsibility to ensure that both images have the same height (in pixels).

applyColorMap()

pts.visual.rgbimage.RGBImage.applyColorMap	(		self,
			cmap )

This function applies the specified color map to the (scaled) pixel values of the red channel, and replaces the image data with the result.

The cmap argument can be one of the following:

• the name of a standard matplotlib color map (see figure below), possibly followed by "_r" to get the reversed map;
• a matplotlib ColorMap object;
• any callable object taking a single array argument with floating point values in range [0,1] and returning a tuple of four RGBA values in range [0,1] for each element in the array – in other words newshape = oldshape+(4,) – where the A value is ignored.

applyCurve()

pts.visual.rgbimage.RGBImage.applyCurve	(		self,
			point1 = (0.25,0.16),
			point2 = (0.80,0.86) )

This function applies a transformation defined by a cubic spline curve to the (scaled) pixel values, and replaces the image data with the result.

The pixel values are scaled to the interval [0,1]. The curve is composed of three cubic spline segments connecting the four points \((0,0),\,(x_1,y_1),\,(x_2,y_2),\,(1,1)\) with \(0<x_1<x_2<1\), where the outer points are fixed and the inner points are provided as arguments to this function.

applyLog()

pts.visual.rgbimage.RGBImage.applyLog

(

self

)

This function applies the natural logarithm function to the pixel values of the image, and adjusts the pixel range accordingly.

This function raises an error if the pixel range includes zero or negative values when this function is called. This can be avoided, for example, by calling the setrange() function with a nonzero minimum value before calling the applylog() function.

applySqrt()

pts.visual.rgbimage.RGBImage.applySqrt

(

self

)

This function applies the square root function to the pixel values of the image, and adjusts the pixel range accordingly.

This function raises an error if the pixel range includes zero or negative values when this function is called. This can be avoided, for example, by calling the setrange() function with a nonzero minimum value before calling the applylog() function.

bytesArray()

pts.visual.rgbimage.RGBImage.bytesArray

(

self

)

This function returns the image's pixel data as a bytes object in the rgba format that can also be obtained from mtplotlib (3 RGB channels plus a dummy alpha channel, 8 bits each).

enlargeCanvas()

pts.visual.rgbimage.RGBImage.enlargeCanvas	(		self,
			shape )

This function adds pixel rows and/or columns to the receiving image if needed to match a given shape.

Each direction (horizontal and vertical) is handled separately. Extra pixels are added equally on both sides of the image (left/right or top/bottom), and are given a value of zero. Pixels are never removed. The target shape can be specified as a 2-tuple (nx,ny), or by providing another RGBImage object.

percentilePixelRange()

pts.visual.rgbimage.RGBImage.percentilePixelRange	(		self,
			from_percentile = 0,
			to_percentile = 100 )

This function determines the range of the image's pixel values, ignoring zero and negative values, and omitting outliers on both sides of the scale as specified by the from and to percentiles.

The resulting range is returned as a tuple (min, max).

pixelArray()

pts.visual.rgbimage.RGBImage.pixelArray

(

self

)

This function returns the image's pixeldata as a 3D numpy array with shape (nx, ny, 3).

pixelRange()

pts.visual.rgbimage.RGBImage.pixelRange

(

self

)

This function returns the range of the image's pixel values as a tuple (min, max).

plot()

pts.visual.rgbimage.RGBImage.plot	(		self,
			fill = False )

This function plots the image to the current axes in the current matplotlib figure.

The image is rescaled to fit the axes. If fill is True, the image is stretched to fit the axes in both directions changing the image aspect ratio if needed. If fill is False (the default), the axes aspect ratio is adjusted so that the image aspect ratio is preserved.

saveTo()

pts.visual.rgbimage.RGBImage.saveTo	(		self,
			outFilePath,
			tiff16bit = False )

This function saves the image to a file with the specified /em outFilePath in one of the supported formats.

The file format is chosen based on the filename extension in the /em outFilePath, which /em must be one of .jpg, .jpeg, .png, .tif, .tiff, .pdf or .fits (case insensitive). The image is saved in RGB mode. If the tiff16bit argument is True and the filename extension is .tif or .tiff, the image is saved with 16 bits per sample rather than the standard 8 bits per sample; however in this case the image data is not compressed. JPEGs are compressed with quality 80 on a scale of 1 to 100. FITS files contain a data cube with three data frames in the order BGR, matching the SKIRT convention of storing data cube frames in order of increasing wavelength.

scaledPixelArray()

pts.visual.rgbimage.RGBImage.scaledPixelArray	(		self,
			newmin,
			newmax )

This function returns the image's pixel data as a 3D numpy array with shape (nx, ny, 3), after scaling the data to the specified range, but without affecting the data in the image itself.

scaleValues()

pts.visual.rgbimage.RGBImage.scaleValues	(		self,
			newmin,
			newmax )

This function applies a linear transformation to the pixel values and to the pixel value range, such that the previous range is exactly mapped onto the new specified range.

setRange()

pts.visual.rgbimage.RGBImage.setRange	(		self,
			newmin = None,
			newmax = None )

This function changes the pixel value range without affecting the actual pixel values except that, if the new range is smaller than the previous range, the pixel values are clipped to the new range.

One can specify a new minimum, a new maximum, or both.

shape()

pts.visual.rgbimage.RGBImage.shape

(

self

)

This function returns the image's shape as a tuple (nx, ny).

---

The documentation for this class was generated from the following file:

• rgbimage.py