ArUCo Marker Measurement System

File Structure

The images should be structured in the following directory format. Each subdirectory must have two or more images.

/path/to/root/folder
    |--> /sub_directory_1
        |--> repeat1.jpg
        |--> repeat2.jpg
    |--> /sub_directory_2
        |--> repeat1.jpg
        |--> repeat2.jpg
    |--> /sub_directory_3
        |--> repeat1.jpg
        |--> repeat2.jpg
        |--> repeat3.jpg
    ...

Basic Usage - Using Docker (recommended)

Downloading the Lastest Docker Image

Pull the docker file from the docker hub with the following command.

docker pull enigmaoffline/armms

Then run the container with the shell file provided, modify the variables to point the directories and files that you need to processing.

./docker_run.sh

Building from Source

In the project directory, run the following command to build the docker image.

docker build -t armms .

Then run the container with the shell file as above.

./docker_run.sh

OR

Basic Usage - Running Locally

1. Create a python environment using Conda

conda env create -f env/environment.yml

This command will create a python3.11 environment and install all the relevant dependencies.

Once activating the conda environment, use the following command to run the main.py file using the dummy data provided.

python main.py -j jobs/job_local.json

You can refer to the jobs/job_local.json file to learn more about the arguments available for the script. Alternatively, you can pass in the arguments directly to the main.py on execution as such.

python main.py -r data/data_small_groups -o out/

OR

Open the ipynb notebook and run each cell, the inference process is identical.

Flags

• DICT_TYPE: ArUCo marker dictionary
• MARKER_SIZE: Marker size (can be in any unit)
• VALID_MARKER_IDS: Detection will only match the IDs provided below, leave the list empty if you want possible markers to be detected, highly advised to be used if USE_ADV_THRESH is enabled
• ROOT_DIR: Root directory of the images, see below for file structure
• OUT_DIR: Output directory for the results, log file, and generated images, however, the output directory can't be inside the ROOT_DIR
• DETECTION_ONLY: Boolean flag for disabling comparison and calculations
• USE_ADV_THRESH: Boolean flag for enabling advanced thresholding. Sweeps for a multitude of thresholding settings, aids in detecting markers that are less visible
• COMPARISON_MODE: Comparison mode, "all" or "series"
• GEN_RESULTS: Boolean flag for generating result images
• GEN_OVERLAYS: Boolean flag for generating an overlaid result of all the result images of the subdirectory
• VERBOSE: Boolean flag for enabling command line output

Inference Script Process Breakdown

Initialisation Step

• Verifying that each subdirectory of the root has two or more images
• Create leaf directories in the output folder

Detection Step

• Go through each subdirectory and each image in the subdirectories
• Detect all markers present in the images
• Generate results images
• Saves the intermediate results (coordinates of detected markers) to JSON and CSV file in the output directory

Calculation and Comparison Step

• Recover edge length of each maker
• Calculate the distances of markers in the same group with the same ID
• Save result dictionary as JSON
• Convert dictionary to rows of data and save as CSV

Edge length recovery calculation demo video created with Manim.

demo.mp4

Image Overlays Generation Step

• Go through each subdirectory in the output folder and overlay images with equal alpha