How to Fix Outdated Reconstruction Pipeline Configuration

Goal: Repair old pipeline.toml files so that reconstruction pipelines run without errors (e.g., "missing Undistorted task") and adopt the current set of parameters.

When to use this guide

• You have one or more pipeline.toml files generated by older versions of PlantDB/FSDB.
• The files contain deprecated fields (Undistorted, old Colmap settings, etc.).
• You want a reliable, repeat‑able way to update them without manually editing each file.

Overview of the fix process

1. Parse each TOML file into a Python dictionary.
2. Update the dictionary:
3. Rename section [Undistorted] to [Undistort].
4. Refresh the Colmap section with modern defaults (MAD‑based QC, new thresholds, etc.).
5. Convert old Masks definitions to the new min_threshold / max_threshold format and set sensible defaults.
6. Replace the old Voxels configuration with the current averaging method.
7. Write the updated dictionary back to pipeline.toml.
8. Create a timestamped backup (unless you disable this with --no‑backup).

Step‑by‑step instructions

1. Choose the appropriate mode

The CLI can work on three kinds of input:

Mode	What you pass as PATH	What happens
Single file	Path to a single pipeline.toml	That file is fixed.
Directory	Path to a folder containing many *.toml files (excluding scan*.toml)	Every matching file is fixed.
FSDB database	Path to an FSDB root directory (contains the marker file)	The script connects to the DB, selects scans, and fixes each scan’s pipeline.toml.

2. Run the command

First, open a terminal and navigate to the directory containing fix_pipeline_toml.py.

cd ~/Projects/plant-3d-vision/scripts/

Then apply one of the following solutions.

a. Fix a single file (default creates a backup)

python fix_pipeline_toml.py /data/FSDB/pipeline.toml

b. Fix every file in a directory without backups

python fix_pipeline_toml.py /data/FSDB/configs --no-backup

c. Fix scans in an FSDB database, limiting to a date pattern

python fix_pipeline_toml.py /data/FSDB \
    --scan "2023-03-*" \
    --user admin --password secret

d. Test against a database that does not require authentication

python fix_pipeline_toml.py /data/FSDB --no-auth

3. Verify the results

• The script prints a line for each file it processes, e.g. Fixing toml file /path/to/pipeline.toml....
• After it finishes, look for a new file named pipeline_YYYY-MM-DD_HH‑MM‑SS.toml.bak next to each original file (unless you used --no-backup).
• Open a corrected pipeline.toml and confirm that:
• Section [Undistorted] is now [Undistort].
• Colmap includes the new fields (colmap_exe, qc_check, mad_factor, etc.).
• Masks has min_threshold, max_threshold, colorspace, dilation, and method.
• Voxels contains query, method, voxel_size, and optionally bounding_box.

4. (Optional) Roll back

If anything looks wrong, restore the original file from its backup:

mv pipeline_2026-07-16_14-30-00.toml.bak pipeline.toml

Tips and common pitfalls

Issue	Why it happens	Fix
No files processed	Path points to a directory that lacks pipeline.toml files or the DB marker file.	Double‑check the path and file extensions.
Authentication error	--user/--password missing or wrong, and --no-auth not set.	Provide correct credentials or add --no-auth for test databases.
Backup not created	You used --no-backup.	Omit the flag if you want safety copies.
Unexpected TOML decode error	The file is malformed.	Inspect the file manually; the script will stop on that file and continue with others.

Next steps

After fixing the configuration, run your reconstruction pipeline as usual. If new errors appear, revisit the reference guide or open an issue in the project repository.