3D Image type and 3D image algorithm interfaces#

3D Image type definition#

class Image3d#

The 3D Image is represented by the 2D Image (type is visionflow::img::Image) and the transform 3D coefficient, which maps the pixel coordinates and pixel values of the 2D image to the 3D point coordinates.

Let \( Col_{img} \), \( Row_{img} \) and \( Val_{img} \) represent the x-axis coordinate, y-axis coordinate and gray value of the 2D image respectively, where the upper left corner of the 2D image represents the origin of the coordinate system, the x-axis is horizontal to the right, and the y-axis is vertically downward. The x-axis and y-axis of the 3D point coordinate system are consistent with the 2D image and follow the right-hand coordinate system rule, so the z-axis direction is inward form the 2D image plane. Here, the coefficients of \( Col_{img} \), \( Row_{img} \) and \( Val_{img} \) are mapped to 3D point coordinates \( (X, Y, Z) \) include \( x_{scale} \), \( y_{scale} \), \( z_{scale} \), \( x_{offset} \), \( y_{offset} \), \( z_{offset} \). The calculation formula is as follows:

\[\begin{split} P_{3d}= \begin {cases} X = Col_{img} * x_{scale} + x_{offset}\\ Y = Row_{img} * y_{scale} + y_{offset} \\ Z = Val_{img} * z_{scale} + z_{offset} \\ \end{cases} \end{split}\]

Note that \( x_{scale} \), \( y_{scale} \) and \( z_{scale} \) are non-zero float values, meanwhile the 2D Image is a single page and one channel image, and the data type is visionflow::Image::kDepthU16.

Public Functions

Image3d()#: Construct a new Image3d object by default.

Image3d(visionflow::img::Image img, float x_scale, float y_scale, float z_scale, float x_offset, float y_offset, float z_offset)#

Constructor with 2D image, x_scale, y_scale, z_scale, x_offset, y_offset and z_offset. Note the absolute values of x_scale, y_scale and z_scale should be greater than FLT_EPSILON.

Parameters:

img – 2D image, it’s a single page, one channel image of type visionflow::Image::kDepthU16.
x_scale – x_scale.
y_scale – y_scale.
z_scale – z_scale.
x_offset – x_offset.
y_offset – y_offset.
z_offset – z_offset.

Throws:

excepts::InvalidArgument – The absolute value of any of x_scale, y_scale and z_scale is less than or equal to FLT_EPSILON, or the input argument img is not a single page, one channel image of type visionflow::Image::kDepthU16.

Image3d(visionflow::img::Image img, std::vector<float> transform3d_coefficient)#

Constructor with 2D image and a vector of transform 3D coefficient.

Parameters:

img – 2D image, it’s a single page, one channel image of type visionflow::Image::kDepthU16.
transform3d_coefficient – The vector should contain 6 float values (x_scale, y_scale, z_scale, x_offset, y_offset, z_offset), with the absolute values of the index at 0~2 should be greater than FLT_EPSILON.

Throws:

excepts::InvalidArgument – The size of the argument transform3d_coefficient is not 6, or the absolute value of any of transform3d_coefficient with index at 0~2 (x_scale, y_scale, z_scale) is less than or equal to FLT_EPSILON, or the input argument img is not a single page, one channel image of type visionflow::Image::kDepthU16.

Image3d(const Image3d &rhs)#

Copy constructor.

Only copy the 2d Image and transform 3d coefficient data pointer, not the data. If you want to copy the data, you should use clone().

Parameters:: rhs – other Image.

Image3d(Image3d &&rhs) noexcept#

Move constructor.

Parameters:: rhs – other rvalue Image.

Image3d clone() const#

Deep copy.

Returns:: NO_DISCARD cloned 3d image.

Image3d roi(uint32_t x, uint32_t y, uint32_t w, uint32_t h) const#

Extract the sub-image based on the ROI. Note that this operation returns an Image3d which is a shallow copy and has non-contiguous memory.

