Image type and image algorithm interfaces#

Image type definition#

class Image#

The Image class.

Only support uint8, uint16 and float32 datatype temporarily. And the data arrangement should be N * [HWC] (with [B,G,R] order if it’s a color image).
An Image may contains multiple visible images like png or jpeg, tiff, etc. And you need to make sure that all the visible images have the same height and width, otherwise some errors would occurred. This will only check when importing and exporting data.

Public Types

enum Depth#

The Depth enum data type of image element.

Values:

enumerator kDepthU8 = 0#: Unsigned char.

enumerator kDepthU16 = 2#: Unsigned short.

enumerator kDepthF32 = 5#: 32-bit float

Public Functions

explicit Image(size_t visual_size = 0)#

Construct a new Image object.

Parameters:: visual_size – Visible image number in the Image.

Image(size_t visual_size, uint32_t height, uint32_t width, uint32_t channels = 1, Depth depth = kDepthU8)#

Construct a new Image object.

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

All the visible images have the same height, width, channels and depth.

Parameters:

visual_size – Visible image number in the Image.
height – Image height (rows).
width – Image width (cols).
channels – Channels of a single image.
depth – Element depth, oneof Depth.

Image(void *data_ptr, uint32_t height, uint32_t width, uint32_t channels = 1, Depth depth = kDepthU8, size_t step = 0)#

Construct a new single visual Image object with pre-allocated external data pointer.

Warning

The external data is not automatically deallocated, and the content may be changed by someone library, so you should take care of it.

Parameters:

data_ptr – The allocated external data pointer, the length of the data block should equal to height * width * channel * sizeof(depth).
height – image height (rows).
width – image width (cols).
channels – channel of single image.
depth – element depth, one of Depth{ kDepthU8, kDepthU16, kDepthF32 }.
step – Number of bytes each matrix row occupies. The value should include the padding bytes at the end of each row, if any. If the parameter is missing (default value: 0), no padding is assumed.

Image(const Image &rhs)#

Copy constructor.

Only copy the data pointer, not the data. If you want to copy the data, you should use clone().

Parameters:: rhs – other Image.

Image(Image &&rhs) noexcept#

Move constructor.

Parameters:: rhs – other rvalue Image.

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

Get roi of Image.

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

Parameters:

x – X-coordinate of top-left point, should be greater than 0 and less than Image width.
y – Y-coordinate of top-left point, should be greater than 0 and less than Image 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 roi Image of this Image.

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

Get roi of Image.

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 sub matrix.
Returns:: NO_DISCARD roi Image of this Image.

geometry::Size2i size(size_t visual_index = 0) const#

The size of Image at [visual_index].

Parameters:: visual_index – Index of visible images at [visual_index]. Default 0 means the first image size. If visual_index out of visual_size an excepts::InvalidArgument will be thrown.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD geometry::Size2i.

void resize(const geometry::Size2i &size)#

Set size of Image.

This will resize all the visible images to target-width and target-height.

Parameters:: size – geometry::Size2i, target-width and target-height.
Throws:: excepts::DataNotFound – if Image is empty.

void resize(uint32_t width, uint32_t height)#

Set size of Image.

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

Parameters:

width – Image width (cols).
height – Image height (rows).

void convert_channels(uint32_t channels, uint32_t visual_index)#

Convert channels of visible image at [visual_index] into target-channels. If visual_index is the default value,convert channels of each visible image into target-channels.

Source-channels need to equal to 1, 3, or 4 and target-channels need to equal to 1 or 3, otherwise an excepts::InvalidArgument will be thrown.

Parameters:

channels – Target-channels must be 1 or 3.
visual_index – Index of visible images at [visual_index] to be converted, If not set, all visible images will be converted.

Throws:

excepts::DataNotFound – if Image is empty.
excepts::InvalidArgument – if source-channels is not equal to 1, 3, or 4 or target-channels is not equal to 1 or 3.or visual_index out of visual_size.

void convert_channels(uint32_t channels)#

Overload of Image::convert_channels(uint32_t channels, uint32_tvisual_index). Convert all the visible images into the target-channels.

Parameters:: channels – Target-channels must be 1 or 3.

void convert_depth(Depth depth)#

Convert depth of each visible image into target-depth.

Parameters:: depth – Target-depth, oneof Depth.
Throws:: excepts::DataNotFound – if Image is empty.

