Client-side interface to a PixInsight Bitmap object. More...

#include <Bitmap.h>

Inheritance diagram for pcl::Bitmap:

Public Types
using	display_channel = DisplayChannel::value_type

using	mask_mode = MaskMode::value_type

using	pixel_format = BitmapFormat::value_type

Public Member Functions
	Bitmap ()

	Bitmap (Bitmap &&x)

	Bitmap (const Bitmap &bmp)

	Bitmap (const Bitmap &bmp, const pcl::Rect &r)

	Bitmap (const Bitmap &bmp, int x0, int y0, int x1, int y1)

	Bitmap (const char **xpm)

	Bitmap (const char *filePath)

	Bitmap (const IsoString &filePath)

	Bitmap (const String &filePath)

	Bitmap (const void data, size_type size, const char format="SVG", uint32 flags=0)

	Bitmap (int width, int height, pixel_format fmt=BitmapFormat::ARGB32)

	~Bitmap () override

void	And (const Bitmap &src)

void	And (const pcl::Point &p, const Bitmap &src)

void	And (const pcl::Point &p, const Bitmap &src, const pcl::Rect &r)

void	And (const pcl::Rect &rect, RGBA andWith)

void	And (RGBA andWith)

pcl::Rect	Bounds () const

void	Copy (const Bitmap &src)

void	Copy (const pcl::Point &p, const Bitmap &src)

void	Copy (const pcl::Point &p, const Bitmap &src, const pcl::Rect &r)

void	Fill (const pcl::Rect &rect, RGBA fillWith)

void	Fill (RGBA fillWith)

void	GetDimensions (int &width, int &height) const

int	Height () const

void	Invert ()

void	Invert (const pcl::Rect &rect)

void	InvertRect ()

void	InvertRect (const pcl::Rect &rect)

bool	IsEmpty () const

void	Load (const String &filePath)

void	Load (const void data, size_type size, const char format="SVG", uint32 flags=0)

Bitmap	Mirrored () const

Bitmap	MirroredHorizontally () const

Bitmap	MirroredVertically () const

	operator bool () const

Bitmap &	operator= (Bitmap &&x)

Bitmap &	operator= (const Bitmap &bmp)

void	Or (const Bitmap &src)

void	Or (const pcl::Point &p, const Bitmap &src)

void	Or (const pcl::Point &p, const Bitmap &src, const pcl::Rect &r)

void	Or (const pcl::Rect &rect, RGBA orWith)

void	Or (RGBA orWith)

double	PhysicalPixelRatio () const

RGBA	Pixel (const pcl::Point &p) const

RGBA	Pixel (int x, int y) const

pixel_format	PixelFormat () const

void	ReplaceColor (const pcl::Rect &rect, RGBA replaceThis, RGBA replaceWith)

void	ReplaceColor (RGBA replaceThis, RGBA replaceWith)

Bitmap	Rotated (double angle, bool precise=true) const

void	Save (const String &filePath, int quality=-1) const

Bitmap	Scaled (double sx, double sy, bool precise=true) const

Bitmap	Scaled (double sxy, bool precise=true) const

Bitmap	ScaledToHeight (int height, bool precise=true) const

Bitmap	ScaledToSize (int width, int height, bool precise=true) const

Bitmap	ScaledToWidth (int width, bool precise=true) const

RGBA *	ScanLine (int y)

const RGBA *	ScanLine (int y) const

void	SetAlpha (const pcl::Rect &rect, uint8 newAlpha)

void	SetAlpha (uint8 newAlpha)

void	SetPhysicalPixelRatio (double ratio)

void	SetPixel (const pcl::Point &p, RGBA v)

void	SetPixel (int x, int y, RGBA v)

void	SetPixelFormat (pixel_format fmt)

Bitmap	Subimage (const pcl::Rect &r) const

Bitmap	Subimage (int x0, int y0, int x1, int y1) const

int	Width () const

void	Xor (const Bitmap &src)

void	Xor (const pcl::Point &p, const Bitmap &src)

