ImageTopoDec 1.0.2

Python wrapper for the Barcode library.

Library Description

The core of this Python library is the C++ one. It consists of .cpp and .h files. It is built using the premake build system. It is recommended to use the make_win.bat script, which provides an example of the build process.

To facilitate usage, a Python wrapper is implemented, enabling the creation and use of the ImageTopoDec library.

Connecting the Python Library

Compatible systems required for library integration:

• Operating Systems: Windows 10, Linux (compatible with manylinux_2_28), macOS (ARM architecture).
• Python: Version 3.13 x86_64.
• C++ Support: Required on Windows only (link for installing the redistributable package).
• Package Manager: pip.

The library is installed using pip:

For Linux:

python3 -m pip install ImageTopoDec

For Windows:

py -m pip install ImageTopoDec

For macOS, it is recommended to use a virtual environment:

python3 -m venv .venv
source ./.venv/bin/activate
pip install ImageTopoDec

C++ Library Interface

The library uses the bc namespace, where all classes are defined. These classes can be categorized into interface classes (used by the user) and internal classes. Tables 1-3 provide descriptions of the interface classes and enumerations.

Table 1. C++ Library Interface Description

Class	Description
BarcodeCreator	Constructs barcodes. Can act as a factory or directly invoked using a static method to create a barcode.
DatagridProvider	Wrapper interface for transferring images for barcode creation.
BarImg	Example implementation of DatagridProvider, storing data in an internal array.
BarNdarray	Wrapper class for DatagridProvider, allowing processing of NumPy arrays (data is taken by reference).
barstruct	Structure for setting barcode creation configurations.
BarConstructor	Stores configuration settings. Used to create multiple barcodes from a single image.
bc::Baritem	Stores the barcode and its metadata after creation.
bc::Barcontainer	Stores a collection of barcodes created from a single image using multiple configurations.
barline	Structure storing information about a barcode component (line).
Barscalar	Class for storing the value (usually brightness) of a barcode.
BarRect	Class for storing the coordinates of a rectangular area.
barvalue	Class storing the value and position of a matrix element.
point	Structure storing the X and Y positions.

Table 2. Enumerations

Translated Text

Enumeration	Enumeration Element	Value
CompireFunction	CommonToLen	Option for comparison by length.
	CommonToSum	Option for comparison of barcodes by the sum of lengths.
ComponentType	Component	Barcode construction type - components.
	Hole	Barcode construction type - holes.
ProcType	f0t255	Pixel traversal strategy – from minimum brightness to maximum. Suitable for detecting light objects.
	f255t0	Pixel traversal strategy – from maximum brightness to minimum. Suitable for detecting dark objects.
	Radius	Pixel traversal strategy in pairs ordered by increasing brightness difference in these pairs.
ColorType	gray	Convert (if necessary) the input image to grayscale.
	native	Process the input image as is.
	rgb	Convert (if necessary) the input image to RGB.
ReturnType	barcode2d	Returns lines constructed based on component lifetimes.
	barcode3d	Returns lines constructed based on component lifetimes and adds an array for each component.
AttachMode	firstEatSecond	The parent component is the one that appeared earlier during attachment.
	secondEatFirst	The parent component is the one that appeared later during attachment.
	createNew	A new "proxy" component is created during attachment, becoming the parent.
	dontTouch	Do not attach components.
	morePointsEatLow	The parent component is the one that consumed more pixels during attachment.
BarType	BYTE8_1	The scalar stores the value as 1 byte (for grayscale).
	BYTE8_3	The scalar stores the value as 3 bytes (for RGB).
	BYTE8_4	The scalar stores the value as 4 bytes (for RGBA).
	FLOAT32_1	The scalar stores the value as 4 bytes (for floating-point numbers).
	INT32_1	The scalar stores the value as 4 bytes (for integers).

---

Table 3. Description of Class Elements from Table 1

Class	Method/Field Interface	Description
BarcodeCreator	bc::Barcontainer* createBarcode(const bc::DatagridProvider* img, const BarConstructor& structure);	Creates multiple barcodes from a single image img using the settings array in structure.
	bc::Baritem* createBarcode(const bc::DatagridProvider* img, const barstruct& structure);	Creates a single barcode from an image img using an instance of structure settings.
	static std::unique_ptr<bc::Baritem> create(const bc::DatagridProvider& img, const barstruct& structure = {});	Static method for creating a single barcode from an image img using an instance of structure settings.
DatagridProvider	virtual int wid() const = 0;	Returns the width of the image.
	virtual int hei() const = 0;	Returns the height of the image.
	virtual int channels() const = 0;	Returns the number of channels in a pixel.
	virtual void maxAndMin(Barscalar& min, Barscalar& max) const = 0;	Finds the extremes of brightness.
	virtual size_t typeSize() const = 0;	Returns the size of one pixel in bytes.
	virtual Barscalar get(int x, int y) const = 0;	Returns the pixel at the specified coordinates.