Image clone(int32_t visual_index = -1) const#

Deep copy.

If visual_index < -1 or visual_index out of visual_size will throw an excepts::InvalidArgument.

Parameters:: visual_index – Index of visible images at [visual_index]. Default -1 means clone all the visible images.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD cloned images.

Image visual_image(size_t visual_index = 0)#

Get visible image at [visual_index].

If visual_index out of visual_size will throw an excepts::InvalidArgument.

Warning

The return Image data is deep reference of this Image, that means this Image would be changed if you change the return Image data.

Parameters:: visual_index – Index of visible images at [visual_index]. Default 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD visible image at [visual_index].

void from_file(const std::string &path, int32_t flag = -1)#

Read a single image from file.

Only support from bmp, png, jpeg, tiff and aqimg, otherwise an excepts::FileNotFound will be thrown.
For tiff and aqimg file, you need to make sure that all the visible images have the same height and width, otherwise an excepts::InvalidArgument will be thrown.

Parameters:

path – Image path.
flag – Refer to cv::ImreadModes

Throws:

excepts::FileNotFound – if the file is empty or file is not in the specified format.
excepts::DataNotFound – if a visible image in Image is empty.
excepts::InvalidArgument – if a visible image is diff in size form the first visible image.
excepts::CanNotOpenFile – if open aqimg failed.
excepts::ParseAqimgFailed – if parse aqimg context failed.

void from_files(const std::vector<std::string> &path, int32_t flag = -1)#

Read multiple visible images from files.

See also

from_file

See also

from_batch

Parameters:

path – Image paths.
flag – Same flag in from_file().

Throws:

excepts::FileNotFound – if the path is empty.

void from_batch(const std::vector<Image> &batch_image)#

Read multiple Image.

This function will not copy the images data, if you want to run with deep copy, please call clone() before or after. You need to make sure that all the visible images have the same height and width, otherwise an excepts::InvalidArgument will be thrown.

Parameters:

batch_image – Multiple Image to be merged.

Throws:

excepts::DataNotFound – if the batch_image have empty data.
excepts::InvalidArgument – if a visible image is diff in size form the first visible image.

void to_file(const std::string &path) const#

Save Image into file.

Image channels need to equal to 1, 3 or 4. For Image with visual_size greater than 1, only tiff format storage is supported, and you need to make sure that all the visible images have the same height and width. For Image with visual_size equal to 1, it supports png, jpg and tiff format storage. Otherwise an excepts::InvalidArgument will be thrown. Unlike from_file(), bmp or aqimg is no longer supported here.

Parameters:

path – File path where you want to save file.

Throws:

excepts::DataNotFound – if Image is empty.
excepts::InvalidArgument – if Image channels is not equal to 1, 3 or 4 or the storage format is incorrect or a visible image is diff in size form the first visible image.

void from_buffer(const Buffer &inbuf, uint32_t height, uint32_t width, uint32_t channels = 1, Depth depth = kDepthU8)#

Parse image from Buffer.

Warning

This function doesn’t support multiple visible images.

Parameters:

inbuf – Buffer.
height – Image height (rows).
width – Image width (cols).
channels – Channels of a single image.
depth – Element depth, oneof Depth.

Throws:

excepts::FileNotFound – if the file is empty.

Buffer to_buffer() const#

Reverse operation of from_buffer().

This function doesn’t support multiple visible images, otherwise an excepts::InvalidArgument will be thrown.

Throws:: excepts::InvalidArgument – if Image visual_size is not equal to 1.
Returns:: NO_DISCARD Buffer out buffer.

Buffer dump() const#

Dump the Image into binary buffer.

Image channels need to equal to 1, 3 or 4. For Image with visual_size greater than 1, you need to make sure that all the visible images have the same height and width. Otherwise an excepts::InvalidArgument will be thrown.

Throws:

excepts::DataNotFound – if Image is empty.
excepts::InvalidArgument – if Image channels is not equal to 1, 3 or 4 or a visible image is diff in size form the first visible image.

Returns:

NO_DISCARD the binary buffer.

void load(const Buffer &buffer)#

Load the Image from binary buffer.

you need to make sure that all the visible images have the same height and width, otherwise an excepts::InvalidArgument will be thrown.

Parameters:

