FIM — Full-Field Indentation Microscopy

3D deformation tracking and inverse material characterization from volumetric (OCT / confocal) image stacks of indentation experiments. The pipeline has three steps:

1. Distortion Correction — Remove optical distortions from raw image volumes to obtain undistorted reference and deformed stacks. (Can be skipped if undistorted images are acquired directly, e.g. by scanning the material from the bottom.)
2. Deformation Tracking — Estimate the 3D displacement field between a reference and deformed volume using optimization-based image registration.
3. Virtual Fields Method (VFM) — Compute material properties (elastic moduli, fiber parameters) from the displacement field using the virtual work principle.

A lightweight web UI is provided for interactive runs. From the terminal, run each step with direct script execution (python -m fim.refactor.…), using each module’s own --help and flags (not a separate schema-driven CLI).

---

Setup and run (choose one path)

FIM offers three installation paths depending on your role and technical needs:

	Path A — Conda / pip install	Path B — Docker container	Path C — Windows installer script
Audience	Developers who edit code, add models, or tune parameters	Users who run FIM in the web browser; no local Python installation is required	Windows users who want one-click setup
Prerequisites	Git, Conda	Docker Desktop	Windows 10/11 with internet access
Install	git clone … && pip install -e .	docker run --rm -p 8000:8000 -v ~/fim-output:/data ghcr.io/ssec-jhu/fim	Run install_fim_v1.bat
Run options	Web UI or CLI	Web UI only	Web UI or CLI (inside fim_env)

Choose one path — they are independent. Full steps are under Path A, Path B, and Path C below.

Path A — Conda / pip install

---

Installation — Conda environment, clone, and editable install

Prerequisites

• Git
• Miniconda or Anaconda

# Create and activate environment (Conda example)
conda create -n fim_env python=3.11
conda activate fim_env

# Clone and enter repo (`pip` uses the active env)
git clone https://github.com/ssec-jhu/fim.git
cd fim

# Install FIM and all dependencies:
pip install -e .

If you use another Python 3.11+ environment instead of Conda, activate it and run the same pip install -e . after cloning.

For CUDA on Linux/NVIDIA, install a matching PyTorch build from pytorch.org first, then run pip install -e . again.

---

Run — Web UI or CLI

After installation you can run the pipeline in two ways:

1. Web UI — run fim-ui:

fim-ui

Open http://127.0.0.1:8000/ (use fim-ui --port 8001 if 8000 is busy).
Equivalent to uvicorn fim.app.main:app --reload. In production use --no-reload and tune --host as needed.

Form fields and defaults in the browser are driven by fim/app/schemas/fim_params.schema.json.

2. CLI — direct script execution

Run each step with python -m … against the refactor entry points below. Each script exposes its own argparse interface; omitted flags use that script’s defaults. --help / -h lists every option (for example python -m fim.refactor.deformation_tracking -h).

python -m fim.refactor.deformation_tracking \
    --with_sphere path/to/deformed_tiffs \
    --without_sphere path/to/reference_tiffs \
    --out_dir path/to/output

python -m fim.refactor.main_VFM \
    --data_path path/to/output \
    --model linear

Path C — Windows batch installer (install_fim_v1.bat)

Use this path if you are on Windows and want an automated setup.

---

Install (one click)

1. Open this repo folder in File Explorer.
2. Double-click install_fim_v1.bat (or run it from cmd).
3. Follow prompts for install location and optional immediate UI launch.

The script will automatically:

• install Git (if missing),
• install Miniconda (if missing),
• create fim_env (Python 3.11),
• clone/update the FIM repo,
• run pip install -e . with dependencies.

---

Run after install

install_fim_v1.bat already includes an end-of-install prompt:

• Launch FIM web UI now? [Y/n]
• If you choose Y (default), it starts fim-ui and opens http://127.0.0.1:8000/ automatically.

You only need manual commands if you skip launch (n) or start FIM later:

