CV3D UI

CV3D UI is the graphical workflow for CompoundVision3D (CV3D), a workflow for extracting compound-eye surface geometry and derived optical quantities from three-dimensional image data and surface meshes.

The UI coordinates Fiji/ImageJ, Blender, and R so that the individual processing steps can be run, inspected, and documented from one project-based interface. Numerical analyses are performed by the companion CV3D R package.

• UI repository: https://github.com/Pete-s-Lab/CV3D-UI
• R package: https://github.com/Pete-s-Lab/CV3D

Workflow

The current workflow comprises:

1. image-volume preprocessing and ROI extraction in Fiji/ImageJ;
2. STL extraction for the head and eyes;
3. manual corneal-surface extraction in Blender;
4. local-height calculation and optional normalization in R;
5. local-height thresholding and facet-candidate condensation;
6. manual checking of facet positions in Blender;
7. edge-aware facet-neighbour selection and QC;
8. specimen-level head landmarking;
9. facet size, facet-normal, inter-facet-angle, eye-parameter, sampling-frequency, and anatomical-acuity calculations;
10. landmark-based global alignment and corneal projection;
11. optional eye mirroring; and
12. analysis-ready export and QC reporting.

The UI stores task/status information and provenance alongside the scientific outputs. Run-level process JSON includes start time, finish time, elapsed runtime, exit code, and timing scope where applicable.

Requirements

Install the following before using CV3D UI:

• Python with PySide6;
• Fiji/ImageJ, including the 3D Viewer used by the current mesh-extraction workflow;
• Blender;
• R with Rscript; and
• the CV3D R package.

Install or update the R package from GitHub with, for example:

remotes::install_github("Pete-s-Lab/CV3D")

The UI also provides an Install/update from GitHub action on its Settings page.

Starting CV3D UI

On Windows, the normal entry point is:

Start CV3D.vbs

Alternatively, run:

python CV3D_app.py

On first use, open Settings, select the Fiji/ImageJ, Blender, and Rscript executables, then use Use bundled helper scripts to populate the helper-script paths.

Documentation

The detailed illustrated workflow is provided in:

• CV3D_UI_Tutorial.pdf
• CV3D_UI_Tutorial.Rmd

The tutorial documents expected input/output files, parameter dialogs, QC plots, neighbour selection, facet-normal estimation, alignment, projection, mirroring, and final export.

Units

CV3D currently assumes that specimen mesh coordinates and length-derived values are in micrometres (µm). This also applies to externally supplied meshes. The corneal-projection sphere size is entered in centimetres in the UI and converted internally to the µm coordinate system.

Project structure and reproducibility

Each dataset is managed inside a CVxxxx_CV3D folder. Scientific outputs remain in the specimen and eye folders, while task/status JSON and logs are stored in dedicated json/ and logs/ directories. The final Results / Export step creates analysis-ready facet-level and summary tables together with metadata, a manifest, and QC output.

For runtime analyses, appropriate process records contain:

process_started_at
process_finished_at
process_runtime_seconds
process_exit_code
process_timing_scope

process_timing_scope should be used when interpreting jobs whose wall-clock time includes a shared external application session or an optional interactive window.

Issues

Please report UI problems at the repository's Issues page:

https://github.com/Pete-s-Lab/CV3D-UI/issues