Roi needs to be completely in Image3d, otherwise an excepts::InvalidArgument will be thrown.

Parameters:

x – X-coordinate of top-left point, should be greater than 0 and less than Image3d width.
y – Y-coordinate of top-left point, should be greater than 0 and less than Image3d height.
w – Width of roi box, should be greater than 0 and less than or equal width - x.
h – Height of roi box, should be greater than 0 and less than or equal height - y.

Throws:

excepts::DataNotFound – if Image is empty.
excepts::InvalidArgument – if bottom-right corner is out of range or if width or height is not greater than 0.

Returns:

NO_DISCARD sub Image3d of this Image3d.

Image3d roi(const geometry::Rect2i &rect) const#

Get sub-Image3d of Image3d.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: rect – Rectangular roi.
Returns:: NO_DISCARD sub-Image3d of this Image3d.

Image3d &set_image2d(visionflow::Image img)#

Set the 2D image data.

Parameters:: img – visionflow::Image image data.
Returns:: Image3d& reference to this object.

const visionflow::Image &image2d() const#

Get the 2D image data.

Returns:: NO_DISCARD visionflow::Image image data.

visionflow::Image &image2d()#

Get the mutable 2D image data.

Returns:: NO_DISCARD visionflow::Image image data.

std::vector<float> transform3d_coefficient() const#

Get the transform 3D coefficient.

Returns:: the vector of transform 3d coefficient (The order is x_scale, y_scale, z_scale, x_offset, y_offset, z_offset).

Image3d &set_transform3d_coefficient(const std::vector<float> &transform3d_coefficient)#

Set the transform 3D coefficient.

Parameters:: transform3d_coefficient – new transform 3D coefficient to set, the vector should contain 6 float values (x_scale, y_scale, z_scale, x_offset, y_offset, z_offset), with the absolute values of the index at 0~2 should be greater than FLT_EPSILON.
Throws:: excepts::InvalidArgument – The size of the argument transform3d_coefficient is not 6, or the absolute value of any of transform3d_coefficient with index at 0~2 (x_scale, y_scale, z_scale) is less than or equal to FLT_EPSILON.
Returns:: Image3d&

3D Image Algorithms#

enum visionflow::img3d::CorrectType#

The type of correct 3D image based on plane.

Values:

enumerator kZAxis#: Correct 3D image along z-axis.

enumerator kProject#: Correct 3D image along project direction.

enum visionflow::img3d::OuterFillType#

The pixel filling method for when performing plane correction, if the gray values of the output 3D image exceed the range [0, 65535].

Values:

enumerator kFillZero#: Fill with 0 when the output grayscale values are outside the range [0, 65535].

enumerator kFillStaturatedTrunc#: When the output grayscale value falls below 1, it is clamped to 1; when it exceeds 65535, it is clamped to 65535.

enumerator kFillPlaneValues#: Fill with the planar Z-value at the current XY coordinates, rounded to the nearest integer, unless it falls outside the range [0, 65535], in which case fill with 0.

Image3d visionflow::img3d::correct_based_plane(const Image3d &src, CorrectType correct_type = CorrectType::kProject, const geo3d::Plane3f &plane = geo3d::Plane3f(0, 0, 1, 0), float bias = 0, OuterFillType out_fill_type = OuterFillType::kFillZero)#

The point cloud in the input 3D image is corrected its height on the given plane.

Parameters:

src – input source 3D image.
correct_type – If it is kZAxis, the point cloud is corrected to the given plane along the Z axis, if it is kProject, it is corrected along the plane normal vector direction.
plane – the plane for 3D image corrected.
bias – Correction distance delay z-axis translation, the unit is mm.
out_fill_type – The filling method for values out the range of [0, 65535]. If it is kFillZero, it is filled with 0, kFillStaturatedTrunc means truncation to [1, 65535], and kFillPlaneValues filling values with plane values.