buffer – The binary buffer.

Throws:

excepts::FileNotFound – if the file is empty.
excepts::DataNotFound – if a visible image in Image is empty.
excepts::InvalidArgument – if a visible image is diff in size form the first visible image.

void show(uint32_t wait_time = 0, const std::string &win_name = "image", size_t visual_index = 0) const#

Show visible image at [visual_index].

Show this image in window named as win_name and wait wait_time milli-seconds. If depth of visible image is not kDepthU8, image will de map to kDepthU8 automaticaly.

Warning

Only support Windows now.

Parameters:

wait_time – Times should the window shows. If set wait_time as 0, this window will show and wait until clicked.
win_name – Window name.
visual_index – Index of visible images at [visual_index]. Default 0 means the first image. If visual_index out of visual_size will throw an excepts::InvalidArgument.

Throws:

excepts::InvalidArgument – if visual_index out of visual_size.

const void *data(size_t visual_index = 0) const#

Readonly data pointer of visible image at [visual_index].

If visual_index out of visual_size will throw an excepts::InvalidArgument. If the visible image data is not continuous will throw an excepts::LogicError.

Parameters:

visual_index – Index of visible images at [visual_index]. Default 0 means the first image.

Throws:

excepts::InvalidArgument – if visual_index out of visual_size.
excepts::LogicError – if the visible image is not continuous.

Returns:

NO_DISCARD readonly data pointer.

void *data(size_t visual_index = 0)#

Mutable data pointer of visible image at [visual_index].

If visual_index out of visual_size will throw an excepts::InvalidArgument. If the visible image data is not continuous will throw an excepts::LogicError.

Parameters:

visual_index – Index of visible images at [visual_index]. Default 0 means the first image.

Throws:

excepts::InvalidArgument – if visual_index out of visual_size.
excepts::LogicError – if the visible image is not continuous.

Returns:

NO_DISCARD mutable data pointer.

size_t data_size(size_t visual_index = 0) const#

Data size of visible image at [visual_index].

Equal to height() * width() * channels().

Parameters:: visual_index – Index of visible images at [visual_index]. Default 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD data size.

size_t data_byte_size(size_t visual_index = 0) const#

Data byte size of visible image at [visual_index].

Equal to height() * width() * channels() * element_size. Temporary, if depth() is kDepthU8, its equal to data_size().

Parameters:: visual_index – Index of visible images at [visual_index]. Default 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD data byte size.

uint32_t height(size_t visual_index = 0) const#

Image height (rows) of visible image at [visual_index].

Parameters:: visual_index – Index of visible images at [visual_index]. Default 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD image height of visible image at [visual_index].

uint32_t width(size_t visual_index = 0) const#

Image width (clos) of visible image at [visual_index].

Parameters:: visual_index – Index of visible images at [visual_index]. Default 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD image width of visible image at [visual_index].

uint32_t channels(size_t visual_index = 0) const#

Image channels of visible image at [visual_index].

Usually its 1 (gray image) or 3 (BGR image).

Parameters:: visual_index – Index of visible images at [visual_index]. Default 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD image channels of visible image at [visual_index].

uint32_t total_channels() const#

Total Image channels.

Usually gray image channels is 1 and BGR image channels is 3. If this Image is multiple visible images, this function wll return total channels of all the visible images.

Throws:: excepts::DataNotFound – if Image is empty.
Returns:: NO_DISCARD total channels of all the visible images.

Depth depth(size_t visual_index = 0) const#

Image depth of visible image at [visual_index].

Parameters:: visual_index – Index of visible images at [visual_index]. Default 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD image depth of visible image at [visual_index].

bool empty() const#

Empty if Image is empty.

Returns:: NO_DISCARD true if visual_size equal to 0 or a visible image is empty.

size_t visual_size() const#

Visual size.

Returns:: NO_DISCARD visible image number in the Image.

bool is_multi_visual() const#

Is multi visual.

Returns:: NO_DISCARD true if this Image have multiple visible images.

void release()#: Release image data.

Public Static Functions

static Image FromFile(const std::string &path, int32_t flag = -1)#

Read a single image from file.

Only support from bmp, png, jpeg, tiff and aqimg, otherwise an excepts::FileNotFound will be thrown.
For tiff and aqimg file, you need to make sure that all the visible images have the same height and width, otherwise an excepts::InvalidArgument will be thrown.

