Skip to content

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).
  • Automatic label mapping:
    • The first pass automatically collects all unique label values and generates class_id in alphabetical order.
    • The second pass writes them uniformly into the .txt files, avoiding the tedious step of manually matching a class table.
  • Accompanying outputs:
    • Automatically copies the corresponding image files (jpg/png/jpeg/bmp/webp, with common suffix case variations automatically tried).
    • Generates data.yaml in the output directory, ready to be used directly with the YOLO training framework.

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 with unary_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 with buffer(-bridge_distance)).
    • Topological simplification: Uses simplify(simplify_tolerance, preserve_topology=True) to remove useless dead points, preventing the model from learning "burrs" during training.
  • 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):
      1. Threshold [0, 180] to extract dark connected components;
      2. Filter by Min Area = 70 and take the largest connected component as the outer disk;
      3. Apply fill_up to the outer disk to obtain a solid outer circle;
      4. Take the one-way difference of "the fill result AND NOT the outer disk" (A AND NOT B) to obtain the inner hole annulus;
      5. Then take the largest connected component of the inner hole annulus and fit it to obtain the inner circle center and radius;
      6. Finally, fit the outer disk separately to obtain the outer circle center and radius.
    • 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.remap per channel, followed by np.stack).
    • Sliding-window cropping: Defaults to CropWidth = 600 and Overlap = 150; adjacent windows guarantee no missed detection through the overlap ratio.
  • 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 with np.fromfile + cv2.imdecode and written with cv2.imencode + tofile, working around the OpenCV decoding bug on non-ASCII paths).
    • Outputs BMP (cv2.imencode is the most stable under non-TIFF codecs), with _part_NNN automatically appended to the file names.

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.