MicroscopeControl

MicroscopeControl is the main module for the MicroscopeControl package. It exports all abstract types and methods for instruments, as well as the implementations for all hardware interfaces. It also provides methods for saving data to HDF5 files, and the GUI methods for user interfaces.

Uses Reexport.jl to cleanly propagate exports from submodules.

AbstractInstrument is an abstract type that all instruments should inherit from.

AbstractSystem

Abstract type for a microscope system (composite of instruments). Systems compose multiple instruments and manage their collective state.

AbstractSystemState

Abstract type for system state. Concrete implementations should contain the configuration parameters for a specific system.

anchor_h5_path(filename::String) -> String

Resolve the parent directory through the filesystem once at call time, including drive-relative paths, directory symlinks and ... Keep the leaf unchanged so HDF5 follows a symlink leaf itself. If parent resolution fails, return filename exactly as given, so the save opens the path the caller passed (a relative path then stays relative to the working directory, which still works when an ancestor of that directory is not searchable); interrupts propagate.

export_state(instrument::AbstractInstrument)

Export the state of the instrument as a tuple of attributes, data, and children.

Arguments

• instrument::AbstractInstrument: The instrument to export the state of.

Returns

• A tuple of dictionaries containing the attributes, data, and children of the instrument.

export_state(sys::AbstractSystem)

Export the state of the system as a tuple of attributes, data, and children.

Arguments

• sys::AbstractSystem: The system to export state from.

Returns

• A tuple of (attributes::Dict, data, children::Dict).

get_state(sys::AbstractSystem)

Get the current state of the system.

Arguments

• sys::AbstractSystem: The system to get state from.

Returns

• An AbstractSystemState representing the current configuration.

gui(instrument::AbstractInstrument)

Open a GUI control panel for the instrument.

Arguments

• instrument::AbstractInstrument: The instrument to build a GUI for.

gui_initialize(device, what::AbstractString) -> Bool

Call initialize(device) from a GUI panel or button. A throw is logged with @error instead of escaping into Makie's callback. Returns false after a throw, or when the device has a connectionstatus field that is still false; otherwise true.

h5_landing_path(path::String) -> String

The file a write to path lands on: path itself, or for a symlink its target, following each link's text (resolved against the link's own directory when relative) for up to 40 links. Works for a link whose target does not exist yet, which realpath refuses and which ispath reports as existing on Windows.

initialize(instrument::AbstractInstrument)

Initialize the instrument.

Arguments

• instrument::AbstractInstrument: The instrument to initialize.

initialize(sys::AbstractSystem)

Initialize all instruments in the system.

Arguments

• sys::AbstractSystem: The system to initialize.

install_skills(target=pwd(); skills=:all, force=false, quiet=false) -> Vector{String}

Copy Claude Code skills from this package's skills/ directory into target's .claude/skills/, stamping each SKILL.md with the installed package version and recording a manifest of installed files and hashes.

skills is :all or a Vector of skill names/Symbols to install selectively. On reinstall, a file whose on-disk hash no longer matches the manifest (a local edit, or a file the manifest never tracked) is left alone unless force=true; otherwise it is reported in an error listing every such file. A file a skill used to ship but no longer does is removed if it is still unmodified, or kept (and reported) if it was locally edited. A skill name or relative path that would resolve outside target's .claude/skills directory – including through a symlinked skill directory – is always refused, regardless of force. Returns the names of the skills that were (at least partially) processed.

list_skills() -> Vector{String}

Names of the Claude Code skills bundled in this package's skills/ directory, sorted alphabetically.

save_attributes_and_data(filename::String, group::String, attributes::Dict, data::Any, children::Dict{String,Any})

Saves hierarchical data to an HDF5 file.

Arguments

• filename::String: Path to the HDF5 file
• group::String: Name of the HDF5 group
• attributes::Dict: Dictionary of attributes to save
• data::Any: Data to save in the group
• children::Dict{String,Any}: Dictionary of child groups

data is written as it is, without permuting. An image is (y, x) or a stack (y, x, frame) (lab decision 0040; see docs/src/conventions.md), and any data of two or more dimensions gets the attributes dimension_order = "y,x" or "y,x,frame" and dimension_order_convention = "column-major (Julia/MATLAB); C-order tools list it reversed", with the older dimension_labels and memory_layout. C-order tools (h5py, h5dump) list the same dimensions reversed.

Files written from 2026-01-29 until this change carry dimension_order = "HW" or "HWN" for the same layout; a reader should keep accepting both spellings.

save_group_recursive(h5parent, group_name::String, attributes::Dict, data, children)

Recursively saves hierarchical data to an HDF5 file.

Arguments

• h5parent: Parent HDF5 group
• group_name::String: Name of the HDF5 group
• attributes::Dict: Dictionary of attributes to save
• data::Any: Data to save in the group
• children::Dict{String,Any}: Dictionary of child groups

save_h5(filename::String, state_data)

Save the state data to an HDF5 file.

Arguments

• filename::String: Path to the HDF5 file
• state_data: Tuple of dictionaries containing the attributes, data, and children of the instrument.

Copies the entire state tree before returning the asynchronous Task; wait it before reading. Writes in place with HDF5's "w" open, letting HDF5 follow symlinks. anchor_h5_path resolves the parent through the filesystem once at call time; the task uses that same path for writing and cleanup. Saves overwrite existing files in place and are not atomic. Every task failure, including an interrupt, logs @error "Failed to save to HDF5 file" once and rethrows. Before writing, it finds the file the write lands on (a symlink's target, following each link's text from the link's directory) and records whether that file exists; ispath on the link itself cannot be used, because on Windows it is true for a symlink whose target does not exist yet. On failure, a file the save created is removed (the target, so a link stays). An existing file is truncated to zero bytes in place, retaining its inode, owner, mode, ACLs and hard links. Cleanup failures are logged separately without hiding the original error. The snapshot does not synchronize concurrent device changes while export_state is being assembled.

An image in data is stored as it is, (y, x) or (y, x, frame), with dimension_order and dimension_order_convention attributes (see save_attributes_and_data; lab decision 0040, docs/src/conventions.md). Files from 2026-01-29 until this change carry dimension_order = "HW" or "HWN"; a reader should keep accepting both.

set_state(sys::AbstractSystem, state::AbstractSystemState)

Set the state of the system, updating all relevant instruments.

Arguments

• sys::AbstractSystem: The system to configure.
• state::AbstractSystemState: The desired state.

shutdown(instrument::AbstractInstrument)

Shuts down the instrument.

Arguments

• instrument::AbstractInstrument: The instrument to shut down.

shutdown(sys::AbstractSystem)

Shutdown all instruments in the system.

Arguments

• sys::AbstractSystem: The system to shut down.

uninstall_skills(target=pwd(); quiet=false) -> Vector{String}

Remove skills previously installed by install_skills into target, using the manifest written there. Only files whose on-disk hash still matches the manifest are removed; a locally modified file is left in place (and reported), and its skill is not counted as removed. A manifest skill name or file path that would resolve outside target's .claude/skills directory – including through a symlinked skill directory – is refused and reported rather than touched. Never touches .claude/skills itself or skills not present in the manifest.