void	Xor (const pcl::Point &p, const Bitmap &src, const pcl::Rect &r)

void	Xor (const pcl::Rect &rect, RGBA xorWith)

void	Xor (RGBA xorWith)

void	XorRect (const pcl::Rect &rect, RGBA xorWith)

void	XorRect (RGBA xorWith)

Public Member Functions inherited from pcl::UIObject
virtual	~UIObject () noexcept(false)

virtual void	EnsureUnique ()

bool	IsAlias () const

bool	IsGarbage () const

bool	IsNull () const

bool	IsSameObject (const UIObject &o) const

bool	IsUnique () const

String	ObjectId () const

IsoString	ObjectType () const

bool	operator< (const UIObject &o) const

bool	operator== (const UIObject &o) const

size_type	RefCount () const

void	SetObjectId (const String &id)

Static Public Member Functions
static Bitmap	FromSVG (const IsoString &svgSource, int width=0, int height=0, SVGRenderOptions options=SVGRenderOption::Default)

static Bitmap	FromSVGFile (const String &filePath, int width=0, int height=0, SVGRenderOptions options=SVGRenderOption::Default)

static Bitmap &	Null ()

static Bitmap	Render (const ImageVariant &image, int zoom=1, display_channel displayChannel=DisplayChannel::RGBK, bool transparency=true, const ImageVariant mask=nullptr, mask_mode maskMode=MaskMode::Default, bool maskInverted=false, const uint8 LUT=nullptr, bool fastDownsample=true, bool(callback)()=nullptr)

Static Public Member Functions inherited from pcl::UIObject
static UIObject &	Null ()

Additional Inherited Members
Protected Member Functions inherited from pcl::UIObject
	UIObject ()=default

	UIObject (const UIObject &x)

	UIObject (UIObject &&x)

UIObject &	operator= (const UIObject &x)

UIObject &	operator= (UIObject &&x)

Detailed Description

In the PixInsight platform, bitmaps are device-independent images that can be used for graphics output and allow direct pixel manipulation.

Pixels in a bitmap are always stored as 32-bit values in the following format:

AARRGGBB

where each letter represents a 4-bit hexadecimal digit (from 0 to F). Each 8-bit pair represents a pixel component in the range from 0 to 255:

AA	Alpha value, or pixel opacity: 0 means completely transparent, 255 corresponds to an opaque pixel.
RR	Red pixel color component.
GG	Green pixel color component.
BB	Blue pixel color component.

Bitmap is a managed, high-level object that encapsulates the properties and behavior of an actual bitmap living in the PixInsight core application.

Bitmap provides a comprehensive set of functions and utility routines to manipulate bitmap images, such as direct pixel access functions, specular and affine transformations, bitwise logical operations, and high-performance rendering of images as bitmaps, among many others.

Along with the Graphics class, Bitmap can be used for off-screen graphics output. Graphics offers a thorough collection of painting routines that can be used to generate sophisticated graphics as bitmaps.

As we have said, bitmaps are device-independent images in PixInsight. It must be pointed out that there is no equivalent to a device-dependent bitmap or image in PixInsight: all device dependencies are managed internally by the PixInsight core application.

Definition at line 203 of file Bitmap.h.

Member Typedef Documentation

◆ display_channel

using pcl::Bitmap::display_channel = DisplayChannel::value_type

The display_channel type represents a display channel supported by the PixInsight core application. Valid channels are defined in the DisplayChannel namespace.

Definition at line 218 of file Bitmap.h.

◆ mask_mode

using pcl::Bitmap::mask_mode = MaskMode::value_type

The mask_mode type represents a mask rendering mode supported by the PixInsight core application. Valid mask rendering modes are defined in the MaskMode namespace.

Definition at line 225 of file Bitmap.h.

◆ pixel_format

using pcl::Bitmap::pixel_format = BitmapFormat::value_type

Represents a bitmap pixel format. See the BitmapFormat namespace for supported values.

Definition at line 211 of file Bitmap.h.

