Scripting and Automation

Scripting & Automation

Every registered analysis operation is also a headless Python surface — fermiviewer.api — the same engine the server and a notebook both use, with no FastAPI/browser dependency. Current coverage is 75 of 83 analysis endpoints; the eight remaining endpoints are parked 4D-STEM/tomography work. The generated coverage audit names every route and any gap. This page is the entry point; the full generated reference and complete worked scripts live in the main repo.

10-line quickstart

import fermiviewer.api as fv

img = fv.open("scan.dm4")                                   # any registered format
denoised = img.gaussian(sigma=2).image.median(window_size=3).image
stats = denoised.image_stats()
print(stats.value)              # {'mean': ..., 'std': ..., 'min': ..., 'max': ..., 'shape': ...}
csv_bytes = stats.to_csv()      # a one-row CSV, ready to write or upload
print(denoised.methods())       # "scan.dm4 was processed with fermiviewer X.Y.Z:
                                #  gaussian (sigma=2.0); median (window_size=3)."

The public surface

Surface	What it gives you
fv.open(path) / fv.Session()	Load any registered format into an Image; a Session tracks opened + derived images and their lineage
Image.<op>(**params)	Every registered op as a method — .gaussian(), .eds_quantify(), .roughness(), ... — returns a Result
Image.pipeline([{"op": ..., "params": {...}, "inputs": {...}}, ...], reference=other)	Run a whole recipe, including named auxiliary images (the same shape a saved batch preset uses), in one call
Result.value / .image / .params	A plain value (scalar/table), a derived Image, and the resolved parameters
Result.to_csv() / .to_json()	Export a dict-shaped result as a table
Image.methods() / .provenance_json()	A reproducible methods paragraph / full JSON ancestry for that image's pipeline
op categories	filter, geometry, analysis, spectral, eels, eds, diffraction

• Full generated API reference (every class, method, and op parameter, regenerated from source): docs/api-reference.md
• GUI/headless coverage audit (every analysis endpoint and registered op): docs/operation-coverage.md
• Worked example scripts (filters + roughness, EDS quantification, real corpus data): examples/

Headless batch runs — fv --script

For a no-code batch run over files or a folder, fv --script replays a saved recipe — the exact .fvbatch.json the GUI's batch dialog exports, or a bare JSON recipe — with no server and no browser:

fv --script recipe.json scan1.dm4 scan2.dm4 --out results/

{
  "steps": [
    { "op": "gaussian", "params": { "sigma": 1.5 } },
    { "op": "median", "params": { "window_size": 3 } },
    { "op": "image_stats", "params": {} }
  ]
}

Each input gets its derived image (TIFF), every value-producing step's result (CSV + JSON), and a provenance JSON written into --out. See fv --script --help for directory/glob input expansion and defaults. One bad input never aborts the rest; the exit code reports whether all inputs succeeded.

Automation in the GUI

The same operation vocabulary drives the in-app automation (Image ▸ Batch & Macro):

• Batch recipes — chain ops over all open images, with per-input success/failure and an exportable results table. Recipes save as named presets and portable .fvbatch.json files.
• Watch folder — pick a saved preset and a directory; new files that appear there are auto-run through the recipe as they land. An active watch keeps the desktop app alive.
• Macro record/replay — recorded GUI actions are captured as ops, so a recorded macro is a batch recipe: replay it, save it as a preset, or run it headless with fv --script. Steps with no batchable equivalent stay recorded and replay through their original path, with the dialog reporting how many steps are not batchable.

One vocabulary, three front doors: the Python API, the GUI batch/macro/watch tools, and the CLI all run the same server-side operations and produce the same provenance.