Improve finite-element workflow generation

.github/workflows/main.yml

@@ -20,9 +20,10 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     strategy:
+      fail-fast: false
       matrix:
-        os: [ubuntu-latest, macOS-latest]
-        python-version: [3.7]
+        os: [ubuntu-latest, macos-15-intel]
+        python-version: ["3.10"]
 
     name: ${{ matrix.os }}, Python ${{ matrix.python-version }}
 
@@ -37,7 +38,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
           miniconda-version: "latest"
           activate-environment: test
-          channels: numerics88,simpleitk,conda-forge
+          channels: numerics88,conda-forge
           auto-activate-base: false
       - uses: actions/cache@v3
         id: conda-env-cache
@@ -47,11 +48,11 @@ jobs:
       - name: Create and install dependencies
         if: steps.conda-env-cache.outputs.cache-hit != 'true'
         run: |
-          conda install -n test n88tools click flake8 matplotlib nose numpy opencv pandas pbr scipy simpleitk six sphinx pydicom gdcm "setuptools<65.6"
+          conda install -y -n test --override-channels -c numerics88 -c conda-forge vtkbone "vtk>=9.2" "numpy<2" pandas nibabel pyyaml netcdf4 pbr pytest wheel "setuptools<65.6"
       - name: Install package
         run: |
           conda activate test
           pip install -e .
       - name: Run tests
         run: |
-          nosetests tests
+          python -m pytest tests

README.rst

@@ -46,6 +46,14 @@ which was presented at the ASBMR in 2018 and published in 2020:
 For further information about the Bone Imaging Laboratory see https://bonelab.ucalgary.ca. 
 Please contact us for further questions, comments or interest in contributing to this project.
 
+Finite Element Modelling
+========================
+
+For hip and spine models, start with the `FEA run guide <ogo/fea/README.md>`_.
+The `vertebra quickstart <docs/fea/vertebra_fea_quickstart.md>`_ covers installation
+and a first L1 model; the `code map <docs/fea/implementation.md>`_ locates the
+registration, material laws, supports and QC functions.
+
 Install
 =======
 

docs/fea/implementation.md

@@ -0,0 +1,51 @@
+# FEA code map
+
+Start at `ogo/cli/GenerateFEM.py`. It parses `ogoFEA`, calls the anatomy builder,
+audits the model, runs FAIM/N88 and writes modelling metadata.
+
+| Task | File / function |
+| --- | --- |
+| CLI and site arguments | `GenerateFEM.build_parser`, `build_spine_command`, `build_femur_command` |
+| Reporting endpoint and criteria | `GenerateFEM.solve_report_profile`, `critical_volume_percent`, `critical_strain` |
+| Spine preparation and model | `spine._prepare_spine_inputs`, `_register_spine_inputs`, `process_vertebra` |
+| Hip preparation and model | `femur._prepare_femur_inputs`, `_register_femur_inputs`, `sidewaysFallFe` |
+| Hip multistart alignment | `alignment/hip.py: estimate_femur_icp` |
+| Physical scan-end/shaft measurements | `shaft_geometry.capture_distal_scan_face`, `measure_available_shaft`, `verify_model_shaft` |
+| Shared transforms | `alignment/`, `image_io.py` |
+| PMMA/contact geometry | `boundary.generate_bone_cap_mask`, `generate_projected_material_disk_vtk` |
+| Density laws and material tables | `material_laws.py`, `materials.build_bone_pmma_material_table` |
+| N88 mesh and file writing | `model.create_microfe_model`, `write_model` |
+| Solver discovery, Pistoia and results | `ogo/util/faim.py` |
+| Model construction record | `metadata.py` |
+| Generation measurements / QC rules | `qc/validation.py: measure_model`, `evaluate` |
+| Legacy measurement recovery | `qc/legacy.py: backfill_measurements` |
+| Three-view previews | `qc/render.py`, using `ogo/cli/Visualize.py` |
+| Gallery and review records | `qc/gallery.py`, `qc/review.py`, `qc/gallery_review.js` |
+
+Anatomy defaults are constants at the top of `spine.py` and `femur.py`.
+Shared helpers own geometry/material logic; the CLI owns solving and reporting.
+Changing a reporting criterion must not silently change model construction.
+Hip supports only the GT-relative flat shaft crop; the initial fixed-length crop
+is used for registration only. Spine settings are explicit keyword arguments;
+misspelled setting names raise an error before reading inputs.
+
+Spine cleans the body label, crops, estimates centroid-initialized ICP, resamples,
+builds caps/materials and applies compression. Hip captures the original distal
+scan face, rough-crops for registration, transforms the full scan, builds proximal
+supports, checks available coverage, then crops and constrains the shaft.
+Reference scaling changes the registration target, not native bone dimensions.
+The modelling JSON records spine label smoothing and resolved contact settings.
+
+For hip, the saved-model length check is
+`min(z of Greater_Trochanter_PMMA_Nodes) - median(z of Distal_Femur_Nodes)`.
+Coverage also accounts for the most proximal transformed scan-end point and
+resampling clearance, so the final face must be complete, not an oblique remnant.
+
+QC measurements are written during generation; validation reads these CSVs
+without reopening models. Legacy recovery uses registered anatomy and saved
+shaft geometry where available, recording what was recovered. Manual inclusion
+is separate from the automatic construction checks.
+
+Tests are in `tests/fea/` and `tests/util/`; run focused tests for the module
+being edited. Imaging/mesh tests require vtkbone and SimpleITK. Document changes
+to defaults and preserve their matching CLI/provenance tests.

