Semphony - Licensed to TU/e Multiscale Lab logo

Reference

Capabilities reference

Complete overview of Semphony capabilities exposed through the Python SDK, control-server REST API, and MCP agent tools. Use the vendor columns to see what is implemented on TESCAN Mira 3 (SharkSEM) vs ZEISS Gemini (SmartSEM).

✓ Supported on this vendor — Not available (command will fail or is not mapped) SDK — wrapped in semphony REST — POST .../commands/{command} or system quick-control route

Imaging — acquisition & orchestration

High-level imaging workflows. Orchestrations run in the SDK; single-frame acquire is a blocking device command.

Capability SDK method TESCAN ZEISS Notes
imaging.acquire device.acquire() ✓ ✓ Blocks until image uploaded. ZEISS: optional grab_immediately freeze-then-grab.
imaging.acquire_continuous.start / .stop device.imaging.record_continuous() ✓ — Continuous ScScanXY(single=0); each finished frame is uploaded into a device acquisition sequence. record_continuous waits a fixed time and/or until a stop condition, then saves the ZIP when download_to is set. start_continuous / stop_continuous are the same two commands. Start returns sequence_id, stop returns frame_count. Frames + manifest.json are also in the run ZIP under sequences/sequence-{id}/. Essence scanning is restored on stop; the scan-speed index is left as set.
imaging.live.start / .stop REST only ✓ ✓ POST /api/systems/{system}/live/start|stop
imaging.chamber_camera.start / .stop REST only ✓ — USB chamber camera on a second SharkSEM session. POST /api/systems/{system}/chamber-camera/start|stop, frames at GET .../chamber-camera/latest.jpg.
imaging.sample_map device.sample_map() ✓ ✓ SDK snake-grid orchestration. ZEISS resolution must match DP_IMAGE_STORE.
imaging.save_roi imaging.save_roi() ✓ ✓ l0_fov_um="max" needs get_view_field_limits (ZEISS).
imaging.find_roi imaging.find_roi() ✓ ✓ Requires semphony[find-roi]. Coordinate defaults differ by vendor.
feed_snap client.feed_snap() / imaging.feed_snap() ✓ ✓ PiKVM live-view JPEG; system-level, not SEM SDK. Requires display feed configured.

Chamber & stage

Stage coordinates at the SDK boundary are canonical µm (x/y/z) and degrees (r/t). Device clients convert from vendor-native units.

Capability SDK method TESCAN ZEISS Notes
vacuum.vent chamber.vent() ✓ ✓ Guardrails require beam off before vent.
vacuum.pump chamber.pump() ✓ ✓
stage.get_pos stage.get_pos() ✓ ✓ Live SDK query (sync).
stage.get_latest_pos stage.get_latest_pos() ✓ ✓ Cached metrics; 409 if stale (>5 s).
stage.move_to stage.move_to() ✓ ✓ Async (202 + correlation_id).
stage.move_delta stage.move_delta() ✓ ✓ ZEISS: frame-relative motion. Relative guardrails limit move to % of FOV.

Focus, beam & field of view

Capability SDK method TESCAN ZEISS Notes
imaging.get_focus_params imaging.get_focus_params() ✓ ✓ WD (mm) + stigmation X/Y.
imaging.set_focus_params imaging.set_focus_params() ✓ ✓ Omitted parameters are left unchanged.
imaging.vendor_autofocus imaging.vendor_autofocus() — ✓ SmartSEM fine/coarse autofocus. imaging.autofocus() with no config delegates here on ZEISS.
imaging.vendor_auto_stigmation imaging.vendor_auto_stigmation() — ✓ SmartSEM auto-stigmation.
DeepFocus ML autofocus imaging.autofocus(AutofocusConfig) ✓ ✓ Requires semphony[autofocus]. See DeepFocus guide.
imaging.toggle_beam imaging.set_beam() ✓ ✓ Also via POST .../beam/on|off.
imaging.set_hv imaging.set_hv() ✓ ✓ TESCAN: HVSetVoltage. ZEISS: AP_MANUALKV.
imaging.set_probe_current imaging.set_beam_intensity() ✓ ✓ TESCAN: Beam Intensity index 1–18 (SetPCIndex), payload beam_intensity. ZEISS: beam_current_a in amperes (AP_IPROBE).
imaging.set_view_field imaging.set_view_field() ✓ ✓ Horizontal FOV in µm.
imaging.get_view_field_limits imaging.get_view_field_limits() — ✓ SmartSEM GetLimits("AP_WIDTH").
get_metrics imaging.get_metrics() ✓ ✓ Beam, stage, vacuum, FOV, stigmator, etc. Also GET .../sem-metrics.