barstruct	float maxLen = 999999;	The maximum allowable lifetime of a component during construction.
	float maxRadius = 999999;	The maximum allowable brightness difference for a pixel to join a component.
	float minAttachRadius = 0;	The minimum allowable brightness difference for components to merge.
	ReturnType returnType = ReturnType::barcode2d;	The type of construction.
	bool createGraph = false;	Whether to create a tree-like graph of relationships.
	bool createBinaryMasks = false;	Whether to create matrices during construction.
	bool killOnMaxLen = false;	Whether a component should disappear upon reaching the maximum allowable size.
BarConstructor	void addStructure(ProcType pt, ColorType colT, ComponentType comT);	Adds a structure for barcode construction.
Baritem	Barscalar Sum() const	Returns the sum of all line lengths.
	void relength()	Normalizes the appearance time of all components relative to the first one.
	Barscalar maxLen() const;	Returns the longest line in the barcode.
	Baritem* clone()	Returns a full copy of the current item.
	BarType getType()	Returns the data type used for storing barcode values.
	std::array<int, 256> getBettyNumbers() const;	Calculates the Betti numbers from the barcode.
	void removeByThreshold(Barscalar const porog);	Removes all lines shorter than the specified threshold.
	void preprocessBarcode(Barscalar const& porog, bool normalize);	Combines removeByThreshold and relength methods.
	float compareFull(const Barbase* bc, bc::CompareStrategy strat) const;	Compares barcode lines linearly.
	float compareBestRes(Baritem const* bc, bc::CompareStrategy strat) const;	Compares barcode lines, finding the best match for each line.
	float compareOccurrence(Baritem const* bc, bc::CompareStrategy strat) const;	Finds the best barcode occurrence and returns the percentage of matches.
	void normalize();	Normalizes the barcode based on its start time.
	template<class TSTR, typename TO_STR> void getJsonObject(TSTR &out, bool exportGraph = false, bool export3dbar = false, bool expotrBinaryMask = false) const	Saves the barcode as a JSON object.
	template<class TSTR, typename TO_STR> void getJsonLinesArray(TSTR &out, bool exportGraph = false, bool export3dbar = false, bool expotrBinaryMask = false) const	Saves the barcode as a JSON array.
	bc::BarRoot* getRootNode()	Returns the root element in the graph.
	getBarcodeLinesCount	Returns the number of components (lines) in the barcode.
	sortByLen	Sorts barcode lines by component length.
	sortBySize	Sorts barcode lines by the number of points in them.
	sortByStart	Sorts barcode lines by their appearance time.
Barcontainer	Barscalar Sum() const	Returns the sum of all line lengths.
	void relength()	Normalizes the appearance time of all components relative to the first one.
	Barscalar maxLen() const;	Returns the longest line in the barcode.
Baritem* clone()	Returns a full copy of the current item.
	size_t count();	Returns the number of barcodes in the container.
	Baritem *getItem(size_t i);	Returns the barcode by its index.
	Baritem *extractItem(size_t index)	Extracts the barcode by its index.
	void removeLast()	Removes the last barcode from the container.
	Baritem* lastItem();	Returns the last barcode in the container.
	void removeByThreshold(Barscalar const porog);	Removes all components in each barcode that are smaller than the specified threshold.
	void preprocessBarcode(Barscalar const& porog, bool normalize);	Preprocesses each barcode in the collection.
	float compareFull(const Barbase* bc, bc::CompareStrategy strat) const;	Compares each barcode in the collection and returns the best match.
	float compareBest (Baritem const* bc, bc::CompareStrategy strat) const;	Compares each barcode in the collection and returns the best match.
	size_t getBarcodesCount() const	Returns the number of barcodes in the container.
	void clear()	Clears the container.
barline	Barscalar getStart() const	Returns the start time of the component.
	Barscalar getLength() const	Returns the lifespan of the component.
	Barscalar getEnd() const	Returns the disappearance time of the component.
	const barvector& getMatrix() const	Returns non-zero points of the matrix in dictionary format {Point: matrix value at the point, ...}.
	barvector& getMatrix()	Returns non-zero points of the matrix in list format {Matrvalue, ...}.
	size_t getMatrixCount() const	Returns the count of non-zero points in the matrix.
	size_t getPointsSize() const	Returns the number of points in the component.
	BarRect getBarRect() const	Returns the bounding rectangle described by coordinates.
	barline* clone(bool cloneMatrix = true) const	Copies the current object.
	float lenFloat() const	Returns the line length as a float.
	int getDeath()	Returns the depth of the current component in the decomposition graph.
	getParrent	Returns the parent of the current component (the component that absorbed this one).
	bc::barline* getChild(uint id) const	Returns the child component.
	size_t getChildrenCount() const	Returns the number of components absorbed by the current one.
	template<class TSTR, typename TO_STRING> void getJsonObject(TSTR& outObj, ExportGraphType exportGraph = ExportGraphType::noExport, bool export3dbar = false, bool expotrBinaryMask = false) const	Saves the current component as a JSON object.
