ImageRGBa¶

class ImageRGBa(*args, **kwargs)¶

Bases: pybind11_object

Definition of the vpImage class member functions.

This is a template class, therefore the type of each element of the array is not a priori defined.

Data structure¶

Each image is build using two structure (an array bitmap which size is [width*height]) and an array of pointer row (which size is [nrow]) the ith element in the row array row[i] is pointer toward the ith “line” of the image (ie, bitmap +i*width )

Such a structure allows a fast access to each element of the image. if i is the ith rows and j the jth columns the value of this pixel is given by I[i][j] (that is equivalent to row[i][j]).

Example¶

The following example available in tutorial-image-manipulation.cpp shows how to create gray level and color images and how to access to the pixels.

#include <visp3/core/vpConfig.h>
#include <visp3/core/vpImage.h>

int main()
{
#ifdef ENABLE_VISP_NAMESPACE
  using namespace VISP_NAMESPACE_NAME ;
#endif

  try {
    vpImage<unsigned char>  gray_image(240, 320);
    vpImage<vpRGBa>  color_image(240, 320);

    gray_image = 128;
    vpRGBa  color(255, 0, 0);
    color_image = color;

    unsigned int igray_max = gray_image.getHeight() - 1;
    unsigned int jgray_max = gray_image.getWidth() - 1;
    std::cout << "Gray  image, last pixel intensity: " << (int)gray_image[igray_max][jgray_max] << std::endl;

    unsigned int icolor_max = color_image.getHeight() - 1;
    unsigned int jcolor_max = color_image.getWidth() - 1;
    std::cout << "Color image, last pixel RGB components: " << (int)color_image[icolor_max][jcolor_max].R << " "
      << (int)color_image[icolor_max][jcolor_max].G << " " << (int)color_image[icolor_max][jcolor_max].B
      << std::endl;
  }
  catch (const vpException  &e) {
    std::cout << "Catch an exception: " << e << std::endl;
  }
}

Important remark¶

To provide high-performance access there is no verification to ensure that 0 \(\le\) i < height and 0 \(\le\) j < width. Since the memory allocated in the bitmap array is continuous, that means that if (i, j) is outside the image you will manipulate a pixel that is not as expected. To highlight this remark, we provide hereafter an example where the considered pixel is outside the image:

unsigned int width = 320;
unsigned int height = 240;
vpImage<unsigned char> I(height, width); // Create an 320x240 image
// Set pixel coordinates that is outside the image
unsigned int i = 100;
unsigned int j = 400;
unsigned char value;
value = I[i][j]; // Here we will get the pixel value at position (101, 80)

Overloaded function.

__init__(self: visp._visp.core.ImageRGBa) -> None

constructor

__init__(self: visp._visp.core.ImageRGBa, img: visp._visp.core.ImageRGBa) -> None

copy constructor

__init__(self: visp._visp.core.ImageRGBa, height: int, width: int) -> None

constructor set the size of the image

__init__(self: visp._visp.core.ImageRGBa, height: int, width: int, value: visp._visp.core.RGBa) -> None

constructor set the size of the image and init all the pixel

__init__(self: visp._visp.core.ImageRGBa, np_array: numpy.ndarray[numpy.uint8]) -> None

Construct an image by copying a 3D numpy array. this numpy array should be of the form \(H \times W \times 4\) where the 4 denotes the red, green, blue and alpha components of the image.

param np_array:: The numpy array to copy.

Methods

`__init__`	Overloaded function.
`destroy`	Destructor : Memory de-allocation.
`doubleSizeImage`	Returns a new image that's double size of the current image.
`getCols`	Get the number of columns in the image.
`getHeight`	Get the image height.
`getMaxValue`	Return the maximum value within the bitmap.
`getMinMaxValue`	Look for the minimum and the maximum value within the bitmap.
`getMinValue`	Return the minimum value within the bitmap.
`getNumberOfPixel`	Get the image number of pixels which corresponds to the image width multiplied by the image height.
`getRows`	Get the number of rows in the image.
`getSize`	Get the image size.
`getValue`	Overloaded function.
`getWidth`	Get the image width.
`halfSizeImage`	Returns a new image that's half size of the current image.
`init`	Overloaded function.
`insert`	Insert an image into another one.
`numpy`	Numpy view of the underlying image data.
`quarterSizeImage`	Returns a new image that's a quarter size of the current image.
`resize`	Overloaded function.
`sub`	Overloaded function.
`subsample`	Computes a subsampled image.