Scan control, detector, blanker & freeze

Capability SDK method TESCAN ZEISS Notes
imaging.get_scan_speed / .set_scan_speed imaging.get_scan_speed() / set_scan_speed() ✓ ✓ TESCAN: ScGet/SetSpeed. ZEISS: DP_SCANRATE 0–21.
imaging.get_image_store / .set_image_store imaging.get_image_store() / set_image_store() ✓ ✓ ZEISS DP_IMAGE_STORE. TESCAN: client raster (same size table, e.g. 1024×768). Payload: width+height or image_store_index.
imaging.get_scan_rotation imaging.get_scan_rotation() ✓ ✓ ZEISS: AP_SCANROTATION / DP_SCAN_ROT. TESCAN: always 0° and disabled; SharkSEM has no scan rotation.
imaging.set_scan_rotation imaging.rotate_scan() — ✓ ZEISS: enables DP_SCAN_ROT and sets AP_SCANROTATION.
imaging.rotate_scan_delta imaging.rotate_scan_delta() — ✓ Used by find_roi when rotation correction is enabled.
imaging.disable_scan_rotation imaging.disable_scan_rotation() — ✓
imaging.get/set_blanker imaging.get_blanker() / set_blanker() ✓ ✓ Also POST .../blank/on|off.
imaging.get/set_freeze imaging.get_freeze() / set_freeze() — ✓ DP_FROZEN. Also POST .../freeze/on|off.
imaging.get/set_detector imaging.get_detector() / set_detector() — ✓ DP_DETECTOR_TYPE. Also GET|POST .../detector.
imaging.list_detectors imaging.list_detectors() — ✓ Probes available detector options.
imaging.get/set_brightness REST only ✓ ✓ Use client.invoke_capability(..., "imaging.set_brightness", {"pct": ...}).
imaging.get/set_contrast REST only ✓ ✓ Same pattern as brightness via invoke_capability.
imaging.fix_beam imaging.fix_beam_at() ✓ ✓ Point scan for EDS. Always call stop_scan() after.
imaging.stop_scan imaging.stop_scan() ✓ ✓ TESCAN ScStopScan; ZEISS leave DP_SPOT.
imaging.scan_window imaging.scan_window() ✓ — Rectangular scan region in scan space.

TESCAN SharkSEM — geometries & centerings

SharkSEM-style alignment parameters. Access via device.imaging.geometric_transformations and device.imaging.centerings.

Capability SDK method TESCAN ZEISS
imaging.geometric_transformations.list .geometric_transformations.list() ✓ —
imaging.geometric_transformations.get .geometric_transformations.get() ✓ —
imaging.geometric_transformations.set .geometric_transformations.set() ✓ —
imaging.geometric_transformations.reset .geometric_transformations.reset() ✓ —
imaging.centerings.list .centerings.list() ✓ —
imaging.centerings.get .centerings.get() ✓ —
imaging.centerings.set .centerings.set() ✓ —

EDS

Attach an EdsDevice (system_type="eds"). Vendor column shows EDAX-style EDS devices, not SEM vendor.

Capability SDK method EDS device Notes
eds.acquire_spectrum EdsDevice.acquire_spectrum() ✓ Blocking sync command. Download via client.download_file().
eds.collect_maps EdsDevice.collect_maps() ✓ Implementation-dependent; some devices return not implemented.

