Open3D (C++ API)  0.18.0+252c867
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Attributes
open3d::t::geometry::Image Class Reference

The Image class stores image with customizable rows, cols, channels, dtype and device. More...

#include <Image.h>

Inheritance diagram for open3d::t::geometry::Image:
open3d::t::geometry::Geometry open3d::core::IsDevice

Public Types

enum class  InterpType {
  Nearest = 0 , Linear = 1 , Cubic = 2 , Lanczos = 3 ,
  Super = 4
}
 Image interpolation algorithms. More...
 
- Public Types inherited from open3d::t::geometry::Geometry
enum class  GeometryType {
  Unspecified = 0 , PointCloud = 1 , VoxelGrid = 2 , Octree = 3 ,
  LineSet = 4 , MeshBase = 5 , TriangleMesh = 6 , HalfEdgeTriangleMesh = 7 ,
  Image = 8 , RGBDImage = 9 , TetraMesh = 10 , OrientedBoundingBox = 11 ,
  AxisAlignedBoundingBox = 12
}
 Specifies possible geometry types. More...
 

Public Member Functions

 Image (int64_t rows=0, int64_t cols=0, int64_t channels=1, core::Dtype dtype=core::Float32, const core::Device &device=core::Device("CPU:0"))
 Constructor for image. More...
 
 Image (const core::Tensor &tensor)
 Construct from a tensor. The tensor won't be copied and memory will be shared. More...
 
virtual ~Image () override
 
ImageClear () override
 Clear image contents by resetting the rows and cols to 0, while keeping channels, dtype and device unchanged. More...
 
bool IsEmpty () const override
 Returns true if rows * cols * channels == 0. More...
 
ImageReset (int64_t rows=0, int64_t cols=0, int64_t channels=1, core::Dtype dtype=core::Float32, const core::Device &device=core::Device("CPU:0"))
 Reinitialize image with new parameters. More...
 
int64_t GetRows () const
 Get the number of rows of the image. More...
 
int64_t GetCols () const
 Get the number of columns of the image. More...
 
int64_t GetChannels () const
 Get the number of channels of the image. More...
 
core::Dtype GetDtype () const
 Get dtype of the image. More...
 
core::Device GetDevice () const override
 Get device of the image. More...
 
core::Tensor At (int64_t r, int64_t c) const
 Get pixel(s) in the image. More...
 
core::Tensor At (int64_t r, int64_t c, int64_t ch) const
 Get pixel(s) in the image. Returns a tensor with shape {}. More...
 
void * GetDataPtr ()
 Get raw buffer of the Image data. More...
 
const void * GetDataPtr () const
 Get raw buffer of the Image data. More...
 
core::Tensor AsTensor () const
 Returns the underlying Tensor of the Image. More...
 
Image To (const core::Device &device, bool copy=false) const
 Transfer the image to a specified device. More...
 
Image Clone () const
 Returns copy of the image on the same device. More...
 
Image To (core::Dtype dtype, bool copy=false, utility::optional< double > scale=utility::nullopt, double offset=0.0) const
 Returns an Image with the specified dtype. More...
 
ImageLinearTransform (double scale=1.0, double offset=0.0)
 Function to linearly transform pixel intensities in place. More...
 
Image RGBToGray () const
 Converts a 3-channel RGB image to a new 1-channel Grayscale image. More...
 
Image Resize (float sampling_rate=0.5f, InterpType interp_type=InterpType::Nearest) const
 Return a new image after resizing with specified interpolation type. More...
 
Image Dilate (int kernel_size=3) const
 Return a new image after performing morphological dilation. More...
 
Image Filter (const core::Tensor &kernel) const
 Return a new image after filtering with the given kernel. More...
 
Image FilterBilateral (int kernel_size=3, float value_sigma=20.0f, float distance_sigma=10.0f) const
 Return a new image after bilateral filtering. More...
 