docs/fea/vertebra_fea_quickstart.md

@@ -0,0 +1,66 @@
+# L1 FEA quickstart
+
+## Install
+
+Install Git and conda first, then:
+
+```bash
+git clone https://github.com/Bonelab/Ogo.git
+cd Ogo
+git checkout ogo-fea
+conda create -n ogo -c numerics88 -c conda-forge \
+  git pandas nibabel pyyaml vtkbone netcdf4 pbr "setuptools<69" wheel python=3
+conda activate ogo
+PBR_VERSION=0.0.1 python -m pip install -e .
+ogoFEA --help
+```
+
+`PBR_VERSION` supplies installation metadata only. The Numerics88 channel
+provides vtkbone; solving additionally requires FAIM/N88 tools and a license.
+Use tools already on `PATH`, or add `--faim_bin_dir /path/to/n88/bin` to commands.
+A separate solver conda environment can be selected with `--faim_env NAME`.
+
+## Generate and inspect
+
+Use density-calibrated QCT in mg/cm3 K2HPO4-equivalent units and a segmentation
+in the same physical space. This example uses body label 20 and process label 48;
+replace these with your dataset's labels. NIfTI geometry must preserve anatomical
+orientation, with physical z along the superior-inferior axis.
+
+```bash
+ogoFEA spine qct.nii.gz labels.nii.gz --vertebra L1:20:48 \
+  --output_path derivatives/fea --threads 4 --no-solve
+```
+
+Inspect `*_qc_3d.webp`: the body should be upright, processes posterior, and
+both PMMA caps in contact with the body. Check `*_bc_audit.json` and
+`*_qc_metrics.csv`. Registration/segmentation failures should be resolved
+before interpreting mechanical results.
+
+## Solve and report both regions
+
+```bash
+ogoFEA spine qct.nii.gz labels.nii.gz --vertebra L1:20:48 \
+  --pistoia_mask_label 20 --critical_volume 12 --masked_critical_volume 35 \
+  --critical_strain 0.007 --output_path derivatives/fea --threads 4
+```
+
+This reports reaction force at 0.68%, stiffness, full-bone Pistoia at 12%
+critical volume, and body-only Pistoia at 35%, all in `*_results.csv`.
+Critical volume is a percentage of evaluated bone; critical strain 0.007 means
+0.7% effective strain. These criteria must be justified for the intended study.
+The model-space ROI is saved as `*_pistoia_mask.nii.gz`.
+
+For a separate binary body mask, replace `--pistoia_mask_label 20` with
+`--pistoia_mask body_mask.nii.gz`. The full-bone result is still included.
+For full-bone Pistoia alone, omit the ROI and add `--run_pistoia`.
+
+## Review a cohort
+
+```bash
+ogoValidateFEA derivatives/fea --output derivatives/qc --gallery-zip --workers 4
+```
+
+Extract `gallery.zip`, open `gallery.html`, review and export the inclusion CSV.
+Browser decisions do not overwrite project files. See the
+[workflow guide](../../ogo/fea/README.md) for defaults, outputs and legacy models.

ogo/__init__.py

@@ -4,8 +4,12 @@
   '__version__',
   'version_info',
 )
-from pbr.version import VersionInfo
-
-_v = VersionInfo('ogo').semantic_version()
-__version__ = _v.release_string()
-version_info = _v.version_tuple()
+try:
+  from pbr.version import VersionInfo
+except ImportError:
+  __version__ = '0+unknown'
+  version_info = (0,)
+else:
+  _v = VersionInfo('ogo').semantic_version()
+  __version__ = _v.release_string()
+  version_info = _v.version_tuple()