Image type and image algorithm interfaces#

Image type definition#

class Image#

The Image class.

  1. 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).

  2. 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 = visionflow::img::Image::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 = visionflow::img::Image::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:
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:
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, double alpha = 1.0, double beta = 0.0)#

Convert depth of each visible image into target-depth.

\[m(x,y) = \alpha (*this)(x,y) + \beta \]

Parameters:

  • depth – Target-depth, one of Depth.

  • alpha – The coefficient to multiply with image

  • beta – The coefficient to be added with image

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.

  1. Only support from bmp, png, jpeg, tiff and aqimg, otherwise an excepts::FileNotFound will be thrown.

  2. 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:
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:
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:
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:
void from_buffer(const Buffer &inbuf, uint32_t height, uint32_t width, uint32_t channels = 1, Depth depth = visionflow::img::Image::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, one of 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 std::string &format_extension = "") 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.

Note

multi-page image will be forced to encode as TIFF format regardless of the format that user set.

Parameters:

format_extension – The format to decode single-page image when serialization. Supported format :”.bmp” “.png” “.jpeg” “jpg” “.tif”. Single-page 8bit image will be be encoded into PNG if the format user set is not supported or not set by default, single-page 16bit or float image will be encoded into PNG by default, and multi-page image will be encoded into TIFF by default.

Throws:
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:
int 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.

Returns:

the key pressed on the image.

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:
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:
Returns:

NO_DISCARD mutable data pointer.

bool is_continuous(size_t visual_index = 0) const#

Determined whether visible image at [visual_index] is memory continuous.

If visual_index out of visual_size will throw an excepts::InvalidArgument. Visible image with empty data will be regard as continuous.

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 data continuous or not.

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.

  1. Only support from bmp, png, jpeg, tiff and aqimg, otherwise an excepts::FileNotFound will be thrown.

  2. 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:
static Image FromFiles(const std::vector<std::string> &path, int32_t flag = -1)#

Read multiple visible images from files.

See also

from_files

Parameters:
Returns:

Image the image object.

static Image FromBuffer(const Buffer &inbuf, uint32_t height, uint32_t width, uint32_t channels = 1, Depth depth = visionflow::img::Image::kDepthU8)#

Parse image from Buffer.

See also

from_buffer

Parameters:

  • inbuf – Buffer.

  • height – Image height (rows).

  • width – Image width (cols).

  • channels – Channels of a single image.

  • depth – Element depth, one of Depth.

Returns:

Image the image object.

static Image FromBatch(const std::vector<Image> &batch_image)#

Read multiple Image.

See also

from_batch

Parameters:

batch_image – Multiple Image to be merged.

Returns:

Image the image object.

static Image Zeros(size_t visual_size, const geometry::Size2i &size, uint32_t channels = 1, Depth depth = visionflow::img::Image::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 visionflow::img::LineType#

types of line

Values:

enumerator kLine4 = 4#

4-connected line

enumerator kLine8 = 8#

8-connected line

enumerator kLineAntiAliased = 16#

anti-aliased line

visionflow::img::SubImage visionflow::img::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:

roi original image sub-image.

std::vector<visionflow::img::SubImage> visionflow::img::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=1 or INTER_NEAREST=0). 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 visionflow::img::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:

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

enum visionflow::img::ColorType#

ColorType Enumerate of color space.

Values:

enumerator kGray = 1#

Gray color space.

enumerator kBGR = 3#

BGR color space.

enum visionflow::img::ColorSpace#

Enumerate of image color space.

Values:

enumerator kColorGray = 1#

Gray color space.

enumerator kColorBGR = 3#

BGR color space.

enumerator kColorBGRA = 4#

BGRA color space.

enumerator kColorRGB = 5#

RGB color space.

enumerator kColorRGBA = 6#

RGBA color space.

Image visionflow::img::data_to_image(void *data, uint32_t height, uint32_t width, ColorSpace src_color, ColorType dst_color, uint32_t padding_pixels = 0, Image::Depth depth = Image::kDepthU8, bool force_copy = true)#

Convert image data given by data pointer to Image object with the dst_color.

Parameters:

  • data – The raw image data pointer.

  • height – The image height.

  • width – The image width.

  • src_color – The source image color space.

  • dst_color – The destination image color type, should be gray or BGR as the img::Image object only support gray and BGR color.

  • padding_pixels – Number of padding pixels at the end of each row on the source data pinter, if any. If the parameter is missing (default value: 0), no padding is assumed.

  • depth – The source image depth. The output image depth will be as same as the source.

  • force_copy – It will force copy data from src image even if channel of src image equal to target channel.

