Image type and image algorithm interfaces#

Image type defination#

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 visualizable images like png or jpeg, tiff, etc. And you need to make sure that all the visualizable 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 – Visualizable 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 visualizable images have the same height, width, channels and depth.

Parameters:

visual_size – Visualizable 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 shoud 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, shoud be greater than 0 and less than or equal width - x.
h – Height of roi box, shoud 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 isnot 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 submatrix.
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 visualizable images at [visual_index]. Defalt 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 visualizable 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)#

Convert channels of each visualizable 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.

Throws:

excepts::DataNotFound – if Image is empty.
excepts::InvalidArgument – if source-channels isnot equal to 1, 3, or 4 or target-channels isnot equal to 1 or 3.

void convert_depth(Depth depth)#

Convert depth of each visualizable 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_szie will throw an excepts::InvalidArgument.

Parameters:: visual_index – Index of visualizable images at [visual_index]. Defalt -1 means clone all the visualizable 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 visualizable 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 visualizable images at [visual_index]. Defalt 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD visualizable 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 visualizable 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 isnot in the specified format.
excepts::DataNotFound – if a visualizable image in Image is empty.
excepts::InvalidArgument – if a visualizable image is diff in size form the first visualizable 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 visualizable 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 visualizable 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 visualizable image is diff in size form the first visualizable 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 visualizable 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 isnot equal to 1, 3 or 4 or the storage format is incorrect or a visualizable image is diff in size form the first visualizable 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 doesenot support multiple visualizable 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 dosenot support multiple visualizable images, otherwise an excepts::InvalidArgument will be thrown.

Throws:: excepts::InvalidArgument – if Image visual_size isnot 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 visualizable 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 isnot equal to 1, 3 or 4 or a visualizable image is diff in size form the first visualizable 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 visualizable 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 visualizable image in Image is empty.
excepts::InvalidArgument – if a visualizable image is diff in size form the first visualizable image.

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

Show visualizable image at [visual_index].

Show this image in window named as winname and wait wait_time milli-seconds. If depth of visualizable 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.
winname – Window name.
visual_index – Index of visualizable images at [visual_index]. Defalt 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 visualizable image at [visual_index].

If visual_index out of visual_size will throw an excepts::InvalidArgument. If the visualizable image data isnot continuous will throw an excepts::LogicError.

Parameters:

visual_index – Index of visualizable images at [visual_index]. Defalt 0 means the first image.

Throws:

excepts::InvalidArgument – if visual_index out of visual_size.
excepts::LogicError – if the visualizable image isnot continuous.

Returns:

NO_DISCARD readonly data pointer.

void *data(size_t visual_index = 0)#

Mutable data pointer of visualizable image at [visual_index].

If visual_index out of visual_size will throw an excepts::InvalidArgument. If the visualizable image data isnot continuous will throw an excepts::LogicError.

Parameters:

visual_index – Index of visualizable images at [visual_index]. Defalt 0 means the first image.

Throws:

excepts::InvalidArgument – if visual_index out of visual_size.
excepts::LogicError – if the visualizable image isnot continuous.

Returns:

NO_DISCARD mutable data pointer.

size_t data_size(size_t visual_index = 0) const#

Data size of visualizable image at [visual_index].

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

Parameters:: visual_index – Index of visualizable images at [visual_index]. Defalt 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 visualizable 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 visualizable images at [visual_index]. Defalt 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 visualizable image at [visual_index].

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

uint32_t width(size_t visual_index = 0) const#

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

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

uint32_t channels(size_t visual_index = 0) const#

Image channels of visualizable image at [visual_index].

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

Parameters:: visual_index – Index of visualizable images at [visual_index]. Defalt 0 means the first image.
Throws:: excepts::InvalidArgument – if visual_index out of visual_size.
Returns:: NO_DISCARD image channels of visualizable 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 visualizable images, this function wll return total channels of all the visualizable images.

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

Depth depth(size_t visual_index = 0) const#

Image depth of visualizable image at [visual_index].

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

bool empty() const#

Empty if Image is empty.

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

size_t visual_size() const#

Visual size.

Returns:: NO_DISCARD visualizable image number in the Image.

bool is_multi_visual() const#

Is multi visual.

Returns:: NO_DISCARD true if this Image have multiple visualizable 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 visualizable 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 isnot in the specified format.
excepts::DataNotFound – if a visualizable image in Image is empty.
excepts::InvalidArgument – if a visualizable image is diff in size form the first visualizable 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 – Visualizable 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 aidi::Image = aidi::img::Image #: export the aidi::img::Image type into aidi 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 aidi::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 aidi::Image::clone() explicitly like below:

auto sub_image = std::make_shared<SubImage>(image.clone(),
aidi::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& aidi::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 aidi::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& aidi::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 aidi::Image will not be copied,

Parameters:: image – aidi::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 – aidi::geometry::Matrix3f
Returns:: SubImage& reference to this object.

SubImage clone() const#

Deep copy.

Returns:: NO_DISCARD cloned sub-image.

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

Image Algorithms#

enum LineType#

types of line

Values:

enumerator kFilled = -1#

enumerator kLine4 = 4#: 4-connected line

enumerator kLine8 = 8#: 8-connected line

enum ColorType#

ColorType Enumerate of color space.

Values:

enumerator kGray = 1#: Gray color space.

enumerator kBGR = 3#: BGR color space.

aidi::img::SubImage transform(const aidi::img::Image &image, const aidi::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<aidi::img::SubImage> transform(const aidi::img::Image &image, const std::vector<aidi::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<aidi::img::SubImage> the roi original image sub-image corresponding to each View.

float similar(const aidi::img::Image &src, const aidi::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(aidi::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 aidi::img::Image &image)#

Compute the mean of Image.

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

aidi::geometry::MultiPolygon2f find_polygons(const aidi::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:: aidi::geometry::MultiPolygon2f

void draw(aidi::img::Image &image, const aidi::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(aidi::img::SubImage &sub_image, const aidi::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.