Image FilterGaussian (int kernel_size=3, float sigma=1.0f) const
 Return a new image after Gaussian filtering. More...
 
std::pair< Image, ImageFilterSobel (int kernel_size=3) const
 Return a pair of new gradient images (dx, dy) after Sobel filtering. More...
 
Image PyrDown () const
 Return a new downsampled image with pyramid downsampling. More...
 
Image PyrDownDepth (float diff_threshold, float invalid_fill=0.f) const
 Edge and invalid value preserving downsampling by 2 specifically for depth images. More...
 
Image ClipTransform (float scale, float min_value, float max_value, float clip_fill=0.0f) const
 Return new image after scaling and clipping image values. More...
 
Image CreateVertexMap (const core::Tensor &intrinsics, float invalid_fill=0.0f)
 Create a vertex map from a depth image using unprojection. More...
 
Image CreateNormalMap (float invalid_fill=0.0f)
 Create a normal map from a vertex map. More...
 
Image ColorizeDepth (float scale, float min_value, float max_value)
 Colorize an input depth image (with Dtype UInt16 or Float32). More...
 
core::Tensor GetMinBound () const
 Compute min 2D coordinates for the data (always {0, 0}). More...
 
core::Tensor GetMaxBound () const
 Compute max 2D coordinates for the data ({rows, cols}). More...
 
open3d::geometry::Image ToLegacy () const
 Convert to legacy Image type. More...
 
std::string ToString () const
 Text description. More...
 
- Public Member Functions inherited from open3d::t::geometry::Geometry
virtual ~Geometry ()
 
GeometryType GetGeometryType () const
 Returns one of registered geometry types. More...
 
int Dimension () const
 Returns whether the geometry is 2D or 3D. More...
 
std::string GetName () const
 
void SetName (const std::string &name)
 
- Public Member Functions inherited from open3d::core::IsDevice
 IsDevice ()=default
 
virtual ~IsDevice ()=default
 
bool IsCPU () const
 
bool IsCUDA () const
 

Static Public Member Functions

static Image FromLegacy (const open3d::geometry::Image &image_legacy, const core::Device &Device=core::Device("CPU:0"))
 Create from a legacy Open3D Image. More...
 

Static Public Attributes

static constexpr bool HAVE_IPPICV = false
 Do we use IPP ICV for accelerating image processing operations? More...
 

Protected Attributes

core::Tensor data_
 

Additional Inherited Members

- Protected Member Functions inherited from open3d::t::geometry::Geometry
 Geometry (GeometryType type, int dimension)
 Parameterized Constructor. More...
 

Detailed Description

The Image class stores image with customizable rows, cols, channels, dtype and device.

Member Enumeration Documentation

◆ InterpType

Image interpolation algorithms.

Enumerator
Nearest 

Nearest neighbors interpolation.

Linear 

Bilinear interpolation.

Cubic 

Bicubic interpolation.

Lanczos 

Lanczos filter interpolation.

Super 

Super sampling interpolation (only downsample).

Constructor & Destructor Documentation

◆ Image() [1/2]

open3d::t::geometry::Image::Image ( int64_t  rows = 0,
int64_t  cols = 0,
int64_t  channels = 1,
core::Dtype  dtype = core::Float32,
const core::Device device = core::Device("CPU:0") 
)

Constructor for image.

Row-major storage is used, similar to OpenCV. Use (row, col, channel) indexing order for image creation and accessing. In general, (r, c, ch) are the preferred variable names for consistency, and avoid using width, height, u, v, x, y for coordinates.

Parameters
rowsNumber of rows of the image, i.e. image height. rows must be non-negative.
colsNumber of columns of the image, i.e. image width. cols must be non-negative.
channelsNumber of channels of the image. E.g. for RGB image, channels == 3; for grayscale image, channels == 1. channels must be greater than 0.
dtypeData type of the image.
deviceDevice where the image is stored.

◆ Image() [2/2]