In Anaconda Prompt or cmd:

conda activate fim_env
fim-ui

Then open http://127.0.0.1:8000/.

CLI example:

conda activate fim_env
python -m fim.app.cli list-steps

Path B — Docker container

The image serves the UI with uvicorn on port 8000 (CPU PyTorch).
Prerequisite: install Docker Desktop (macOS/Windows) or Docker Engine + Compose (Linux).

---

For users — run the published image

Pull the FIM image from GHCR, then run in UI mode:

# Latest UI image from GitHub Container Registry
docker pull ghcr.io/ssec-jhu/fim:latest

# Host folder for pipeline output; appears as /data inside the container
mkdir -p ~/fim-output
# Publish UI on port 8000; bind ~/fim-output → /data; --rm drops container when stopped
docker run --rm -p 8000:8000 -v ~/fim-output:/data ghcr.io/ssec-jhu/fim:latest

Open http://localhost:8000 (not http://0.0.0.0:8000 — that address only means “listen on all interfaces” inside the container).

To refresh the image later (if the Docker image was updated):

docker pull ghcr.io/ssec-jhu/fim:latest

In the UI, outputs should live under /data (mapped to your host folder above). Override the host path with FIM_HOST_DATA_DIR if you use Compose (see below).

---

For maintainers — build / update images locally

Run from a local build (clone the repo first, then):

docker compose up --build

Defaults: ./fim-docker-data → /data, container name fim-app. Rebuild/restart:

docker compose down
docker compose up -d --build
docker compose logs -f fim

Build and publish (multi-arch push to GHCR):

docker login ghcr.io
make build   # local tag: fim:local (single architecture)
make push    # ghcr.io/ssec-jhu/fim:latest (linux/amd64 + linux/arm64)

The default published image is CPU-only (no CUDA GPU).

---

Testing (Conda setup)

Install developer dependencies:

pip install -e ".[dev]"

Using tox (recommended)

tox              # run all checks: lint, security, tests, docs, build
tox -e test      # tests only
tox -e check-style  # lint only

Outside of tox

pytest .                                        # all tests
pytest fim/tests/test_util.py::test_base_dummy  # single test
ruff check . --select E --select F --select I   # lint
bandit --severity-level=medium -r fim            # security

Build docs

pip install -e ".[docs]"
cd docs && make clean html
open _build/html/index.html

---

Project Layout

fim/
├── app/               # FastAPI web UI and pipeline runner
│   ├── main.py        # FastAPI application
│   └── schemas/       # JSON parameter schemas (web UI)
├── refactor/          # Core algorithms
│   ├── deformation_tracking.py   # Step 1: 3D displacement estimation
│   ├── main_VFM.py               # Step 2: Inverse material characterization
│   └── vws_models.py             # VFM model implementations
├── tests/             # Unit tests
├── test_data/         # Small demo TIFFs (simulate/); large fixtures
│                      # are downloaded on demand — see "Test data" below.
├── util.py            # Package helpers and dataset fetcher
└── legacy/            # Previous implementations (not actively maintained)

---

Test data

Large reference and benchmark fixtures (~260 MB of .npy arrays and .inp meshes) are not stored in the repository. They are published as assets on the data-v1 GitHub release and fetched on demand by fim.util.fetch_dataset.

# List available datasets and the local cache directory
python -m fim.util list
python -m fim.util where

# Pre-download one or more datasets (verified by SHA-256 after download)
python -m fim.util fetch 80um HGO NH exp2-benchmark

The main_VFM CLI also downloads the appropriate fixture automatically when you omit --data_path:

python -m fim.refactor.main_VFM --model hgo     # auto-fetches fim/test_data/HGO

By default data is cached under <fim package>/test_data/<name>. Set FIM_DATA_DIR to redirect the cache (useful for read-only installs or to share the cache across virtual environments), or FIM_DATA_URL_BASE to point at a mirror of the release assets.

---

License

See LICENSE.