Constructor & Destructor Documentation

◆ Bitmap() [1/11]

pcl::Bitmap::Bitmap ( )

Constructs an empty Bitmap object.

◆ Bitmap() [2/11]

pcl::Bitmap::Bitmap	(	int	width,
		int	height,
		pixel_format	fmt = `BitmapFormat::ARGB32`
	)

Constructs a Bitmap object of the specified width and height dimensions, and pixel format fmt

For the sake of performance, bitmap pixel values are not initialized, so they will contain unpredictable garbage values.

◆ Bitmap() [3/11]

pcl::Bitmap::Bitmap ( const char ** xpm )

Constructs a Bitmap object from a source image in the XPM format.

Parameters

xpm	Starting address of an XPM image description.

References

◆ Bitmap() [4/11]

pcl::Bitmap::Bitmap ( const String & filePath )

Constructs a Bitmap object by loading an embedded resource or disk file.

Parameters

filePath Path to the source image file or resource. A resource path begins with the ":/" prefix. For a list of supported image file formats, see the documentation for the Load( const String& ) member function. The source file format is always determined from the specified file extension.

For more information on embedded resources, see Bitmap::Bitmap( const char* ).

In the even of file I/O error, or if the specified file cannot be decoded and read correctly, this constructor throws an Error exception.

◆ Bitmap() [5/11]

pcl::Bitmap::Bitmap ( const char * filePath )

Constructs a Bitmap object by loading an embedded resource or disk file.

Parameters

filePath Path to the source image file or resource. A resource path begins with the ":/" prefix. For a list of supported image file formats, see the documentation for the Load( const String& ) member function. The source file format is always determined from the specified file extension.

The PixInsight core application uses the Qt resource system for embedded images that can be loaded dynamically from .rcc binary files. For example, the following code snippet loads one of the standard core application icons:

Bitmap icon( ":/icons/document.png" );

pcl::Bitmap::Bitmap

Bitmap()

A module can also use the standard ":/@module_root/" prefix to load module-defined resources. See MetaModule::LoadResource() for a detailed description.

In the even of stream I/O error, or if the specified resource or file cannot be decoded and read correctly, this constructor throws an Error exception.

References

The Qt Resource System: http://doc.qt.io/qt-5/resources.html

◆ Bitmap() [6/11]

pcl::Bitmap::Bitmap ( const IsoString & filePath )

Constructs a Bitmap object by loading an embedded resource or disk file. This constructor is equivalent to Bitmap::Bitmap( const char* ).

◆ Bitmap() [7/11]

pcl::Bitmap::Bitmap	(	const void *	data,
		size_type	size,
		const char *	format = `"SVG"`,
		uint32	flags = `0`
	)

Constructs a Bitmap object from bitmap data stored in memory.

Parameters

data	Starting address of the source bitmap data block.
size	Length of the source data in bytes.
format	A nul-terminated character string identifying the format of the source data. Currently the following formats are supported by the PixInsight core application:

BMP	Windows Bitmap
GIF	Graphics Interchange Format
ICO	Windows Icon Format
JPG	Joint Photographic Experts Group
WEBP	WebP image format
MNG	Multiple Network Graphics
PBM	Portable Bitmap
PNG	Portable Network Graphics
PPM	Portable Pixel Map
SVG	Scalable Vector Graphics
TIFF	Tagged Image File Format
TGA	Truevision TGA Format (TARGA)
XBM	X11 Bitmap
XPM	X11 Pixmap

           The default value (when no format is specified) is SVG.

Parameters

flags Currently not used. This parameter is reserved for future extension and its value must be zero (the default value).

If the data address is invalid, or if the data are not valid in the specified format, this constructor throws an Error exception.

◆ Bitmap() [8/11]

pcl::Bitmap::Bitmap	(	const Bitmap &	bmp,
		const pcl::Rect &	r
	)

Constructs a Bitmap object as a subimage of an existing Bitmap.

Parameters