open3d::t::geometry::Image::Image ( const core::Tensor tensor)

Construct from a tensor. The tensor won't be copied and memory will be shared.

Parameters
tensorTensor of the image. The tensor must be contiguous. The tensor must be 2D (rows, cols) or 3D (rows, cols, channels).

◆ ~Image()

virtual open3d::t::geometry::Image::~Image ( )
inlineoverridevirtual

Member Function Documentation

◆ AsTensor()

core::Tensor open3d::t::geometry::Image::AsTensor ( ) const
inline

Returns the underlying Tensor of the Image.

◆ At() [1/2]

core::Tensor open3d::t::geometry::Image::At ( int64_t  r,
int64_t  c 
) const
inline

Get pixel(s) in the image.

If channels == 1, returns a tensor with shape {}, otherwise returns a tensor with shape {channels,}. The returned tensor is a slice of the image's tensor, so when modifying the slice, the original tensor will also be modified.

◆ At() [2/2]

core::Tensor open3d::t::geometry::Image::At ( int64_t  r,
int64_t  c,
int64_t  ch 
) const
inline

Get pixel(s) in the image. Returns a tensor with shape {}.

◆ Clear()

Image& open3d::t::geometry::Image::Clear ( )
inlineoverridevirtual

Clear image contents by resetting the rows and cols to 0, while keeping channels, dtype and device unchanged.

Implements open3d::t::geometry::Geometry.

◆ ClipTransform()

Image open3d::t::geometry::Image::ClipTransform ( float  scale,
float  min_value,
float  max_value,
float  clip_fill = 0.0f 
) const

Return new image after scaling and clipping image values.

This is typically used for preprocessing a depth image. Images of shape (rows, cols, channels=1) and Dtypes UInt16 and Float32 are supported. Each pixel will be transformed by

  • x = x / scale
  • x = x < min_value ? clip_fill : x
  • x = x > max_value ? clip_fill : x

Use INFINITY, NAN or 0.0 (default) for clip_fill.

Returns
Transformed image of type Float32, with out-of-range pixels clipped and assigned the clip_fill value.

◆ Clone()

Image open3d::t::geometry::Image::Clone ( ) const
inline

Returns copy of the image on the same device.

◆ ColorizeDepth()

Image open3d::t::geometry::Image::ColorizeDepth ( float  scale,
float  min_value,
float  max_value 
)

Colorize an input depth image (with Dtype UInt16 or Float32).

The image values are divided by scale, then clamped within [min_value, max_value] and finally converted to an RGB image using the Turbo colormap as a lookup table.

Returns
Full color depth map of shape (rows, cols, channels=3) and Dtype UInt8.

◆ CreateNormalMap()

Image open3d::t::geometry::Image::CreateNormalMap ( float  invalid_fill = 0.0f)

Create a normal map from a vertex map.

The input vertex map image should be of shape (rows, cols, channels=3) and Dtype Float32. This uses a cross product of \(V(r, c+1)-V(r, c)\) and \(V(r+1, c)-V(r, c)\). The input vertex map is expected to be the output of CreateVertexMap. You may need to start with a filtered depth image (e.g. with FilterBilateral) to obtain good results.

Parameters
invalid_fillValue to fill in for invalid points, and to fill-in if no valid neighbor is found. Use NAN, INFINITY or 0.0 (default). Must be consistent with clip_fill in CreateVertexMap.
Returns
Normal map of shape (rows, cols, channels=3) and Dtype Float32, with invalid normals assigned the invalid_fill value.

◆ CreateVertexMap()

Image open3d::t::geometry::Image::CreateVertexMap ( const core::Tensor intrinsics,
float  invalid_fill = 0.0f 
)

Create a vertex map from a depth image using unprojection.

The input depth (of shape (rows, cols, channels=1) and Dtype Float32) is expected to be the output of ClipTransform.

