API Reference

Create a new client instance. The base_url is the root URL of your Semphony control server (trailing slash is stripped). The api_key is a personal access token generated in the Semphony dashboard.

Create a new run or resume an existing one with the same name. When resume=True (default), a run with the same name is resumed if it exists; otherwise a new run is created. Pass system to target a specific system (e.g. "tescan-001"). Optional metadata dict is stored with the run.

Low-level method to invoke a capability on an attached device. You typically don't call this directly; device classes use it internally. Posts to /api/runs/{run_id}/sessions/{session_id}/commands/{capability_id}.

Download an acquisition artifact by its ID. If target_path is provided, streams the image to that file and returns the path. Otherwise returns raw bytes. Raises SemphonyApiError if image_id is None or on HTTP errors.

Create a new session for this run. Use as a context manager (with run.session() as s:) or call .start() / .close() manually for notebooks. Pass guardrails to enable safety checks during the session.

Explicitly create the session on the server. Useful in notebooks where you need the session across multiple cells. If guardrails are set, they are sent to the server after session creation. Idempotent: calling start on an already-started session is a no-op.

Mark the session (and underlying run) as finished on the server. Idempotent: safe to call multiple times. Also called automatically when exiting the context manager.

Create an imaging device instance. Provide either device_slug (e.g. "tescan-001") or device_id. At least one is required.

Attach this device to a session so it can receive capability calls. Must be called before any imaging, stage, or chamber operations.

Convenience alias for imaging.acquire(). Acquires an image with the given configuration. Set download=True to fetch the image from the server; provide target_path to save to disk.

Acquire an image with the given configuration. Blocks until the device completes. Retries up to 2 times on 504 timeout. Raises SemphonyApiError on failure. If download=True and the result includes an image_id, the image is downloaded via the API.

Capture a pyramidal ROI at the current stage position. Acquires images at each level whose FOV in the spec is > 0. Optionally saves images and manifest to target_dir. A short delay between levels allows hardware settling.

Navigate back to a previously saved ROI using correlative image matching. Loads the saved pyramid, then iteratively acquires live images and corrects stage position. Requires semphony[find-roi].

Run DeepFocus iterative autofocus. For each iteration: reads current WD/stigmation, acquires two perturbed images (WD +/- sigma), predicts corrections with the trained CNN, applies them, and repeats until convergence. Requires semphony[autofocus].

Pause the workflow and display a message in the Semphony UI. Blocks until the operator clicks Continue. Use for sample loading, manual ROI selection, or any step requiring human interaction.

Get current focus parameters: working distance (mm), stigmation X and Y. Returns a dict with keys wd_mm, stigm_x, stigm_y.

Set working distance and/or stigmation values. Only provided (non-None) parameters are sent.

Set the field of view in micrometres without acquiring an image. Dispatches to the device's SetViewField capability.

Turn the electron beam on or off. Guardrails enforce that vacuum must be present before enabling.

Return current device metrics snapshot: beam status, stage position, vacuum, stigmator, magnification, etc.

Vent the chamber (release vacuum). Used before loading or exchanging a sample. Guardrails require beam to be off.

Pump (evacuate) the chamber. Typically called after loading a sample and closing the chamber door.

Query the device for the live stage position (x, y, z, r, t). Raises SemphonyApiError on 502/504.

Return the last-reported stage position from server-stored metrics. Faster than get_pos(), but may be stale. Raises SemphonyApiError on 409 (stale).

Move the stage to an absolute position. Only x and y are required. Coordinates in mm (x, y, z) and degrees (r). Subject to stage guardrails if configured.

Move the stage by a relative offset. dx/dy in mm; dr/dt in degrees. When relative guardrails are active, the max move may be limited to a percentage of the current FOV.

List all available geometry parameters. Returns a dict keyed by index with name, count, and unit for each geometry.

Get the current value(s) for a geometry parameter. Accepts a positional name/index or keyword arguments. Example: .get("tilt_correction") or .get(index=0).

Set a geometry parameter's value(s). Provide x (required) and optionally y for 2D geometries. Example: .set("tilt_correction", x=0.0).

Reset all geometry parameters to zero. Returns a summary with reset indices.

List all available centering parameters with name, count, and unit.

Get current value(s) for a centering. Example: .get("beam_shift").

Set a centering parameter. Example: .set("beam_shift", x=0.0, y=0.0).

Create a deformation device instance. Provide device_slug or device_id.

Attach this device to a session so it can receive capability calls.

Raised when the control server cannot be reached, returns a non-2xx status, or returns a non-JSON response (e.g. a login redirect). Also wraps device-level failures (e.g. ScScanXY errors).

Import: from semphony.client import SemphonyApiError

Raised when a guardrail rule is violated before executing a capability. Includes guardrail_type (str) and details (dict) attributes.

Import: from semphony import SemphonyGuardrailException

Module-level convenience helper. Equivalent to client.run(...).

Load a SavedRoi from the filesystem. Accepts either a directory containing manifest.json or the path to the manifest itself. Resolves relative level paths to absolute paths.

Import: from semphony.models import load_roi_from_fs