Inherited Methods

Operators

`__call__`	Overloaded function.
`__doc__`
`__eq__`	Compare two images.
`__getitem__`	Overloaded function.
`__hash__`
`__init__`	Overloaded function.
`__module__`
`__ne__`	Compare two images.
`__repr__`
`__sub__`	Operation A - B (A is unchanged).

Attributes

`__annotations__`
`__hash__`

__call__(*args, **kwargs)¶

Overloaded function.

__call__(self: visp._visp.core.ImageRGBa, i: int, j: int) -> visp._visp.core.RGBa

Get the value of an image point with coordinates (i, j), with i the row position and j the column position.

Returns:: Value of the image point (i, j).

__call__(self: visp._visp.core.ImageRGBa, i: int, j: int, v: visp._visp.core.RGBa) -> None

Set the value v of an image point with coordinates (i, j), with i the row position and j the column position.

__call__(self: visp._visp.core.ImageRGBa, ip: visp._visp.core.ImagePoint, v: visp._visp.core.RGBa) -> None

Set the value of an image point.

Parameters:

ip: An image point with sub-pixel coordinates. Sub-pixel coordinates are roughly transformed to insigned int coordinates by cast.
v: Value to set for the image point.

__eq__(self, I: visp._visp.core.ImageRGBa) → bool¶

Compare two images.

Returns:: true if the images are the same, false otherwise.

__getitem__(*args, **kwargs)¶

Overloaded function.

__getitem__(self: visp._visp.core.ImageRGBa, arg0: tuple[int, int]) -> visp._visp.core.RGBa
__getitem__(self: visp._visp.core.ImageRGBa, arg0: int) -> numpy.ndarray[numpy.uint8]
__getitem__(self: visp._visp.core.ImageRGBa, arg0: slice) -> numpy.ndarray[numpy.uint8]
__getitem__(self: visp._visp.core.ImageRGBa, arg0: tuple) -> numpy.ndarray[numpy.uint8]

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: visp._visp.core.ImageRGBa) -> None

constructor

__init__(self: visp._visp.core.ImageRGBa, img: visp._visp.core.ImageRGBa) -> None

copy constructor

__init__(self: visp._visp.core.ImageRGBa, height: int, width: int) -> None

constructor set the size of the image

__init__(self: visp._visp.core.ImageRGBa, height: int, width: int, value: visp._visp.core.RGBa) -> None

constructor set the size of the image and init all the pixel

__init__(self: visp._visp.core.ImageRGBa, np_array: numpy.ndarray[numpy.uint8]) -> None

Construct an image by copying a 3D numpy array. this numpy array should be of the form \(H \times W \times 4\) where the 4 denotes the red, green, blue and alpha components of the image.

Parameters:

np_array: The numpy array to copy.

__ne__(self, I: visp._visp.core.ImageRGBa) → bool¶

Compare two images.

Returns:: true if the images are different, false if they are the same.

__sub__(self, B: visp._visp.core.ImageRGBa) → visp._visp.core.ImageRGBa¶

Operation A - B (A is unchanged).

#include <visp3/core/vpImage.h>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpImage<unsigned char> A(288, 384);
  vpImage<unsigned char> B(288, 384);
  vpImage<unsigned char> C;

  A = 128;
  B = 120;

  // operator-() : C = A - B
  C = A - B;

  return 0;
}

Note

See sub(const vpImage<Type> &, const vpImage<Type> &, vpImage<Type> &) to avoid matrix allocation for each use.

destroy(self) → None¶: Destructor : Memory de-allocation.

Warning

does not deallocate memory for display and video

doubleSizeImage(self, res: visp._visp.core.ImageRGBa) → None¶

Returns a new image that’s double size of the current image. Used (eg. in case of keypoints extraction, we might double size of the image in order to have more keypoints). The double size image is computed by nearest-neighbour interpolation:

A B C
E F G
H I J

where
A C H J are pixels from original image
B E G I are interpolated pixels

Warning

Operator = must be defined for Type.

The example below shows how to use this method:

vpImage<unsigned char> I; // original image
vpImageIo::read(I, "myImage.pgm");
vpImage<unsigned char> I2; // double size image
I.doubleSizeImage(I2);
vpImageIo::write(I2, "myDoubleSizeImage.pgm");

See halfSizeImage(vpImage<Type> &) for an example of pyramid construction.

Parameters:

res: visp._visp.core.ImageRGBa¶: [out] : Image that is double size of the current image.

