Command Line Interface (CLI)

The primary entrypoint for playNano is the playnano command-line tool. It provides interactive playback (GUI), batch processing/export, analysis runs, and an interactive wizard for building pipelines.

General usage

playnano [global options] <command> <input_file> [command options]

Run playnano --help to see global options and a list of subcommands.

Available subcommands

  • play - Launch the interactive GUI viewer.

  • process - Batch mode: apply filters and export images/bundles/GIFs.

  • analyze - Run a pipeline of analysis modules (detection/tracking) on a stack and export results.

  • wizard - Interactive REPL for constructing processing/analysis pipelines.

  • env-info- Print environment information useful for debugging.

The CLI maps to the Python entry point playnano.cli.entrypoint:main.

Quick examples

playnano play data.h5-jpk
playnano process data.ARIS --processing "remove_plane" --make-gif
playnano analyze processed.h5 --analysis-file analysis.yaml

Global options

These options apply to all subcommands (or can be used on their own).

--version

Print the installed playNano version and exit.

playnano --version

Example output:

playnano 0.5.1

This is useful for debugging, reporting issues, and reproducibility.

--log-level

Set the global logging verbosity for the CLI.

playnano --log-level DEBUG play data.afm
playnano --log-level WARNING process data.afm --make-gif

Allowed values are:

  • DEBUG - Verbose output for development and debugging

  • INFO - Standard operational output (default)

  • WARNING - Only warnings and errors

  • ERROR - Errors only

If not specified, the default log level is INFO.

Note

Global options must be specified before the subcommand name.

Batch mode operations

Processing and analysis can be run in a non-interactive batch mode without a GUI or wizard.

Batch processing mode- process

Apply filters and export without user interaction.

playnano process /path/to/sample.h5-jpk \
  [--channel CHANNEL] \
  [--processing "remove_plane;row_median_align"] \
  [--processing-file pipeline.yaml] \
  [--export tif,npz,h5] \
  [--make-gif] \
  [--make-video mp4,avi] \
  [--make-sequence] \
  [--output-folder OUTPUT_DIR] \
  [--output-name BASE_NAME] \
  [--scale-bar-nm SCALE_BAR_INT] \
  [--zmin MINIMUM] \
  [--zmax MAXIMUM] \
  [--cmap COLORMAP_NAME] \
  [--fps FRAMES_PER_SECOND]

Primary options

  • --channel (default: height_trace) - channel name to load from the file.

  • --processing - semi-colon delimited inline pipeline string.

  • --processing-file - YAML/JSON file describing the processing pipeline.

  • --export - comma-separated list of formats to write: tif, npz, h5.

  • --make-gif - write an animated GIF with current annotations.

  • --make-video - write an annotated video; specify formats (e.g. mp4, avi).

  • --make-sequence - write an annotated image sequence (PNG files).

  • --output-folder / --output-name - export location and basename.

  • --scale-bar-nm - integer length (nm) for scale bar in GIF (0 disables).

  • --zmin / --zmax - initial z-range; can be a float or auto (1st/99th percentiles).

  • --cmap - name of colormap to use for animated visualisation export (default=afm_brown).

  • --fps - the frame rate (in seconds) for GIF and video exports.

Note

--processing and --processing-file are mutually exclusive. Use one or the other (or neither to run with no processing).

Processing pipeline schema

Example pipeline YAML (see Processing for details):

filters:
  - name: remove_plane
  - name: gaussian_filter
    sigma: 2.0
  - name: threshold_mask
    threshold: 2
  - name: polynomial_flatten
    order: 2

Batch analysis mode

Run an analysis pipeline on a loaded AFM stack and export the results.

playnano analyze /path/to/processed_sample.h5 \
  [--channel CHANNEL] \
  (--analysis-steps "detect_particles:threshold=5;track_particles:max_distance=3.0" \
   | --analysis-file analysis.yaml) \
  [--output-folder OUTPUT_DIR] \
  [--output-name BASE_NAME]

Analysis options

  • --analysis-steps - semicolon-delimited inline steps (example below).

  • --analysis-file - YAML/JSON file specifying the analysis pipeline.

  • --output-folder / --output-name - export location and basename.

Inline example:

playnano analyze sample_flat.h5 \
  --analysis-steps "detect_particles:threshold=4.5;track_particles:max_distance=2.5" \
  --output-folder ./analysis_results --output-name run1

Analysis pipeline schema

Example YAML (see Analysis for full reference):

analysis:
  - name: detect_particles
    mask_fn: mask_threshold
    threshold: 5
  - name: track_particles
    max_distance: 3.0

Outputs

  • <output>.json - sanitized analysis record (suitable for downstream parsing).

  • <output>.h5 - full analysis bundle (if HDF5 export requested).

Wizard mode (interactive)

The wizard opens a small REPL to interactively build and run processing and analysis pipelines. Useful for experimentation and creating shareable YAML configurations.

playnano wizard /path/to/sample.h5-jpk --output-folder ./results --output-name demo

Common REPL commands

Processing pipeline commands

  • add <filter> - add a processing step (REPL prompts for parameters).

  • list - show the current processing pipeline steps.

  • save <path.yaml> - save the current processing pipeline as YAML.

  • run - execute the processing pipeline on the supplied input.

Analysis pipeline commands (prefixed with a)

  • aadd <analysis_step> - add an analysis step (REPL prompts for parameters).

  • alist - show the current analysis pipeline steps.

  • asave <path.yaml> - save the current analysis pipeline as YAML.

  • arun - run the analysis pipeline (runs any processing steps as configured if

    AFM stack contains only raw data).

Other utility commands

  • help - show available REPL commands.

  • quit - exit the wizard (this is a single, global quit that closes the entire session).

Play (GUI) mode

Open the PySide6 GUI viewer:

playnano play /path/to/sample.h5-jpk \
  [--channel CHANNEL] \
  [--processing "remove_plane;row_median_align"] \
  [--processing-file pipeline.yaml] \
  [--output-folder OUTPUT_DIR] \
  [--output-name BASE_NAME] \
  [--scale-bar-nm SCALE_BAR_INT] \
  [--zmin MINIMUM] \
  [--zmax MAXIMUM] \
  [--cmap COLORMAP_NAME]
  [--fps INITIAL_FRAMES_PER_SECOND]

GUI highlights

  • Playback controls (play/pause, FPS, frame slider)

  • Toggle raw vs processed views and apply processing on demand

  • Z-scale histogram with draggable zmin/zmax lines and numeric spinboxes

  • Export panel: NPZ, OME-TIFF, HDF5 and animated export options

  • Keyboard shortcuts: Space (play/pause), F (apply filters), R (toggle raw/processed), G (export GIF), E (export selected formats)

Notes about z-range

  • --zmin / --zmax accept a float or the string auto (default). When auto is used values are computed as the 1st and 99th percentiles of the stack.

Find out more on the GUI docs page: GUI: Interactive Playback

env-info

Prints environment and dependency information to help debugging and issue reports:

playnano env-info

Help & usage

  • Subcommand help:

    playnano <subcommand> --help

    Example:

    playnano process --help

  • Global help:

    playnano --help

Tips & troubleshooting

  • If the CLI command is not found, ensure your environment is activated and that you installed the package (pip install -e .) in that environment.

  • If GIF export fails, check the input metadata (e.g. line_rate) and the console logs.

  • For Windows users, installing PySide6 via conda install -c conda-forge pyside6 can reduce platform-specific issues.