Parameters:

path – Image path.
flag – Refer to cv::ImreadModes

Throws:

excepts::FileNotFound – if the file is empty or file is not in the specified format.
excepts::DataNotFound – if a visible image in Image is empty.
excepts::InvalidArgument – if a visible image is diff in size form the first visible image.
excepts::CanNotOpenFile – if open aqimg failed.
excepts::ParseAqimgFailed – if parse aqimg context failed.

static Image Zeros(size_t visual_size, const geometry::Size2i &size, uint32_t channels = 1, Depth depth = kDepthU8)#

Construct an image with all pixels init with 0.

Parameters:

visual_size – Visible image number in the Image.
size – Image size to create.
channels – Channels of a single image.
depth – Element depth, oneof Depth.

Returns:

Image the image object.

static inline Image Load(const Buffer &encoded_buffer)#

Load image object from buffer.

Parameters:: encoded_buffer – Image data buffer.
Returns:: Image

using visionflow::Image = visionflow::img::Image #: export the visionflow::img::Image type into visionflow namespace.

class SubImage#

SubImage is a class that contains only the contents of a sub-image, but is able to determine its position within the original image, it consists of two parts, the submap and its position information in the original map.

Public Functions

explicit SubImage(Image image, geometry::Matrix3f transform_matrix, geometry::Size2i raw_image_size = {})#

Construct a new Sub Image object.

Note

The data in the visionflow::Image will not be copied, which means that if you modify the data content in the image later, the data of the image in the sub-image will also be modified. If this is not the behavior you expect, you can call visionflow::Image::clone() explicitly like below:

auto sub_image = std::make_shared<SubImage>(image.clone(),
visionflow::geometry::Matrix3f());

Parameters:

image – The sub image after transform.
transform_matrix – The transform matrix to transform sub-region in the raw image to this SubImage.
raw_image_size – The size of the raw image, empty by default.

const Image &image() const#

Get the sub image after transform.

See also

SubImage(Image image, geometry::Matrix3f transform_matrix) for more details.

Note

Do not modify the data in the image without clone,

Returns:: NO_DISCARD const& visionflow::Image

Image &image()#

Get the mutable sub image after transform.

Returns:: Image& The sub-image.

const geometry::Size2i &raw_image_size() const#

Get the size of the raw image.

Returns:: NO_DISCARD const& geometry::Size2i

Image raw_image(const geometry::Size2i &image_size = {}) const#

Get the sub-region in the raw image.

Note

1.If image size is not empty, it will be preferred as the size of the output image. 2.If image size is empty and raw image size is not empty, then raw image size will be used as the size of the output image. 3.If both image size and raw image size are empty, an appropriate size to cover the output will be automatically calculated.

Parameters:: image_size – The size of the output image.
Throws:: excepts::InvalidArgument – If the image size is illegal.
Returns:: NO_DISCARD visionflow::Image

const geometry::Matrix3f &transform_matrix() const#

Get the transform matrix to transform sub-region in the raw image to this SubImage.

Returns:: NO_DISCARD const& visionflow::geometry::Matrix3f

SubImage &set_image(Image image)#

Set the sub image after transform.

See also

SubImage(Image image, geometry::Matrix3f transform_matrix) for more details.

Note

The data in the visionflow::Image will not be copied,

Parameters:: image – visionflow::Image
Returns:: SubImage& reference to this object.

SubImage &set_raw_image_size(geometry::Size2i image_size)#

Set the size of raw image.

Parameters:: image_size – The size of the raw image.
Throws:: excepts::InvalidArgument – If the image size is illegal.
Returns:: SubImage&

SubImage &set_transform_matrix(geometry::Matrix3f transform_matrix)#

Set the transform matrix to transform sub-region in the raw image to this SubImage.

Parameters:: transform_matrix – visionflow::geometry::Matrix3f
Returns:: SubImage& reference to this object.

SubImage clone() const#

Deep copy.

Returns:: NO_DISCARD cloned sub-image.

using visionflow::SubImage = img::SubImage #: export img::SubImage into visionflow namespace.

Image Algorithms#

enum LineType#

types of line

Values:

enumerator kFilled = -1#

enumerator kLine4 = 4#: 4-connected line

enumerator kLine8 = 8#: 8-connected line