bmp	Source bitmap.
r	Rectangle that defines the source subimage, in source bitmap coordinates.

◆ Bitmap() [9/11]

pcl::Bitmap::Bitmap	(	const Bitmap &	bmp,
		int	x0,
		int	y0,
		int	x1,
		int	y1
	)

Constructs a Bitmap object as a subimage of an existing Bitmap.

Parameters

bmp	Source bitmap.
x0,y0	Coordinates of the upper left corner of the rectangle that defines the source subimage, in source bitmap coordinates.
x1,y1	Coordinates of the lower right corner of the rectangle that defines the source subimage, in source bitmap coordinates.

◆ Bitmap() [10/11]

pcl::Bitmap::Bitmap ( const Bitmap & bmp )

inline

Copy constructor. This object will reference the same server-side bitmap as the specified instance b.

Definition at line 372 of file Bitmap.h.

◆ Bitmap() [11/11]

pcl::Bitmap::Bitmap ( Bitmap && x )

inline

Move constructor.

Definition at line 379 of file Bitmap.h.

◆ ~Bitmap()

pcl::Bitmap::~Bitmap ( )

inlineoverride

Destroys a Bitmap object.

The actual bitmap object that this Bitmap instance refers to lives in the PixInsight core application, and as such, it will be destroyed and deallocated (garbage-collected) only when no more references exist to it in other high-level managed objects, such as other instances of Bitmap living in installed modules, or some element of the graphical interface.

Definition at line 392 of file Bitmap.h.

Member Function Documentation

◆ Bounds()

pcl::Rect pcl::Bitmap::Bounds ( ) const

inline

Returns the bounding rectangle of this bitmap.

The upper-left corner of the returned rectangle is always at (0,0). The width and height of the returned rectangle are the bitmap dimensions.

Definition at line 536 of file Bitmap.h.

Referenced by Copy().

◆ FromSVG()

static Bitmap pcl::Bitmap::FromSVG	(	const IsoString &	svgSource,
		int	width = `0`,
		int	height = `0`,
		SVGRenderOptions	options = `SVGRenderOption::Default`
	)

static

Renders an SVG document as a raster image into a new Bitmap object.

Parameters

filePath	The source code of a valid SVG document representing the image to be rendered, encoded in UTF-8.
width,height	The width and height in pixels of the image where the SVG rendition will be generated. If a dimension is ≤ 0, the rendition will use the corresponding dimension specified by the SVG document: either viewBox coordinates, if available, or the width and height attributes of the root svg element.
options	Rendering options. See the SVGRenderOption namespace for possible values.

See also: FromSVGFile()

◆ FromSVGFile()

static Bitmap pcl::Bitmap::FromSVGFile	(	const String &	filePath,
		int	width = `0`,
		int	height = `0`,
		SVGRenderOptions	options = `SVGRenderOption::Default`
	)

static

Renders an SVG document file as a raster image into a new Bitmap object.

Parameters

filePath	Path to an existing file in the local file system, which must store a valid SVG document representing the image to be rendered. The SVG source code must be encoded in UTF-8.
width,height	The width and height in pixels of the image where the SVG rendition will be generated. If a dimension is ≤ 0, the rendition will use the corresponding dimension specified by the SVG document: either viewBox coordinates, if available, or the width and height attributes of the root svg element.
options	Rendering options. See the SVGRenderOption namespace for possible values.

Automatic Resource Location

This function can load SVG documents from arbitrary locations on the local file system. However, modules typically install their process and interface icons on the /rsc/icons/module directory under the local PixInsight installation. A module can specify the "@module_icons_dir/" prefix in the filePath argument to this function to let the PixInsight core application load the corresponding SVG document from the appropriate standard distribution directory automatically. For example, suppose that this function is invoked by a "Foo" module as follows:

Bitmap RenderSpecialIcon()
{
   return Bitmap::FromSVGFile( "@module_icons_dir/special/icon.svg" );
}

Then the core application will attempt to load the following SVG file:

<install-dir>/rsc/icons/module/Foo/special/icon.svg