Parameters
intrinsicsPinhole camera model of (3, 3) in Float64.
invalid_fillValue to fill in for invalid depths. Use NAN, INFINITY or 0.0 (default). Must be consistent with clip_fill in ClipTransform.
Returns
Vertex map of shape (rows, cols, channels=3) and Dtype Float32, with invalid points assigned the invalid_fill value.

◆ Dilate()

Image open3d::t::geometry::Image::Dilate ( int  kernel_size = 3) const

Return a new image after performing morphological dilation.

Supported datatypes are UInt8, UInt16 and Float32 with {1, 3, 4} channels. An 8-connected neighborhood is used to create the dilation mask.

Parameters
kernel_sizeAn odd number >= 3.

◆ Filter()

Image open3d::t::geometry::Image::Filter ( const core::Tensor kernel) const

Return a new image after filtering with the given kernel.

◆ FilterBilateral()

Image open3d::t::geometry::Image::FilterBilateral ( int  kernel_size = 3,
float  value_sigma = 20.0f,
float  distance_sigma = 10.0f 
) const

Return a new image after bilateral filtering.

Parameters
value_sigmaStandard deviation for the image content.
distance_sigmaStandard deviation for the image pixel positions.

Note: CPU (IPP) and CUDA (NPP) versions use different algorithms and will give different results:
CPU uses a round kernel (radius = floor(kernel_size / 2)),
while CUDA uses a square kernel (width = kernel_size).
Make sure to tune parameters accordingly.

◆ FilterGaussian()

Image open3d::t::geometry::Image::FilterGaussian ( int  kernel_size = 3,
float  sigma = 1.0f 
) const

Return a new image after Gaussian filtering.

Parameters
kernel_sizeOdd numbers >= 3 are supported.
sigmaStandard deviation of the Gaussian distribution.

◆ FilterSobel()

std::pair< Image, Image > open3d::t::geometry::Image::FilterSobel ( int  kernel_size = 3) const

Return a pair of new gradient images (dx, dy) after Sobel filtering.

Parameters
kernel_sizeSobel filter kernel size, either 3 or 5.

◆ FromLegacy()

Image open3d::t::geometry::Image::FromLegacy ( const open3d::geometry::Image image_legacy,
const core::Device Device = core::Device("CPU:0") 
)
static

Create from a legacy Open3D Image.

◆ GetChannels()

int64_t open3d::t::geometry::Image::GetChannels ( ) const
inline

Get the number of channels of the image.

◆ GetCols()

int64_t open3d::t::geometry::Image::GetCols ( ) const
inline

Get the number of columns of the image.

◆ GetDataPtr() [1/2]

void* open3d::t::geometry::Image::GetDataPtr ( )
inline

Get raw buffer of the Image data.

◆ GetDataPtr() [2/2]

const void* open3d::t::geometry::Image::GetDataPtr ( ) const
inline

Get raw buffer of the Image data.

◆ GetDevice()

core::Device open3d::t::geometry::Image::GetDevice ( ) const
inlineoverridevirtual

Get device of the image.

Implements open3d::t::geometry::Geometry.

◆ GetDtype()

core::Dtype open3d::t::geometry::Image::GetDtype ( ) const
inline

Get dtype of the image.

◆ GetMaxBound()

core::Tensor open3d::t::geometry::Image::GetMaxBound ( ) const
inline

Compute max 2D coordinates for the data ({rows, cols}).

◆ GetMinBound()

core::Tensor open3d::t::geometry::Image::GetMinBound ( ) const
inline

Compute min 2D coordinates for the data (always {0, 0}).

◆ GetRows()

int64_t open3d::t::geometry::Image::GetRows ( ) const
inline

Get the number of rows of the image.

◆ IsEmpty()

bool open3d::t::geometry::Image::IsEmpty ( ) const
inlineoverridevirtual

Returns true if rows * cols * channels == 0.

Implements open3d::t::geometry::Geometry.

◆ LinearTransform()