Runs, sessions & operator workflow

Feature SDK REST endpoint
Create / resume run client.run() POST /api/runs
Open session run.session().start() POST /api/runs/{run}/sessions
Set guardrails ImagingGuardrails on session PUT .../guardrails
Attach device device.attach(session) POST .../attach
Checkpoint session.checkpoint(name) POST .../checkpoint
Control handoff session.checkpoint() blocks GET/POST .../control-state, request-control, release-control
Await human imaging.await_human(message) POST .../await-human
Close session session.close() POST .../close
Download artifact client.download_image() GET /api/artifacts/{id}
Download file (EDS) client.download_file() GET /api/files/{id}
List sequences of a run client.list_acquisition_sequences(run_id) GET /api/runs/{run}/acquisition-sequences
Sequence details client.get_acquisition_sequence(id) GET /api/acquisition-sequences/{id}
Download sequence ZIP client.download_acquisition_sequence(id) GET /api/acquisition-sequences/{id}/download

REST quick controls (no run/session)

Dashboard and mobile app routes that dispatch directly to the first SEM on a system.

Route TESCAN ZEISS Maps to
POST .../beam/on|off ✓ ✓ imaging.toggle_beam
POST .../blank/on|off ✓ ✓ imaging.set_blanker
POST .../freeze/on|off — ✓ imaging.set_freeze
POST .../hv ✓ ✓ imaging.set_hv
POST .../probe-current ✓ ✓ imaging.set_probe_current
POST .../working-distance ✓ ✓ imaging.set_focus_params
POST .../field-of-view ✓ ✓ imaging.set_view_field
GET .../detector — ✓ imaging.get_detector
POST .../detector — ✓ imaging.set_detector
POST .../live/acquire ✓ ✓ imaging.acquire
GET .../live/latest.jpg ✓ ✓ Latest live JPEG stream
POST .../display-feed/feed-snap ✓ ✓ PiKVM crop snapshot
GET .../sem-metrics ✓ ✓ Cached SEM metrics
GET .../sem-metrics/live ✓ ✓ Live get_metrics (HUD)

MCP agent tools

The Semphony MCP server (python -m semphony.mcp) wraps the REST API for AI agents. Mutating tools require a unique idempotency_key. Long jobs return a job ID — poll with get_job.

Lifecycle

  • list_systems, list_devices
  • start_run, open_session, attach_device
  • checkpoint, await_human, close_session
  • get_control_state, request_control, release_control

Read-only getters

  • get_stage_pos, get_latest_stage_pos
  • get_focus_params, get_metrics, get_sem_metrics
  • get_view_field, get_scan_speed, get_scan_rotation
  • get_detector, get_blanker, get_latest_image
  • list_geometric_transformations, list_centerings (TESCAN)

Control (idempotency_key)

  • move_stage_to, move_stage_delta
  • set_focus_params, vendor_autofocus (ZEISS)
  • set_field_of_view, set_high_voltage, set_beam
  • set_blanker, set_scan_speed, set_scan_rotation
  • chamber_vent, chamber_pump
  • set_geometric_transformation, set_centering (TESCAN)
  • stop_scan

Long-running jobs

  • start_acquire
  • start_sample_map
  • start_find_roi
  • start_eds_spectrum, start_eds_maps
  • deepfocus_autofocus (SDK-side ML)
  • get_job — poll status/result

Server capabilities without SDK wrappers

Defined in the control server but not yet exposed as typed Python SDK methods. Call via client.invoke_capability() or extend the SDK.

  • imaging.set_magnification, imaging.set_view, imaging.set_beam_params
  • imaging.trigger_auto_beam_align
  • stage.set_limits, stage.set_unsafe_override
  • actuation.push_in_rbse, actuation.pull_out_rbse (TESCAN GUI automation)
  • kammweiss.start_measurement, kammweiss.resume_measurement, kammweiss.stop_measurement, kammweiss.update_speeds, kammweiss.start, kammweiss.stop