getCols(self) → int¶

Get the number of columns in the image.

Note

See getWidth()

Returns:: The image number of column, or image width.

getHeight(self) → int¶

Get the image height.

Note

See getWidth()

Returns:: The image height.

getMaxValue(self, onlyFiniteVal: bool = true) → visp._visp.core.RGBa¶

Return the maximum value within the bitmap.

Return the maximum value within the float bitmap.

Return the maximum value within the double bitmap.

Note

See getMinValue()

Parameters:

onlyFiniteVal: bool = true¶: This parameter is ignored for non double or non float bitmap. If true, consider only finite values.

getMinMaxValue(self, min: visp._visp.core.RGBa, max: visp._visp.core.RGBa, onlyFiniteVal: bool = true) → None¶

Look for the minimum and the maximum value within the bitmap.

Note

See getMaxValue()

Note

See getMinValue()

Note

See getMinMaxLoc()

Parameters:

min: visp._visp.core.RGBa¶: The minimal value within the bitmap.
max: visp._visp.core.RGBa¶: The maximal value within the bitmap.
onlyFiniteVal: bool = true¶: This parameter is ignored for non double or non float bitmap.

getMinValue(self, onlyFiniteVal: bool = true) → visp._visp.core.RGBa¶

Return the minimum value within the bitmap.

Return the minimum value within the float bitmap.

Return the minimum value within the double bitmap.

Note

See getMaxValue()

Parameters:

onlyFiniteVal: bool = true¶: This parameter is ignored for non double or non float bitmap. If true, consider only finite values.

getNumberOfPixel(self) → int¶

Get the image number of pixels which corresponds to the image width multiplied by the image height.

Note

See getWidth() , getHeight()

Returns:: The image number of pixels or image size.

getRows(self) → int¶

Get the number of rows in the image.

Note

See getHeight()

Returns:: The image number of rows, or image height.

getSize(self) → int¶

Get the image size.

Note

See getWidth() , getHeight()

Returns:: The image size = width * height.

getValue(*args, **kwargs)¶

Overloaded function.

getValue(self: visp._visp.core.ImageRGBa, i: int, j: int) -> visp._visp.core.RGBa

Retrieves pixel value from an image containing values of type Type .

Gets the value of a sub-pixel with coordinates (i,j).

Parameters:

i: Pixel coordinate along the rows.
j: Pixel coordinate along the columns.

Returns:

Pixel value.

getValue(self: visp._visp.core.ImageRGBa, i: float, j: float) -> visp._visp.core.RGBa

Retrieves pixel value from an image containing values of type Type with sub-pixel accuracy.

Gets the value of a sub-pixel with coordinates (i,j) with bilinear interpolation.

See also vpImageTools::interpolate() for a similar result, but with a choice of the interpolation method.

Parameters:

i: Sub-pixel coordinate along the rows.
j: Sub-pixel coordinate along the columns.

Returns:

Interpolated sub-pixel value from the four neighbours.

getValue(self: visp._visp.core.ImageRGBa, ip: visp._visp.core.ImagePoint) -> visp._visp.core.RGBa

Retrieves pixel value from an image containing values of type Type with sub-pixel accuracy.

Gets the value of a sub-pixel with coordinates (i,j) with bilinear interpolation.

See also vpImageTools::interpolate() for a similar result, but with a choice of the interpolation method.

Parameters:

ip: Sub-pixel coordinates of a point in the image.

Returns:

Interpolated sub-pixel value from the four neighbors.

getWidth(self) → int¶

Get the image width.

Note

See getHeight()

Returns:: The image width.

halfSizeImage(self, res: visp._visp.core.ImageRGBa) → None¶

Returns a new image that’s half size of the current image. No filtering is used during the sub sampling.

Used for building pyramid of the image.

Warning

Operator = must be defined for Type.

The example below shows how to use this method:

vpImage<unsigned char> I; // original image
vpImageIo::read(I, "myImage.pgm");
vpImage<unsigned char> I2; // half size image
I.halfSizeImage(I2);
vpImageIo::write(I2, "myHalfSizeImage.pgm");

This other example shows how to construct a pyramid of the image:

vpImage<unsigned char> I[4];   // pyramid with 4 levels
vpImageIo::read(I[1], "myImage.pgm"); // Original image at level 1
// compute the other levels
I5[1].doubleSizeImage(I5[0]);  // double size image at level 0
I5[1].halfSizeImage(I5[2]);    // half size image at level 2
I5[1].quarterSizeImage(I5[3]); // quarter size image at level 3