Barscalar	BarType type	Data type in which the scalar value is stored.
	unsigned char getByte8() const	Returns the scalar as an 8-byte value.
	int getInt() const	Returns the scalar as a 32-bit integer.
	float getFloat() const	Returns the scalar as a 32-bit floating-point value.
	unsigned char getRGB(int id) const	Retrieves one of the RGB color channels.
	float getAvgFloat() const	Returns the scalar value converted to a 32-bit integer.
	uchar getAvgUchar() const	Returns the scalar value converted to an 8-byte unsigned integer.
	float val_distance(const Barscalar& R) const	Returns the Euclidean distance between the current and the provided scalar.
	Barscalar absDiff(const Barscalar& R) const	Computes the absolute difference between the current and the provided scalar.
BarRect	int x	Position of the rectangle relative to the left edge.
	int y	Position of the rectangle relative to the top edge.
	int width	Width of the rectangle.
	int height	Height of the rectangle.
	float coof()	Returns the aspect ratio of the rectangle.
	int right()	Returns the position of the rectangle's right edge.
	int botton()	Returns the position of the rectangle's bottom edge.
	int area()	Returns the area of the rectangle.
	bool isItemInside(BarRect anItem)	Determines whether the given rectangle is entirely within the current rectangle.
barvalue	unsigned short x	Position of the matrix element relative to the left edge.
	unsigned short y	Position of the matrix element relative to the top edge.
	Barscalar value	Matrix value at the given position.
point	int x	Position relative to the left edge.
	int y	Position relative to the top edge.

Python Library

The Python library is a wrapper for the C++ library. All classes listed in Table 1 are translated to Python with the same method and field names. If a method returns a vector or array, the Python wrapper returns a set.

The library also includes its own functions and a class, as shown in Tables 4 and 5.

To use the library, import it:

import ImageTopoDec as bcc

Barcodes are created using the create_barcode method:

barc = bcc.create_barcode(img, cont)

Table 4. Python Library Custom Functions

Function Interface	Description
create_barcode(img, struct: barstruct) -> Barcode	Creates a barcode object from an image img with options struct.
append_line_to_matrix(barline: Barline, matrix: np.array)	Appends a matrix from the barline component to the output matrix matrix.
combine_components_into_matrix(barlines: list[Barline] | Barline, shape: tuple, type = np.uint8)	Creates a matrix from components or a single component.

Table 5. Python Library Custom Classes

Class Name	Method/Field	Description
Barcode	__init__(self, img: np.ndarray, build_options: barstruct)	Constructor that builds and stores metadata.
	item	Field storing the original barcode wrapped in Baritem.
	get_largest_component()	Returns the largest component (by matrix size).
	get_first_component()	Returns the first component in the barcode.
	restore()	Constructs an image from the barcode.

---

Visualization Module

The library includes a barplot module for visualizing barcodes using Matplotlib. To use it:

import ImageTopoDec.barplot as bcp

The module provides one function:

plot_barcode_lines(lines: set[bc.Barline] | bc.Baritem | bc.Barline, name, show=False, save=False)

This function can display or save the plot.

---

Example Usage

import ImageTopoDec as bc
import ImageTopoDec.barcode as bcc
import cv2
import matplotlib.pyplot as plt

# Load image
img = cv2.imread('/Users/sam/Edu/bar/12/1.png', cv2.IMREAD_GRAYSCALE)
plt.imshow(img, cmap='gray')

Figure 1. Source image

# Create barcode and visualize the largest component
cmp = barc.get_largest_component()
img = bcc.combine_components_into_matrix(cmp, img.shape, img.dtype)

plt.imshow(img, cmap='gray')

cmp = barc.get_largest_component()
img = bcc.combine_components_into_matrix(cmp, img.shape, img.dtype)
plt.imshow(img, cmap='gray')

Figure 2. Visualization of the largest component

binmap = barc.segmentation(False)

plt.imshow(binmap, cmap='gray')

Figure 3. Segmentation by each component (parameter set to False in the segmentation method) with overlap.

binmap = barc.segmentation(True)
plt.imshow(binmap, cmap='gray')

Figure 4. Binary segmentation (parameter set to True in the segmentation method).

filterd = barc.filter(100)
plt.imshow(filterd, cmap='gray')

Figure 5. Reconstructed image without components whose length is less than 100.

import ImageTopoDec.barplot as bcp
bcp.plot_barcode_lines(barc, 'test', True, False)

Figure 6. Barcode visualization: an image named 'test' will be created, which will be visualized (parameter True) and not saved to disk (parameter False).