Other Tools
The Other Tools module brings together practical utilities for dataset normalization checks and flexible annotation format conversion, designed to solve data redundancy and format compatibility problems in the later stages of a project.
1. Filename Sanitizer¶
Description: When industrial vision software is deployed, non-standard file names (such as those containing special characters, spaces, or illegal symbols) often cause path resolution to crash or model loading to fail.
- Detection scope:
- Automatically scans all image and JSON file names in the dataset.
- Identifies hidden illegal symbols, including the common English hyphen
-, spaces, or Chinese characters.
- Processing logic:
- Automatic renaming: Migrates non-standard file names into a custom output directory with a single click.
Developer Notes
A file name that looks perfectly fine on Windows may still cause crashes on Linux or in certain embedded vision operators. It is recommended to run a symbol check once before model training.
2. Polygon to BBox¶
Description: Converts fine-grained "polygon" annotations into standard "bounding box" annotations.
- Conversion logic:
- The system automatically extracts the maximum / minimum coordinates of all vertices of the polygon.
- It automatically computes the smallest horizontal rectangle that fully encloses the polygon.
- Use cases:
- Algorithm downgrade: When a project switches from a segmentation algorithm (Segmentation) to a detection algorithm (Detection), no re-annotation is required.
- Format unification: Quickly unify heterogeneous data coming from different annotation teams or different versions of the software.
Conversion Characteristics
The conversion is non-destructive. The generated bounding boxes strictly follow YOLO or standard JSON coordinate specifications, making them ready for training.
3. LabelMe to YOLO¶
Description:
Converts JSON files annotated in LabelMe into the .txt annotation files required by the YOLO family for training, and automatically generates the dataset configuration file data.yaml.
- Supported annotation types:
- rectangle: object detection (
class_id x_center y_center width height, all normalized). - polygon: instance segmentation (
class_id x1 y1 x2 y2 ... xn yn, all normalized). - obb: rotated object detection (
class_id x1 y1 x2 y2 x3 y3 x4 y4, all normalized).
- rectangle: object detection (
- Automatic label mapping:
- The first pass automatically collects all unique
labelvalues and generatesclass_idin alphabetical order. - The second pass writes them uniformly into the
.txtfiles, avoiding the tedious step of manually matching a class table.
- The first pass automatically collects all unique
- Accompanying outputs:
- Automatically copies the corresponding image files (
jpg/png/jpeg/bmp/webp, with common suffix case variations automatically tried). - Generates
data.yamlin the output directory, ready to be used directly with the YOLO training framework.
- Automatically copies the corresponding image files (
Recommendation
It is recommended to clean the file names first with "Filename Sanitizer" from the "Other Tools" module, which reduces the cases of a misaligned imagePath field and failed image matching.
4. Polygon Merge¶
Description: For the common case in industrial scenes where "the same defect is cut into multiple small segments", it intelligently merges the polygons by class using gap bridging, while keeping truly non-intersecting independent defects as separate individuals.
- Core strategy:
- Micro dilation bridging: Uses
buffer(bridge_distance)to glue adjacent polygons that are very close together, then fuses them withunary_union. - Split restoration: If the fusion result is a
MultiPolygon, it is restored one by one into independent polygons (and then contracted back to the original size withbuffer(-bridge_distance)). - Topological simplification: Uses
simplify(simplify_tolerance, preserve_topology=True)to remove useless dead points, preventing the model from learning "burrs" during training.
- Micro dilation bridging: Uses
- Adjustable parameters:
bridge_distance: The pixel distance of the bridging gap. Polygons closer than this value are fused; those farther apart remain completely independent.simplify_tolerance: The tolerance for topological simplification; the larger the value, the fewer the vertices (the "cleaner" the annotation).
Recommendation
The default bridge_distance of 2.0 works well for industrial images around 1080p. If the resolution differs greatly (for example, with a 4K camera), it is recommended to scale it up proportionally, to avoid "accidentally merging" independent defects.
5. Circular Image Flatten & Crop¶
Description: For top-view images of annular workpieces (metal bearings / flanges / end faces, glass bottle mouths, plastic hubs, rubber seals, printed label rings, food packaging rings, and any other sample that can be photographed as a top-view ring), it automatically detects the inner and outer circles, unwraps the annular region in polar coordinates into a rectangle, and then applies sliding-window cropping according to the specified width and overlap ratio. This makes it convenient to train with conventional object detection / segmentation models (YOLO, U-Net, RT-DETR, etc. all take rectangular images directly).
- Algorithm highlights (
utils/cut.py, derived from the HALCON industrial vision workflow):- Inner / outer circle detection (outer first, then inner):
- Threshold
[0, 180]to extract dark connected components; - Filter by
Min Area = 70and take the largest connected component as the outer disk; - Apply
fill_upto the outer disk to obtain a solid outer circle; - Take the one-way difference of "the fill result AND NOT the outer disk" (
A AND NOT B) to obtain the inner hole annulus; - Then take the largest connected component of the inner hole annulus and fit it to obtain the inner circle center and radius;
- Finally, fit the outer disk separately to obtain the outer circle center and radius.
- Threshold
- Polar unwrapping: Reverse-samples the original image according to the formula
r = outer - (row / H) * (outer - inner) - 3, with the top = outer ring and the bottom = inner ring, which matches visual intuition; grayscale and color images are both handled automatically (cv2.remapper channel, followed bynp.stack). - Sliding-window cropping: Defaults to
CropWidth = 600andOverlap = 150; adjacent windows guarantee no missed detection through the overlap ratio.
- Inner / outer circle detection (outer first, then inner):
- Adjustable parameters (already filled in with the default values in the interface):
CropWidth: The horizontal pixel width of each sub-image.Overlap: The number of overlapping pixels between adjacent sub-images, which determines the window step =CropWidth - Overlap.
- Robustness:
- Compatible with paths containing Chinese characters and special characters such as
&and()(images are read withnp.fromfile+cv2.imdecodeand written withcv2.imencode+tofile, working around the OpenCV decoding bug on non-ASCII paths). - Outputs BMP (
cv2.imencodeis the most stable under non-TIFF codecs), with_part_NNNautomatically appended to the file names.
- Compatible with paths containing Chinese characters and special characters such as
Recommendation
Process only one image at a time. If the hole of the ring is close to the outer circle (a thin ring), it is recommended to first confirm that the distance between the inner and outer circles is ≥ 20 pixels; otherwise the height after the polar unwrapping will be extremely small, and the cropping result may end up empty.