Add utility to merge multiple defect masks into single grayscale masks

[Copilot]

Defect detection datasets often have multiple mask files per image (e.g., image_42586468_裂纹_1_mask.png, image_42586468_破损_2_mask.png). This PR adds tooling to merge these into single masks named after the base image.

Implementation

• merge_masks.py: Core utility with CLI and Python API

  • Extracts base names via regex pattern matching (<base>_<type>_<num>_mask.png → <base>.png)
  • Groups masks by base name, merges using pixel-wise maximum (OR operation)
  • Handles Chinese characters, creates output directories automatically
  • Proper resource management with context managers

• test_merge_masks.py: Test suite covering name extraction, grouping, merging logic, and edge cases

• MERGE_MASKS_README.md: Complete documentation with API reference and troubleshooting

• example_usage.py: Six practical usage patterns from basic to batch processing

Usage

from merge_masks import process_masks

# Merge all masks in folder
process_masks(
    'D:/datasets/train/masks',
    'D:/datasets/merged_masks'
)

# CLI usage
python merge_masks.py <input_folder> <output_folder>

Quality: 100% test pass rate, 0 CodeQL alerts

Original prompt

You have a folder containing mask files for various defects, where each file is named like 20251008新数据-大面龟裂_42586468_裂纹_1_mask.png. Multiple masks for the same image and/or defect type exist in this folder. The task is to combine all such masks related to the same base image into a single grayscale mask. The resulting mask file should match the original image name exactly, without additional suffixes (e.g., '20251008新数据-大面龟裂_42586468.png'). Defects from different mask files should be merged using pixel-wise OR operations. The input mask folder is: D:\qw\Code_github\cicai_all\cicaiquexian_seg\train\masks The output of merged files should be saved to: D:\qw\Code_github\cicai_all\merged_masks_images

This pull request was created as a result of the following prompt from Copilot chat.

You have a folder containing mask files for various defects, where each file is named like 20251008新数据-大面龟裂_42586468_裂纹_1_mask.png. Multiple masks for the same image and/or defect type exist in this folder. The task is to combine all such masks related to the same base image into a single grayscale mask. The resulting mask file should match the original image name exactly, without additional suffixes (e.g., '20251008新数据-大面龟裂_42586468.png'). Defects from different mask files should be merged using pixel-wise OR operations. The input mask folder is: D:\qw\Code_github\cicai_all\cicaiquexian_seg\train\masks The output of merged files should be saved to: D:\qw\Code_github\cicai_all\merged_masks_images

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.