Image& open3d::t::geometry::Image::LinearTransform ( double  scale = 1.0,
double  offset = 0.0 
)
inline

Function to linearly transform pixel intensities in place.

\(image = scale * image + offset\).

Parameters
scaleFirst multiply image pixel values with this factor. This should be positive for unsigned dtypes.
offsetThen add this factor to all image pixel values.
Returns
Reference to self.

◆ PyrDown()

Image open3d::t::geometry::Image::PyrDown ( ) const

Return a new downsampled image with pyramid downsampling.

The returned image is formed by a chained Gaussian filter (kernel_size = 5, sigma = 1.0) and a resize (ratio = 0.5) operation.

Returns
Half sized downsampled depth image.

◆ PyrDownDepth()

Image open3d::t::geometry::Image::PyrDownDepth ( float  diff_threshold,
float  invalid_fill = 0.f 
) const

Edge and invalid value preserving downsampling by 2 specifically for depth images.

Only 1 channel Float32 images are supported. The returned image is formed by a chained Gaussian filter (kernel_size = 5, sigma = 1.0) and a resize (ratio = 0.5) operation.

Parameters
diff_thresholdThe Gaussian filter averaging ignores neighboring values if the depth difference is larger than this value.
invalid_fillThe Gaussian filter ignores these values (may be specified as NAN, INFINITY or 0.0 (default)).
Returns
Half sized downsampled Float32 depth image.

◆ Reset()

Image & open3d::t::geometry::Image::Reset ( int64_t  rows = 0,
int64_t  cols = 0,
int64_t  channels = 1,
core::Dtype  dtype = core::Float32,
const core::Device device = core::Device("CPU:0") 
)

Reinitialize image with new parameters.

◆ Resize()

Image open3d::t::geometry::Image::Resize ( float  sampling_rate = 0.5f,
InterpType  interp_type = InterpType::Nearest 
) const

Return a new image after resizing with specified interpolation type.

Downsample if sampling rate is < 1. Upsample if sampling rate > 1. Aspect ratio is always preserved.

◆ RGBToGray()

Image open3d::t::geometry::Image::RGBToGray ( ) const

Converts a 3-channel RGB image to a new 1-channel Grayscale image.

Uses formula \(I = 0.299 * R + 0.587 * G + 0.114 * B\).

◆ To() [1/2]

Image open3d::t::geometry::Image::To ( const core::Device device,
bool  copy = false 
) const
inline

Transfer the image to a specified device.

Parameters
deviceThe targeted device to convert to.
copyIf true, a new image is always created; if false, the copy is avoided when the original image is already on the targeted device.

◆ To() [2/2]

Image open3d::t::geometry::Image::To ( core::Dtype  dtype,
bool  copy = false,
utility::optional< double >  scale = utility::nullopt,
double  offset = 0.0 
) const

Returns an Image with the specified dtype.

Parameters
dtypeThe targeted dtype to convert to.
copyIf true, a new tensor is always created; if false, the copy is avoided when the original tensor already has the targeted dtype.
scaleOptional scale value. This is 1./255 for UInt8 -> Float{32,64}, 1./65535 for UInt16 -> Float{32,64} and 1 otherwise
offsetOptional shift value. Default 0.

◆ ToLegacy()

open3d::geometry::Image open3d::t::geometry::Image::ToLegacy ( ) const

Convert to legacy Image type.

◆ ToString()

std::string open3d::t::geometry::Image::ToString ( ) const

Text description.

Field Documentation

◆ data_

core::Tensor open3d::t::geometry::Image::data_
protected

Internal data of the Image, represented as a contiguous 3D tensor of shape {rows, cols, channels}. Image properties can be obtained from the tensor.

◆ HAVE_IPPICV

constexpr bool open3d::t::geometry::Image::HAVE_IPPICV = false
staticconstexpr

Do we use IPP ICV for accelerating image processing operations?


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