where <install-dir> is the local directory where the running PixInsight core application is installed.

See also: FromSVG()

◆ GetDimensions()

void pcl::Bitmap::GetDimensions	(	int &	width,
		int &	height
	)		const

Obtains the dimensions (width, height) of this bitmap in pixels.

◆ Height()

int pcl::Bitmap::Height ( ) const

inline

Returns the height of this bitmap in pixels.

Definition at line 525 of file Bitmap.h.

◆ IsEmpty()

bool pcl::Bitmap::IsEmpty ( ) const

Returns true iff this bitmap is empty. An empty bitmap has zero dimensions and does not contain any image.

◆ Load()

void pcl::Bitmap::Load	(	const void *	data,
		size_type	size,
		const char *	format = `"SVG"`,
		uint32	flags = `0`
	)

Loads this bitmap from data stored in memory.

Parameters

data	Starting address of the source bitmap data block.
size	Length of the source data in bytes.
format	A nul-terminated character string identifying the format of the source data. Currently the only supported format is Scalable Vector Graphics (SVG), and this is also the default value of this parameter ("SVG").
flags	Currently not used. This parameter is reserved for future extension and its value must be zero (the default value).

If the data address is invalid, or if the data are not valid in the specified format, this member function throws an Error exception.

◆ Null()

static Bitmap& pcl::Bitmap::Null ( )

static

Returns a reference to a null Bitmap instance. A null Bitmap does not correspond to an existing bitmap in the PixInsight core application.

Referenced by pcl::BitmapBox::Clear(), pcl::ComboBox::ClearItemIcon(), pcl::TabBox::ClearPageIcon(), and pcl::ImageWindow::ResetDynamicCursor().

◆ operator bool()

pcl::Bitmap::operator bool ( ) const

inline

Returns true iff this bitmap contains an image, that is, if it is not an empty bitmap.

This is a convenience operator that simply returns !IsEmpty().

Definition at line 553 of file Bitmap.h.

◆ operator=() [1/2]

Bitmap& pcl::Bitmap::operator= ( Bitmap && x )

inline

Move assignment operator. Returns a reference to this object.

Definition at line 412 of file Bitmap.h.

◆ operator=() [2/2]

Bitmap& pcl::Bitmap::operator= ( const Bitmap & bmp )

inline

Copy assignment operator. Returns a reference to this object.

Makes this object reference the same server-side bitmap as the specified instance bmp. If the previous bitmap becomes unreferenced, it will be garbage-collected by the PixInsight core application.

Definition at line 403 of file Bitmap.h.

◆ PixelFormat()

pixel_format pcl::Bitmap::PixelFormat ( ) const

Returns the current pixel format for this bitmap.

Supported pixel format values are enumerated in the BitmapFormat namespace.

◆ Render()

static Bitmap pcl::Bitmap::Render	(	const ImageVariant &	image,
		int	zoom = `1`,
		display_channel	displayChannel = `DisplayChannel::RGBK`,
		bool	transparency = `true`,
		const ImageVariant *	mask = `nullptr`,
		mask_mode	maskMode = `MaskMode::Default`,
		bool	maskInverted = `false`,
		const uint8 **	LUT = `nullptr`,
		bool	fastDownsample = `true`,
		bool(*)()	callback = `nullptr`
	)

static

Renders an image as a bitmap.

Parameters