Returns:

Image object.

void visionflow::img::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> visionflow::img::mean(const visionflow::img::Image &image)#

Compute the mean of Image.

Parameters:

image – The Image.

Returns:

std::vector<double> The mean of Image, with size equal to the image channels.

visionflow::geometry::MultiPolygon2f visionflow::img::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 visionflow::img::draw(visionflow::img::Image &image, const visionflow::geometry::MultiPolygon2f &polygons, std::vector<int> color = {}, int thickness = 1, LineType line_type = visionflow::img::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 visionflow::img::draw(visionflow::img::Image &image, const visionflow::geometry::Line2f &line, std::vector<int> color = {}, int thickness = 1, LineType line_type = img::kLine8)#

Render a line onto an image.

Parameters:

  • image – [inout] The Image object where the line will be rendered.

  • line – the Line2f object to be drawn.

  • 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. Must be a non-negative value, default is 1.

  • line_type – Line connectivity. See LineType.

Throws:

excepts::InvalidArgument – Throws if the thickness is negative value.

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

Render a polygon onto an image.

Parameters:

  • image – [inout] The Image object where the polygon will be rendered.

  • polygon – the Polygon2f object to be drawn.

  • 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. Default is 1.

  • line_type – Line connectivity. See LineType.

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

Render a circle onto an image.

Parameters:

  • image – [inout] The Image object where the circle will be rendered.

  • circle – the Circle2f object to be drawn.

  • 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. Default is 1.

  • line_type – Line connectivity. See LineType.

void visionflow::img::draw(visionflow::img::Image &image, const visionflow::geometry::Point2f &point, std::vector<int> color = {})#

Render a point onto an image.

Parameters:

  • image – [inout] The Image object where the point will be rendered.

  • point – the Point2f object to be drawn.

  • color – color, The size should be 0, 1 or equal to the Image::total_channels(). mask with zero by default.

void visionflow::img::draw(visionflow::img::Image &image, const visionflow::geometry::MultiPoint2f &multi_points, const std::vector<int> &color = {})#

Render multiple points onto an image.

Parameters:

  • image – [inout] The Image object where the multiple points will be rendered.

  • multi_points – the MultiPoint2f object to be drawn.

  • color – color, The size should be 0, 1 or equal to the Image::total_channels(). mask with zero by default.

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

Render a ring onto an image.

Parameters:

  • image – [inout] The Image object where the ring will be rendered.

  • ring – the Ring2f object to be drawn.

  • 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. Default is 1.

  • line_type – Line connectivity. See LineType.

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

Render an ellipse onto an image.

Parameters:

  • image – [inout] The Image object where the ellipse will be rendered.

  • ellipse – the Ellipse2f object to be drawn.

  • 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. Default is 1.

  • line_type – Line connectivity. See LineType.

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

Render a rectangle onto an image.

Parameters:

  • image – [inout] The Image object where the ellipse will be rendered.

  • rect – the Rect2f object to be drawn.

  • 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. Default is 1.

  • line_type – Line connectivity. See LineType.

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

Render a fold line onto an image.

Parameters:

  • image – [inout] The Image object where the fold line will be rendered.

  • line_string – the LineString2f object to be drawn.

  • 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. Must be a non-negative value, default is 1.

  • line_type – Line connectivity. See LineType.

Throws:

excepts::InvalidArgument – Throws if the thickness is negative value.

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

Render a line segment onto an image.

Parameters:

  • image – [inout] The Image object where the line segment will be rendered.

  • segment – the Segment2f object to be drawn.

  • 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. Must be a non-negative value, default is 1.

  • line_type – Line connectivity. See LineType.

Throws:

excepts::InvalidArgument – Throws if the thickness is negative value.

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

Render multiple line segments onto an image.

Parameters:

  • image – [inout] The Image object where the multiple line segments will be rendered.

  • multi_seg – the MultiSegment2f object to be drawn.

  • 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. Must be a non-negative value, default is 1.

  • line_type – Line connectivity. See LineType.

Throws:

excepts::InvalidArgument – Throws if the thickness is negative value.

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

Render an arc onto an image.

Parameters:

  • image – [inout] The Image object where the arc will be rendered.

  • arc – the Arc2f object to be drawn.

  • 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. Default is 1.

  • line_type – Line connectivity. See LineType.

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

Render a rotated rectangle onto an image.

Parameters:

  • image – [inout] The Image object where the rotated rectangle will be rendered.

  • rotate_rect – the RotateRect2f object to be drawn.

  • 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. Default is 1.

  • line_type – Line connectivity. See LineType.

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

Render a ray onto an image.

Parameters:

  • image – The Image object where the ray will be rendered.

  • ray – the Ray2f object to be drawn.

  • 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. Must be a non-negative value, default is 1.

  • line_type – Line connectivity. See LineType.

Throws:

excepts::InvalidArgument – Throws if the thickness is negative value or the direction of ray is (0,0) which does not mean any specific direction.

void visionflow::img::draw(visionflow::img::SubImage &sub_image, const visionflow::geometry::MultiPolygon2f &polygons, std::vector<int> color = {}, int thickness = 1, LineType line_type = visionflow::img::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::geometry::Size2i visionflow::img::get_text_size(const std::string &u8str, uint32_t font_height_pixel = 32, const std::string &font_name = "")#

Get the text box size of the text string encoded by utf8.

Parameters:

  • u8str – the text string to be drawn.

  • font_height_pixel – The maximum pixel height of the character in the font, such as the height of “|” in many fonts. Default is 32 pixel.

  • font_name – The font name to be used. If not set Will use several predefined common fonts.

Returns:

visionflow::geometry::Size2i The text bounding box size.

void visionflow::img::draw(visionflow::img::Image &image, const std::string &u8str, std::vector<int> color, const visionflow::geometry::Point2f &pos, uint32_t font_height_pixel = 32, const visionflow::geometry::Radian &angle = 0, const std::string &font_name = "", int pos_mode = 0)#

Draw a text string encoded by utf8 onto image.

Parameters:

  • image – [inout] The Image object where the text string will be rendered.

  • u8str – the text string to be drawn.

  • color – the color of the fonts. The size should be 0, 1 or equal to the Image::total_channels(). mask with zero by default.

  • pos – The position of the first character to be drawn.

  • font_height_pixel – The maximum pixel height of the character in the font, such as the height of “|” in many fonts. Default is 32 pixel.

  • angle – The angle of the string’s base line. Default is 0.

  • font_name – The font name to be used. If not set Will use several predefined common fonts.

  • pos_mode – Starting point positioning mode, which defines the meaning of the pos parameter: 0 - Baseline mode: pos represents the starting point of the text baseline. 1 - Top-left corner mode: pos represents the top-left corner of the text bounding box. 2 - Bottom-left corner mode: pos represents the bottom-left corner of the text bounding box.

Throws:

  • excepts::UnknownError – Throws if the cannot initialize FreeType library or cannot open the font file.

  • excepts::FileNotFound – Throws if the font name not exist in registry or the font file not exists.

visionflow::img::Image visionflow::img::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.

std::string visionflow::img::fingerprint(const visionflow::img::Image &image)#

Get the fingerprint of the image (based on MD5)

Parameters:

image – the image

Returns:

std::string fingerprint string.

double visionflow::img::min(const visionflow::img::Image &image, const visionflow::geometry::MultiPolygon2f &region, int channel = -1)#

Get the minimum pixel value in a specified area of an image.

Parameters:
Returns:

double

double visionflow::img::max(const visionflow::img::Image &image, const visionflow::geometry::MultiPolygon2f &region, int channel = -1)#

Get the maximum pixel value in a specified area of an image.

Parameters:
Returns:

double

double visionflow::img::mean(const visionflow::img::Image &image, const visionflow::geometry::MultiPolygon2f &region, int channel = -1)#

Get the mean pixel value in a specified area of an image.

Parameters:
Returns:

double

double visionflow::img::contrast(const visionflow::img::Image &image, const visionflow::geometry::MultiPolygon2f &region)#

Get the contrast in a specified area of an gray image. If the image has multi channels, convert the multi-channel image to a single channel image, by calculating the mean value of all channels.

Parameters:
Returns:

double

double visionflow::img::min_gray(const visionflow::img::Image &image, const visionflow::geometry::MultiPolygon2f &region)#

Get the minimum value in a specified area of an gray image. If the image has multi channels, convert the multi-channel image to a single channel image, by calculating the mean value of all channels.

Parameters:
Returns:

double

double visionflow::img::max_gray(const visionflow::img::Image &image, const visionflow::geometry::MultiPolygon2f &region)#

Get the maximum value in a specified area of an gray image. If the image has multi channels, convert the multi-channel image to a single channel image, by calculating the mean value of all channels.

Parameters:
Returns:

double

enum visionflow::img::BorderTypes#

Various border types, image boundaries are denoted with |

See also

border_interpolate, copy_make_border

Values:

enumerator kBorderConstant = 0#

iiiiii|abcdefgh|iiiiiii with some specified i

enumerator kBorderReplicate = 1#

aaaaaa|abcdefgh|hhhhhhh

enumerator kBorderReflect = 2#

fedcba|abcdefgh|hgfedcb

enumerator kBorderWrap = 3#

cdefgh|abcdefgh|abcdefg

enumerator kBorderReflect101 = 4#

gfedcb|abcdefgh|gfedcba

enumerator kBorderTransparent = 5#

uvwxyz|abcdefgh|ijklmno

enumerator kBorderReflect_101 = kBorderReflect101#

same as kBorderReflect101

enumerator kBorderDefault = kBorderReflect101#

same as kBorderReflect101

enumerator kBorderIsolated = 16#

do not look outside of ROI

enum visionflow::img::MorphTypes#

morphology types

Values:

enumerator kMorphErode = 0#

erode

enumerator kMorphDilate = 1#

dilate

enumerator kMorphOpen = 2#

opening operation(erode+dilate)

enumerator kMorphClose = 3#

closing operation(dilate+erode)

enumerator kMorphGradient = 4#

morphological gradient(dilate-erode)

enumerator kMorphTopHat = 5#

top hat(src-opening)

enumerator kMorphBlackHat = 6#

black hat(closing-src)

enumerator kMorphHitMiss = 7#

hit or miss(only supported for kDepthU8 single-channel binary images)

enum visionflow::img::MorphShapes#

shape of the structuring element

Values:

enumerator kMorphRect = 0#

a rectangular structuring element:

\[E_{ij}=1\]

enumerator kMorphCross = 1#

a cross-shaped structuring element:

\[\begin{split}E_{ij} = \begin{cases} 1 & \texttt{if } < {i=\texttt{anchor.y } {or } {j=\texttt{anchor.x}}} < \\0 & \texttt{otherwise} \end{cases}\end{split}\]

enumerator kMorphEllipse = 2#

an elliptic structuring element, that is, a filled ellipse inscribed into the rectangle Rect(0, 0, ellipse_size.width, ellipse_size.height)

enum visionflow::img::FlipFlags#

flip flags

Values:

enumerator kFlipVertical = 0#

up down flip

enumerator kFlipHorizontal = 1#

left right

enumerator kFlipBoth = 2#

left right and up down

enumerator kFlip45 = 3#

flip around 45 degree diagonal (same as transpose)

enumerator kFlip135 = 4#

flip around 135 degree diagonal (same as kBoth + kFlip45)

enum visionflow::img::InterMethod#

interpolation method

Values:

enumerator kInterNearest = 0#

nearest neighbor interpolation

enumerator kInterLinear = 1#

bilinear interpolation

enumerator kInterCubic = 2#

bicubic interpolation

enumerator kInterArea = 3#

resampling using pixel area relation. It may be a preferred method for image decimation, as it gives moire’-free results. But when the image is zoomed, it is similar to the kInterNearest method.

enumerator kInterMax = 7#

mask for interpolation codes

void visionflow::img::gaussian_blur(Image &image, const geometry::Size2i &ksize, double sigma_x, double sigma_y = 0, bool high_pass = false, double alpha = 1, double beta = 0, BorderTypes border_type = img::kBorderDefault)#

Blurs an image using a Gaussian filter.

Parameters:

  • image – [inout] input image; the image can have any number of channels, which are processed independently, but the depth should be CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.

  • ksize – Gaussian kernel size. ksize.width and ksize.height can differ but they both must be positive and odd. Or, they can be zero’s and then they are computed from sigma.

  • sigma_x – Gaussian kernel standard deviation in X direction.

  • sigma_y – Gaussian kernel standard deviation in Y direction; if sigma_y is zero, it is set to be equal to sigma_x, if both sigmas are zeros, they are computed from ksize.width and ksize.height;

  • high_pass – flag indicating whether to perform high-pass filtering

  • alpha – gain factor to adjust the contrast of the filtered image (only applicable when high_pass is true)

  • beta – bias term to adjust the brightness of the filtered image (only applicable when high_pass is true)

  • border_type – pixel extrapolation method, see BorderTypes. kBorderWrap is not supported.

Throws:

excepts::InvalidArgument – if image type error.

void visionflow::img::box_blur(Image &image, int ddepth, const geometry::Size2i &ksize, bool high_pass = false, double alpha = 1, double beta = 0, bool normalize = true, BorderTypes border_type = img::kBorderDefault)#

Blurs an image using a box filter.

Parameters:

  • image – [inout] input image; the image can have any number of channels.

  • ddepth – destination image depth, set it to -1 to use the same depth as the input image.

  • ksize – blurring kernel size; width and height can differ but they both must be positive and odd.

  • high_pass – flag indicating whether to perform high-pass filtering (subtracting the low-pass filtered image from the original image).

  • alpha – gain factor to adjust the contrast of the filtered image (only applicable when high_pass is true).

  • beta – bias term to adjust the brightness of the filtered image (only applicable when high_pass is true).

  • normalize – flag indicating whether to normalize the kernel to achieve unity sum (default is true).

  • border_type – pixel extrapolation method, see BorderTypes. kBorderWrap is not supported.

Throws:

excepts::InvalidArgument – if image is empty.

void visionflow::img::median_blur(Image &image, int ksize, bool high_pass = false, double alpha = 1, double beta = 0)#

Blurs an image using the median filter.

Note

The median filter uses kBorderReplicate internally to cope with border pixels, see BorderTypes

Parameters:

  • image – input 1-, 3-, or 4-channel image; when ksize <= 9, the image depth should be kDepthU8, kDepthU16, or kDepthF32, for larger aperture sizes, it can only be kDepthU8.

  • ksize – aperture linear size; it must be odd and greater than 1. The maximum ksize is 255.

  • high_pass – flag indicating whether to perform high-pass filtering (subtracting the low-pass filtered image from the original image).

  • alpha – gain factor to adjust the contrast of the filtered image (only applicable when high_pass is true).

  • beta – bias term to adjust the brightness of the filtered image (only applicable when high_pass is true).

Throws:

excepts::InvalidArgument – if image depth or channel is error, or ksize out of range.

void visionflow::img::emphasize(Image &image, const geometry::Size2i &ksize, float factor)#

The operator emphasizes high frequency areas of the image. (edges and corners). The resulting images appears sharper.

Parameters:

  • image – Image to be enhanced.

  • ksize – Size of low pass filter. The value is an odd number between 3 and 201.

  • factor – Intensity of contrast emphasis.The range is between 0.0 and 20.0.

Throws:

excepts::InvalidArgument – if image depth is error, or filter_size/factor out of range.

void visionflow::img::sobel(Image &image, int dx, int dy, int ksize = 3, double scale = 1, double delta = 0, BorderTypes border_type = kBorderDefault)#

Calculates the first, second, third, or mixed image derivatives using an extended sobel operator.

Parameters:

  • image – input image.

  • dx – order of the derivative x.

  • dy – order of the derivative y.

  • ksize – size of the extended sobel kernel; it must be 1, 3, 5, or 7.

  • scale – optional scale factor for the computed derivative values; by default, no scaling is applied.

  • delta – optional delta value that is added to the results prior to storing them in result.

  • border_type – pixel extrapolation method, see BorderTypes. kBorderWrap is not supported.

Throws:

excepts::InvalidArgument – if image is empty, or ksize out of range.

void visionflow::img::gamma_transform(Image &image, double gamma, double alpha = 1, double beta = 0)#

Transform the contrast of image, the function use the formula as follow:

\[\texttt{dst} = 255 * alpha(((\texttt{src}+beta)/255)^{gamma})\]

Parameters:

  • image – Source image in kDepthU8, one or three channel.

  • gamma – Transformation coefficient, it is greater than 0. It gets higher output value within (0,1), lower output value within (1,+∞) and linear mapping when equal to 1.

  • alpha – Slope, it is greater than 0, and result image will get the higher luminance with its increasing.

  • beta – Offset, it is a offset in transforming contrast of image.

void visionflow::img::filter2d(Image &image, int ddepth, const std::vector<std::vector<float>> &kernel, const geometry::Point2f &anchor = geometry::Point2f(-1, -1), double delta = 0, BorderTypes border_type = img::kBorderDefault)#

Convolves an image with the kernel.

Parameters:

  • image – [inout] input image.

  • ddepth – desired depth of the destination image

  • kernel – convolution kernel (or rather a correlation kernel), a single-channel floating point matrix; if you want to apply different kernels to different channels, split the image into separate color planes using split and process them individually.

  • anchor – anchor of the kernel that indicates the relative position of a filtered point within the kernel; the anchor should lie within the kernel; default value (-1,-1) means that the anchor is at the kernel center.

  • delta – optional value added to the filtered pixels before storing them in dst.

  • border_type – pixel extrapolation method, see BorderTypes. kBorderWrap is not supported.

Throws:

excepts::InvalidArgument – if image or kernel is empty.

void visionflow::img::morphology(Image &image, MorphTypes op, MorphShapes shape, const geometry::Size2i &ksize, int iterations = 1, BorderTypes border_type = kBorderConstant)#

Performs advanced morphological transformations.

Note

The number of iterations is the number of times erosion or dilatation operation will be applied. For instance, an opening operation (kMorphOpen) with two iterations is equivalent to apply successively: erode -> erode -> dilate -> dilate (and not erode -> dilate -> erode -> dilate). In case of multi-channel images, each channel is processed independently.

Parameters:

  • image – Source image. The number of channels can be arbitrary. The depth should be one of kDepthU8, kDepthU16, kDepthF32.

  • op – Type of a morphological operation, see MorphTypes.

  • shape – Element shape that could be one of MorphShapes.

  • ksize – Size of the structuring element.

  • iterations – Number of times erosion and dilation are applied.

  • border_type – Pixel extrapolation method, see BorderTypes. kBorderWrap is not supported.

Throws:

excepts::InvalidArgument – if image is empty or op/shape is not defined.

void visionflow::img::histogram_equalization(Image &image, const Image &mask = Image())#

histogram equalization.

Parameters:

  • image – Source 8-bit single channel image.

  • mask – optional mask. If the visual size of mask is not empty, it must have one image in it (all image use the same mask), or its’ visual size should equal to image (each image use the corresponding mask). Each mask must be an 8-bit array of the same size as images. The non-zero mask elements mark the array elements counted in the histogram.

Throws:

excepts::InvalidArgument – if image type is error or mask is not match.

Image visionflow::img::lut(const Image &image, const std::vector<unsigned char> &lut)#

Performs a look-up table transform of an array.

Parameters:

  • image – input array of 8-bit elements.

  • lut – look-up table of 256 elements; in case of multi-channel input array, the same table is used for all channels.

Throws:

excepts::InvalidArgument – if image is not a 8-bit Image or number of elements in lut is not 256.

Returns:

Image output array of the same size, depth and channels as src.

void visionflow::img::flip(Image &image, FlipFlags flip_code)#

Flips an Image around vertical, horizontal, both axes or diagonal.

Note

For now, kFlip135 only supports Mat with elem_size <= 4.

Parameters:

  • image – Image to flip.

  • flip_code – a flag to specify how to flip the array; kVertical means flipping around the x-axis and kHorizontal means flipping around y-axis. kBoth means flipping around both axes. kFlip45 and kFlip135 means flipping around 45 or 135 degree diagonal.

Throws:

excepts::InvalidArgument – if image is empty or flip_code is not defined.

void visionflow::img::warp_circle_spread(Image &image, const geometry::Point2f &center, double r_start, double r_end, const geometry::Radian &start_angle, const geometry::Radian &span_angle, const geometry::Size2i &dsize, InterMethod inter_method = kInterLinear, BorderTypes border_type = kBorderConstant)#

Wrap circle spread(cart to polar)

Parameters:

  • image – Image wantted to be warpped.

  • center – Center of ploar origin.

  • r_start – Start radius of annulus, should be none negative.

  • r_end – End radius of annulus, should be none negative.

  • start_angle – From where begin to warp.

  • span_angle – Total angle span of the annulus, can be positive or negative.

  • dsize – Size of result image, dsize will be set adaptively with given annulus when given dsize is empty.

  • inter_method – Interpolation method, see InterMethod.

  • border_type – Pixel extrapolation method, see BorderTypes.

Throws:

excepts::InvalidArgument – if image is empty or r_start is not smaller than r_end.

void visionflow::img::resize(Image &image, const geometry::Size2i &dst_size, double x_scale = 0.0, double y_scale = 0.0, InterMethod inter_method = kInterLinear)#

Resize image.

Parameters:

  • image – Input image。

  • dst_size – Size of output image.

  • x_scale – Scale factor in x direction

  • y_scale – Scale factor in y direction

  • inter_method – Interpolation method, see InterMethod.