enumerator kLineAntiAliased = 16#: anti-aliased line

enum ColorType#

ColorType Enumerate of color space.

Values:

enumerator kGray = 1#: Gray color space.

enumerator kBGR = 3#: BGR color space.

visionflow::img::SubImage transform(const visionflow::img::Image &image, const visionflow::View &view, int flags = 1, int border_type = 0, std::vector<int> border_color = {0})#

Get the roi original image sub-image corresponding to View.

Parameters:

image – Original image.
view – View.
flags – combination of interpolation methods (INTER_LINEAR=0 or INTER_NEAREST=1). See cv::InterpolationFlags in OpenCV for more details.
border_type – pixel extrapolation method (BORDER_CONSTANT=0 or BORDER_REPLICATE=1). See cv::BorderTypes in OpenCV for more details.
border_color – the border color, The size should be 0, 1 or equal to the Image::total_channels(). border with zero by default.

Returns:

NO_DISCARD roi original image sub-image.

std::vector<visionflow::img::SubImage> transform(const visionflow::img::Image &image, const std::vector<visionflow::View> &views, int flags = 1, int border_type = 0, const std::vector<int> &border_color = {0})#

Get the roi original image sub-image corresponding to each View.

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

Parameters:

image – Original image.
views – std::vector<View>.
flags – combination of interpolation methods (INTER_LINEAR=0 or INTER_NEAREST=1). See cv::InterpolationFlags in OpenCV for more details.
border_type – pixel extrapolation method (BORDER_CONSTANT=0 or BORDER_REPLICATE=1). See cv::BorderTypes in OpenCV for more details.
border_color – the border color, The size should be 0, 1 or equal to the Image::total_channels(). border with zero by default.

Returns:

std::vector<visionflow::img::SubImage> the roi original image sub-image corresponding to each View.

float similar(const visionflow::img::Image &src, const visionflow::img::Image &dst)#

Compare if two Image are similar.

Calculate similarity using pHash algorithm.

Parameters:

src – The first Image.
dst – The second Image.

Returns:

NO_DISCARD float the Hamming distance representing the similarity between two Image, from 0 to 1.

void convert_color(visionflow::img::Image &image, ColorType color_type)#

Convert Image to gray scale or BGR color.

Parameters:

image – [inout] The Image.
color_type – The color type, gray or BGR.

std::vector<double> mean(const visionflow::img::Image &image)#

Compute the mean of Image.

Parameters:: image – The Image.
Returns:: std::vector<double> The mean of Image.

visionflow::geometry::MultiPolygon2f find_polygons(const visionflow::img::Image &image)#

Find contours in the image and convert the contours into polygon.

Parameters:: image – The binary image, which should contains only one binary image with DepthU8.
Returns:: visionflow::geometry::MultiPolygon2f

void draw(visionflow::img::Image &image, const visionflow::geometry::MultiPolygon2f &polygons, std::vector<int> color = {}, int thickness = 1, LineType line_type = kLine8)#

Draw polygons on the image.

Parameters:

image – [inout] The image to be mask.
polygons – mask polygons.
color – color, The size should be 0, 1 or equal to the Image::total_channels(). mask with zero by default.
thickness – Thickness of lines the contours are drawn with. If it is negative, the contour interiors are drawn.
line_type – Line connectivity. See LineType.

void draw(visionflow::img::SubImage &sub_image, const visionflow::geometry::MultiPolygon2f &polygons, std::vector<int> color = {}, int thickness = 1, LineType line_type = kLine8)#

Draw polygons on the sub-image, This function will only draw the regions on the sub-image, the polygon regions out of the sub-image will be ignored.

Parameters:

sub_image – [inout] The sub-image to be mask.
polygons – mask polygons.
color – color, The size should be equal to the Image::total_channels(). mask with zero by default.
thickness – Thickness of lines the contours are drawn with. If it is negative, the contour interiors are drawn.
line_type – Line connectivity. See LineType.

visionflow::img::Image polar_transform(const visionflow::img::Image &image, const visionflow::geometry::Point2f &center, float radius, const visionflow::View &view)#

Convert an image from Cartesian to polar coordinates.

Parameters:

image – The input image to be transformed.
center – The transformation center.
radius – The radius of the bounding circle to transform.
view – View.

Returns:

The polar image in a new Image object.