image	The source image to be rendered. It can be a PCL image of any supported sample type.
zoom	Zoom factor. If zoom == 1, the image will be rendered at its actual dimensions in pixels. Positive zoom factors are enlarging ratios; for example, if zoom == 2, the image will be rendered zoomed 2:1 (twice its actual sizes). Negative zoom factors are reduction ratios: zoom = -3 means zoomed 1:3, or one third of the actual image dimensions.
displayChannel	See the DisplayChannel enumeration for possible values. The default mode is DisplayChannel::RGBK, which means that the image will be rendered in RGB/gray composite mode.
transparency	If this parameter is true and the image has one or more alpha channels, the image will be rendered over a transparent background and the first alpha channel will define pixel opacity. If this parameter is false, alpha channels will not be interpreted as transparency masks.
mask	If non-null, this is the address of an image that will be treated as a mask acting for the source image. Mask pixels modify the image rendition according to the specified mask rendering mode (see the maskMode paramter). The mask image must have the same dimensions as the source image. This parameter is nullptr by default.
maskMode	This parameter defines the mask rendering mode to be used if a mask image has been specified. See the MaskMode enumeration for supported values. The default mode is MaskMode::Default, which corresponds to the red overlay mask rendering mode.
maskInverted	If mask is non-null and this parameter is true, mask pixels will be inverted before rendering them over source image pixels.
LUT	If non-null, this is the address of a look-up table that will be used to remap bitmap pixel values. This parameter is nullptr by default.
fastDownsample	If this parameter is true, a fast sparse interpolation algorithm will be used to render the image if a zoom factor less than -2 is specified. Fast subsampling interpolation is considerably faster than normal (slow) interpolation, but the generated renditions are less accurate. In general though, fast interpolation errors are barely noticeable. This parameter is true by default.
callback	If non-null, this is the address of a callback routine that will be invoked during the bitmap rendition procedure. If the callback routine returns false, the rendition is aborted and a null bitmap (Bitmap::Null()) is returned. By default this parameter is nullptr.

This is a high-performance routine, implemented with highly optimized parallel code, that can be used for real-time image visualization. If allowed through global preferences, it will use all available processors and processor cores by means of concurrent threads.

◆ SetPixelFormat()

void pcl::Bitmap::SetPixelFormat ( pixel_format fmt )

Sets the pixel format for this bitmap. If necessary, pixel values will be converted internally to match the specified format.

Supported pixel format values are enumerated in the BitmapFormat namespace.

◆ Subimage() [1/2]

Bitmap pcl::Bitmap::Subimage ( const pcl::Rect & r ) const

inline

Returns a subimage of this bitmap.

Parameters

r	A Rect object defining subimage boundaries.

The rectangular area defines the size and position of the subimage that is extracted and returned as a new Bitmap object.

Definition at line 869 of file Bitmap.h.

References pcl::GenericRectangle< T >::x0, pcl::GenericRectangle< T >::x1, pcl::GenericRectangle< T >::y0, and pcl::GenericRectangle< T >::y1.

◆ Subimage() [2/2]

Bitmap pcl::Bitmap::Subimage	(	int	x0,
		int	y0,
		int	x1,
		int	y1
	)		const

Returns a subimage of this bitmap.

Parameters

x0,y0	Coordinates of the upper left corner of the source rectangular region.
x1,y1	Coordinates of the lower right corner of the source rectangular region.

The rectangular region defines the size and position of the subimage that is extracted and returned as a new Bitmap object.

◆ Width()

int pcl::Bitmap::Width ( ) const

inline

Returns the width of this bitmap in pixels.

Definition at line 517 of file Bitmap.h.

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

Bitmap.h

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ display_channel

◆ mask_mode

◆ pixel_format

Constructor & Destructor Documentation

◆ Bitmap() [1/11]

◆ Bitmap() [2/11]

◆ Bitmap() [3/11]

◆ Bitmap() [4/11]

◆ Bitmap() [5/11]

◆ Bitmap() [6/11]

◆ Bitmap() [7/11]

◆ Bitmap() [8/11]

◆ Bitmap() [9/11]

◆ Bitmap() [10/11]

◆ Bitmap() [11/11]

◆ ~Bitmap()

Member Function Documentation

◆ Bounds()

◆ FromSVG()

◆ FromSVGFile()

◆ GetDimensions()

◆ Height()

◆ IsEmpty()

◆ Load()

◆ Null()

◆ operator bool()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PixelFormat()

◆ Render()

◆ SetPixelFormat()

◆ Subimage() [1/2]

◆ Subimage() [2/2]

◆ Width()