Note

See subsample()

Parameters:

res: visp._visp.core.ImageRGBa¶: [out] : Subsampled image that is half size of the current image.

init(*args, **kwargs)¶

Overloaded function.

init(self: visp._visp.core.ImageRGBa, height: int, width: int) -> None

Set the size of the image.

init(self: visp._visp.core.ImageRGBa, height: int, width: int, value: visp._visp.core.RGBa) -> None

Set the size of the image and initialize all the elements to ‘value’.

insert(self, src: visp._visp.core.ImageRGBa, topLeft: visp._visp.core.ImagePoint) → None¶

Insert an image into another one.

It is possible to insert the image \(src\) into the calling vpImage . You can set the point in the destination image where the top left corner of the \(src\) image will be located.

Parameters:

src: visp._visp.core.ImageRGBa¶: Image to insert
topLeft: visp._visp.core.ImagePoint¶: Upper/left coordinates in the image where the image src is inserted in the destination image.

numpy(self) → numpy.ndarray[numpy.uint8]¶: Numpy view of the underlying image data. This numpy view can be used to directly modify the array.

quarterSizeImage(self, res: visp._visp.core.ImageRGBa) → None¶

Returns a new image that’s a quarter size of the current image. No filtering is used during the sub sampling. Used for building a quarter of the image.

Warning

Operator = must be defined for Type.

The example below shows how to use this method:

vpImage<unsigned char> I; // original image
vpImageIo::read(I, "myImage.pgm");
vpImage<unsigned char> I4; // quarter size image
I.halfSizeImage(I4);
vpImageIo::write(I4, "myQuarterSizeImage.pgm");

See halfSizeImage(vpImage<Type> &) for an example of pyramid construction.

Note

See subsample()

Parameters:

res: visp._visp.core.ImageRGBa¶: [out] : Subsampled image that is quarter size of the current image.

resize(*args, **kwargs)¶

Overloaded function.

resize(self: visp._visp.core.ImageRGBa, h: int, w: int) -> None

resize the image : Image initialization

Allocate memory for an [height x width] image.

Warning

The image is not initialized.

Element of the bitmap are not initialized

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Note

See init(unsigned int, unsigned int)

Parameters:

h: Image height.
w: Image width.

resize(self: visp._visp.core.ImageRGBa, h: int, w: int, val: visp._visp.core.RGBa) -> None

resize the image : Image initialization

Allocate memory for an [height x width] image and initialize the image.

Element of the bitmap are not initialized

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Note

See init(unsigned int, unsigned int)

Parameters:

h: Image height.
w: Image width.
val: Pixels value.

sub(*args, **kwargs)¶

Overloaded function.

sub(self: visp._visp.core.ImageRGBa, B: visp._visp.core.ImageRGBa, C: visp._visp.core.ImageRGBa) -> None

Operation C = *this - B.

#include <visp3/core/vpImage.h>

#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif

int main()
{
  vpImage<unsigned char> A(288, 384);
  vpImage<unsigned char> B(288, 384);
  vpImage<unsigned char> C;

  A = 128;
  B = 120;

  A.sub(B, C); // C = A - B

  return 0;
}

The result is placed in the third parameter C and not returned. A new image won’t be allocated for every use of the function (Speed gain if used many times with the same result matrix size).

Note

See operator-()

sub(self: visp._visp.core.ImageRGBa, A: visp._visp.core.ImageRGBa, B: visp._visp.core.ImageRGBa, C: visp._visp.core.ImageRGBa) -> None

Operation C = A - B.

The result is placed in the third parameter C and not returned. A new image won’t be allocated for every use of the function (Speed gain if used many times with the same result matrix size).

Note

See operator-()

subsample(self, v_scale: int, h_scale: int, sampled: visp._visp.core.ImageRGBa) → None¶

Computes a subsampled image. No filtering is used during the sub sampling.

The example below shows how to use this method:

vpImage<unsigned char> I; // original image
vpImageIo::read(I, "myImage.pgm");
vpImage<unsigned char> I2; // half size image
I.subsample(2, 2, I2);
vpImageIo::write(I2, "myHalfSizeImage.pgm");

Parameters:

v_scale: int¶: [in] : Vertical subsampling factor.
h_scale: int¶: [in] : Horizontal subsampling factor.
sampled: visp._visp.core.ImageRGBa¶: [out] : Subsampled image.

__hash__ = None¶