Engine commands

Everything FloraStack does is one of these commands: the desktop app’s buttons and menus, the command-line tool’s subcommands, the command palette (Ctrl+K), MCP tools, the desktop control channel and the Python package’s Project.run all call them. Each takes its parameters as a JSON object and returns a JSON object. florastack-cli run runs them on a project, and florastack-cli commands prints this list as JSON, with the complete schemas. Automation, MCP and Python shows how to call them.

• A query reads and returns at once; an instant command changes the session and returns; a job runs in the background, on one of the engine’s lanes, and returns its result when it ends.
• An undoable command’s changes to the project are one undo step.
• Parameters left out keep their defaults; unknown parameters are refused.

align

align.get

Alignment settings. The stack’s alignment, ordering, framing and focus settings.

Every setting, with the keys the preferences don’t set at their defaults: which terms are corrected and their limits, the processing order (automatic_order, reverse_order), the output’s framing (narrow, wide or common) and the out-of-focus threshold (min_sharp_fraction).

Parameters: none.

Result:

Example:

{}

align.info

Alignment. The stack’s alignment as the project holds it: each frame’s, the processing order and the output’s framings.

For each aligned frame: its transform from the master’s pixels and its terms (scale, rotation, shift), its brightness gain and score, its status and flags, its sharp-content fraction and what moved in it against its neighbor. For the run: the master, the frames’ size, the narrow end, the processing order and the settings it ran with. For each framing (narrow, wide, common): the size of the output it gives and the transform from its pixels to the master’s, or why the frames can’t be framed that way; framing is the one the settings choose.

Parameters: none.

Result:

Example:

{}

align.reset

Reset alignment settings. Puts every alignment setting back at its default.

Parameters: none.

Result:

Example:

{}

align.run

Align frames. Aligns the enabled frames and orders the stack from its narrow end.

Reads and develops every enabled frame in turn and aligns each to its neighbor, correcting the terms the settings say. Then the end of the stack with the narrower field of view becomes its start, and its frame the master that the others are aligned to (unless automatic_order is off, or reverse_order on), and every frame’s sharp-content fraction is measured: the frames with no in-focus detail are flagged out-of-focus, for you to disable with project.setFramesEnabled. Frames that aren’t enabled lose any alignment they had. The result lists the master, the order and the flagged and rejected frames; align.info has every frame’s details. Runs as a job; the alignment is recorded in one undo step when it ends, or not at all when it is cancelled.

Parameters: none.

Result:

Example:

{}

align.set

Set alignment settings. Changes some of the stack’s alignment, ordering, framing and focus settings.

Only the keys given change, as when a preset is applied: {"framing": "wide"} keeps the widest field of view and leaves the rest as it is. The result is checked whole, and a misspelled key is an error. The framing applies at once, since it follows from the stored alignment (align.info); the other settings apply when the stack is next aligned.

Parameters:

Result:

Examples:

{"framing":"wide"}
{"brightness":false,"rotation":false}
{"automatic_order":false,"min_sharp_fraction":0.005,"reverse_order":true}

align.sortByScale

Sort frames by scale. Puts the enabled frames in the order of their scale, then aligns them in that order.

Repairs a stack shot or imported out of order. Focus breathing, or a rail, changes the magnification steadily with the focus, so the frames’ scales give their focus order. A first pass aligns the frames as they are, to measure their scales; the frames are then sorted by scale, in the direction that keeps the stack’s present trend, and aligned again in that order, as align.run does. Disabled frames keep their places in the list. Fails, changing nothing, when the scales differ too little to sort by. Runs as a job, which reads every frame twice; the new order and the alignment are one undo step.

Parameters: none.

Result:

Example:

{}

annotation

annotation.get

Annotation layers. Lists an output’s non-destructive annotation layers.

Parameters:

Result:

Example:

{"output":3}

annotation.set

Set annotation layers. Replaces an output’s annotation layers in one undo step.

Layers are rendered onto exported copies only. Scale bars use the export’s pixels_per_micrometer calibration; automatic lengths use 1, 2 or 5 times a power of ten. Text positions are fractions of the output size. Hidden layers stay saved. An empty list removes every layer.

Parameters:

Result:

Example:

{"layers":[{"annotation":{"kind":"scale-bar"},"name":"Scale","textSize":16,"visible":true,"white":true}],"output":3}

batch

batch.run

Process batch. Queues stacks as separate projects, exports their outputs and writes a summary CSV.

Immediate subfolders are stacks; a folder with images directly inside is auto-split with project.findStacks. Mixed layouts are refused. Each stack receives the preset, a TOML file or a built-in one as builtin:<id> (preset.list), including depth-map contrast thresholds; each output is exported as the preset’s output settings say (export.run: a 16-bit TIFF unless they say otherwise, with the maps and aligned frames they ask for), the template’s extension giving way to their format’s. Failures are recorded and the queue continues. Outputs and projects are staged until the cancellable work ends, then published without replacing existing files. summary.csv lists stack, frames, method, time in seconds, warnings, project, output and error. Templates accept {stack}, {method}, {range}, {first}, {last}, {date} (UTC YYYY-MM-DD), and {params} (the method’s effective settings).

Parameters:

Result:

Examples:

{"input":"C:/Stacks","output":"C:/Results","preset":"C:/Presets/macro.toml"}
{"input":"C:/Stacks","output":"C:/Results","preset":"builtin:insect-macro"}

cache

cache.info

Cache sizes. How much the caches take: temporary projects, spilled tiles and the open project’s cache.

Walks the folders and adds up their files: the temporary projects’ folder (unnamed projects, which orphan cleanup moves to the trash once they are old), the tile folder (tiles of running stacks, and those crashed runs left), and the open project’s cache/ and previews/ folders (results kept so that nothing is computed twice; cleaned of what the project no longer refers to when it closes).

Parameters: none.

Result:

Example:

{}

cache.removeAbandoned

Remove abandoned tile files. Removes the tile folders that crashed runs left in the tile folder.

Stacks keep their accumulators’ tiles in a folder of the tile folder (the system’s temporary directory unless compute.set chose another) when they exceed their memory budget, and remove it when they end; a run that crashes leaves it behind. This removes every such folder that no run holds and that hasn’t changed for a minute (a folder from before tile folders had locks, once it is a day old). They hold nothing a run can use again, so they are deleted, not moved to the trash. The desktop app runs this at startup.

Parameters: none.

Result:

Example:

{}

cache.setFolder

Set cache folder. Puts temporary projects and spilled tiles in a folder of your choice.

Temporary projects go into projects and spilled tiles into tiles under folder, made if they don’t exist, for projects and stacks started from now on: a project open now stays where it is. A fast local drive with room to spare is best. For this engine; it isn’t stored in the project.

Parameters:

Result:

Example:

{"folder":"D:/FloraStack cache"}

calibration

calibration.get

Calibration profiles. Lists the user’s objective and magnification calibrations.

Parameters: none.

Result:

Example:

{}

calibration.set

Save calibration profiles. Replaces the user’s library of calibration profiles.

The library is saved as calibrations.json beside the host’s temporary-projects folder, independently of projects and presets. Select a profile in the Export tab to copy its value into that project’s export settings. Editing the library then leaves existing measurements reproducible.

Parameters:

Result:

Example:

{"profiles":[{"name":"10x","pixelsPerMicrometer":2.5}]}

capture

capture.calculate

Calculate rail step. Recommends diffraction-based physical rail spacing and explains sensor sampling.

Uses 550 nm light, air, pupil ratio 1, N_eff=N(1+m), NA=m/(2 N_eff), wave depth=λ/NA² and 50% overlap. Pixel pitch assesses Airy-disk sampling, not a circle of confusion. Approximate paraxial model; see book/src/user/capture.md. Motor pulses cannot be converted to this spacing.

Parameters:

Result:

Example:

{"aperture":4,"magnification":1,"pixelPitch":4}

capture.camera

Control camera. Discovers, connects or operates a supported camera on a device worker.

Actions: discover, connect (exactly one camera), disconnect, liveView (returns a temporary JPEG path), focus (signed unit pulses), markNear, markFar, invalidateMarks. Marks exist only within this connection and count relative commands, not absolute optical positions. Disable continuous autofocus and do not touch the focus ring; invalidate marks whenever uncertain. A focus error invalidates both marks. gphoto on Linux/macOS only; other builds use the watch-folder workflow.

Parameters:

Result:

Examples:

{"action":"discover"}
{"action":"focus","pulses":1}

capture.info

Capture devices. Reports connected devices, capabilities and relative lens marks.

Does no device I/O; reports busy while a worker owns the devices. Camera control requires a gphoto build on Linux or macOS. Manual focus or autofocus invalidates relative marks: use invalidateMarks before marking again.

Parameters: none.

Result:

Example:

{}

capture.rail

Control rail. Lists serial ports, connects a rail, moves it or stops it.

Actions: ports, connect (settings required), disconnect, move (micrometers), stop. Establish a safe physical zero before connecting and set the travel limit accordingly. Marlin uses relative X millimeters and M400; Arduino uses calibrated integer steps. Stop is best-effort, invalidates position and requires reconnect; use job.cancel for an active device job, which stops at its next I/O checkpoint. Zaber ASCII is explicitly unavailable. No proprietary protocols are inferred.

Parameters:

Result:

Examples:

{"action":"ports"}
{"action":"move","micrometers":50}

capture.run

Capture and stack. Shoots a lens or rail sequence into the watched folder while stacking previews.

Requires an empty input folder, output outside it and a preset. mode=rail takes frames photos separated by stepMicrometers after settling; mode=lens takes frames photos including both relative near/far marks (frames-1 intervals). Trigger=camera downloads each original atomically with a unique filename; controller sends DIY SHUTTER then waits for external ingest; external waits for a new readable frame before advancing. External/controller workflows require one photo per position and frameTimeoutMs greater than exposure plus transfer/processing time. Managed completion overrides watch.idleSeconds while shooting. On cancellation or failure, stops further movement/shots, joins hardware work and keeps completed originals. A blocking libgphoto2 call finishes before cancellation can stop the next operation; final stack publication is atomic as for watch.run.

Parameters:

Result:

Example:

{"frames":10,"mode":"rail","stepMicrometers":50,"trigger":"external","watch":{"input":"C:/Capture","output":"C:/Results","preset":"builtin:insect-macro"}}

compute

compute.info

Compute device. Which device stacks, the GPU or the CPU, and why, and how much memory stacking may use.

The compute preference (auto, cpu or gpu), the device it chose (gpu or cpu) with the GPU’s adapter, or the reason the CPU stacks, and the GPU memory budget of a stack’s accumulators. The first call in a process (or the first stack) probes the GPU: a device on the best adapter, every kernel compiled, and a self-test against the CPU’s results; with auto a software adapter isn’t taken. memory: the memory a stack’s working data may take on the host (beyond it, tiles go to the tile folder on disk), the memory installed, and the budget suggested for this machine.

Parameters: none.

Result:

Example:

{}

compute.set

Set compute device. Chooses which device stacks, and how much memory stacking may use.

device: auto (the default: the GPU when a hardware adapter passes the self-test, the CPU otherwise), cpu (always the CPU, whatever the machine has) or gpu (software adapters such as lavapipe and WARP taken too, which are slower than the CPU). budgetMb: the GPU memory a stack’s accumulators may take; beyond it, tiles move to the host between frames. memoryMb: the memory a stack’s working data may take on the host; beyond it, tiles move to the tile folder on disk, which is slower. tileFolder: that folder (empty for the system’s temporary folder). The preferences apply to stacks started from now on, for this engine; they aren’t stored in the project. Returns what compute.info does.

Parameters:

Result:

Examples:

{"device":"cpu"}
{"budgetMb":2048,"device":"auto"}
{"memoryMb":4096,"tileFolder":"D:/Cache/tiles"}

compute.test

Test the GPU. Probes the GPU again and runs its self-test, now.

What compute.info does on its first call, again: a device on the best adapter the preference allows, every kernel compiled, and a self-test against the CPU’s results, after a driver update or a GPU change, say. device is the preference to test: the engine’s when left out, and auto when that is cpu. Returns what compute.info would with that preference; the engine’s preference stays as it is.

Parameters:

Result:

Examples:

{}
{"device":"gpu"}

defects

defects.clear

Remove defect mask. Removes the stack’s defect mask, so that no pixel is inpainted.

Its file stays until the project is closed, so that undo can bring it back. Align again for it to apply.

Parameters: none.

Result:

Example:

{}

defects.detect

Detect dust and hot pixels. Finds the dust and hot pixels of the enabled frames and makes them the stack’s defect mask.

Reads up to 32 of the enabled frames, spread over the stack (at least 5 are needed), and marks the pixels that are darker than all around them by the same factor in every frame (dust) or brighter than their neighbors in most frames (hot pixels), at the same sensor pixels, grown to cover the faint rim of each dust shadow. Review the mask before stacking with it: defects.export writes it as an image to look at or edit, and defects.import reads it back. Replaces the project’s mask, as one undo step; align again for it to apply.

Parameters: none.

Result:

Example:

{}

defects.export

Export defect mask. Writes the stack’s defect mask as an 8-bit PNG of black spots on white.

For you to look at, edit in any image editor and read back with defects.import. An existing file is replaced only with overwrite.

Parameters:

Result:

Examples:

{"path":"C:/Stacks/dust.png"}
{"overwrite":true,"path":"C:/Stacks/dust.png"}

defects.import

Import defect mask. Makes an image of black spots on white the stack’s defect mask.

The image must have the frames’ size: black (or any value below half) where a pixel is defective, white elsewhere; alpha is ignored. Any format FloraStack reads will do, such as a PNG drawn over a frame, or one that defects.export wrote and you edited. Replaces the project’s mask, as one undo step; align again for it to apply.

Parameters:

Result:

Example:

{"path":"C:/Stacks/dust.png"}

defects.info

Defect mask. Whether the stack has a defect mask, where it came from and what it masks.

The defect mask marks the dust and hot pixels that sit at the same sensor pixels in every frame. The alignment jobs inpaint it in every frame before aligning them, and stacking will read the frames the same way. detect says whether align.run detects a mask when the project has none (the detect_defects alignment setting).

Parameters: none.

Result:

Example:

{}

develop

develop.get

Develop settings. The develop settings of the stack’s RAW frames, and how they were resolved.

settings are the preferences with every key they don’t set at its default. resolved is the development worked out on a reference frame (one white balance and one chromatic-aberration correction for every frame), when the project has one; current says whether it was resolved with these settings.

Parameters: none.

Result:

Example:

{}

develop.reset

Reset develop settings. Puts every develop setting back at its default.

Parameters: none.

Result:

Example:

{}

develop.set

Set develop settings. Changes some of the develop settings of the stack’s RAW frames.

Only the keys given change, as when a preset is applied: {"exposure": 0.5} changes the exposure and keeps the rest, and a nested table (noise_reduction) merges key by key. The result is checked whole. A misspelled key is an error. They apply to camera RAW and DNG frames; TIFF and other image files are imported unchanged.

Parameters:

Result:

Examples:

{"exposure":0.5}
{"noise_reduction":{"color":0.3},"white_balance":{"custom":{"temperature":5200,"tint":3}}}
{"demosaic":"fast","lens_distortion":true,"white_balance":"auto"}

edit

edit.history

Undo history. Lists what undo and redo would do, and whether the project has unsaved changes.

Parameters: none.

Result:

Example:

{}

edit.redo

Redo. Redoes the last change undone.

Parameters: none.

Result:

Example:

{}

edit.undo

Undo. Undoes the last change to the project.

Every undoable command is one step; a retouch stroke is one stroke. Refused while a running job depends on what the step would change.

Parameters: none.

Result:

Example:

{}

export

export.estimate

Estimate export size. About how many bytes exporting an output will write, and in how many files.

From the output’s size and the settings (the project’s, or the ones given): exact for uncompressed files, an estimate from typical compression otherwise, with the extras the settings ask for.

Parameters:

Result:

Examples:

{"output":3}
{"output":3,"settings":{"depth":"u8","format":"jpeg"}}

export.get

Export settings. The project’s output settings: format, depth, profile, metadata, file names and extras.

Parameters: none.

Result:

Example:

{}

export.reproduce

Reproduce an export. Recomputes an export from its sidecar and original input files.

Verifies the manifest version, software version, original SHA-256 input hashes and embedded masks. Replays each stacking method with its recorded development and alignment, then retouch and annotation layers and the original export settings. No original project or output cache is needed. Destination paths are selected here, never taken from the sidecar. CPU/GPU arithmetic can differ slightly when the device changes.

Parameters:

Result:

Example:

{"folder":"C:/Reproduced","sidecar":"C:/Exports/result.tif.json"}

export.reset

Reset export settings. Puts every output setting back at its default.

Parameters: none.

Result:

Example:

{}

export.run

Export output. Writes an output into a folder with the output settings, and its extras alongside.

The file is named by the settings’ template, with the format’s extension; the depth and confidence maps (a depth-map output’s) are written beside it as 16-bit TIFF files ending in -depth and -confidence, and the frames aligned onto the output’s canvas as 16-bit TIFF files in a folder ending in aligned. Settings given apply to this export only, on top of the project’s. Existing files are refused unless overwrite. Each file is written whole and then renamed, so a failure leaves no partial file. Scientific extras include a float TIFF in micrometers, per-frame contribution maps and alignment CSV; visible annotation layers are rendered only onto the output copy. Every export includes a settings/version/input-hash JSON sidecar, published last; export.reproduce replays it. Runs as a job.

Parameters:

Result:

Examples:

{"folder":"C:/Stacks/Exports","output":3}
{"folder":"C:/Stacks","output":3,"overwrite":true,"settings":{"aligned_frames":true}}

export.set

Set export settings. Changes some of the project’s output settings.

Only the keys given change, as when a preset is applied. format: tiff, png, jpeg, dng or open-exr; depth: u8, u16 or f32, as the format holds; then each format’s options (tiff_compression, exr_compression and exr_half, jpeg_quality and jpeg_subsampling, dng_compression and dng_look); profile: input (the frames’ own), srgb, {"wide": "pro-photo"} or {"wide": "rec2020"}, or untagged; metadata and metadata_frame (the output’s frame, from 1 in the filmstrip’s order, whose EXIF, IPTC and XMP the file gets); extended_range (32-bit float files keep values beyond [0, 1]); template, the file name without its extension, with the tokens {project}, {name}, {method}, {frames}, {first}, {last}, {date} and {id}; and depth_map, confidence_map and aligned_frames, written alongside. Scientific options: calibrated_depth with signed z_step_micrometers and z_origin_micrometers, contribution_maps, alignment_csv, annotations, and pixels_per_micrometer with calibration_name. Null clears an optional step or lateral calibration. The keys are the preset files’ [output] keys.

Parameters:

Result:

Examples:

{"depth":"u8","format":"jpeg","jpeg_quality":92,"profile":"srgb"}
{"depth_map":true,"template":"{project}-{method}-{date}"}

filmstrip

filmstrip.list

Filmstrip. Every frame’s previews, as shot and aligned, with its flags and the motion found in it.

For each frame, in the project’s order: its preview as shot (developed, its defects inpainted) and aligned onto the output’s canvas, small JPEGs of at most 512 pixels a side, as paths to read; its flags (such as moved and out-of-focus); and what alignment found moved in it against its neighbor: a score, the largest displacement and the regions, in frame pixels. A preview that is missing or out of date is left out and counted in stale: filmstrip.update makes them.

Parameters: none.

Result:

Example:

{}

filmstrip.update

Update filmstrip. Makes the frames’ previews that are missing or out of date.

Reads and develops the frames whose preview is missing or out of date (their file, the develop settings or the defect mask changed), and aligns every aligned frame’s preview onto the canvas of the framing set, which needs no frame read. A frame whose file can’t be read is listed in unreadable and keeps its previews. align.run makes them too, as it reads the frames. Runs beside other jobs as a preview; a newer call replaces an older one still running. Previews are cache files, not edits: no undo step.

Parameters: none.

Result:

Example:

{}

job

job.cancel

Cancel job. Cancels a job.

A queued job ends at once; a running one stops at its next checkpoint, and its result is discarded, so the project stays as it was. A job that is writing a file can’t be cancelled any more (cancelled is then false).

Parameters:

Result:

Example:

{"job":3}

job.list

List jobs. Lists the jobs queued and running, then the last ones that ended, with their progress and results.

Parameters: none.

Result:

Example:

{}

output

output.list

List outputs. Lists the outputs, oldest first: how each was made, its maps and its retouch layers.

Parameters: none.

Result:

Example:

{}

output.remove

Remove output. Removes an output from the project.

Its cache files stay until the project is closed, so that undo can bring it back whole.

Parameters:

Result:

Example:

{"output":4}

output.rename

Rename output. Renames an output.

Parameters:

Result:

Example:

{"name":"Pyramid, grit 0.5","output":4}

output.save

Save output. Writes an output to an image file, in the format, depth and color profile given.

The metadata (EXIF, IPTC, XMP) comes from metadataFrom, or by default from the first of the output’s frames, with the frame count in XMP. With extended_range in the spec and a 32-bit float depth (TIFF or OpenEXR), values outside [0, 1] are kept: for an output whose tone compression brought it into range (the pyramid method’s), the result from before it is written (“retain extended range”). With map, one of the output’s maps (output.list names them) is written instead, such as a depth-map output’s depth and confidence maps: maps are data, so the spec’s profile must be untagged, and a 16-bit depth keeps every level. The file is written whole to a temporary file and then renamed, so a failed write leaves nothing behind; an existing file is replaced only with overwrite. Runs as a job, which can be cancelled until writing starts.

Parameters:

Result:

Examples:

{"output":4,"path":"C:/Stacks/bee.tif","spec":{"depth":"u16","format":{"compression":"deflate","format":"tiff"}}}
{"output":4,"overwrite":true,"path":"C:/Stacks/bee.jpg","spec":{"depth":"u8","format":{"format":"jpeg","quality":92,"subsampling":"s444"},"profile":"srgb"}}
{"output":5,"path":"C:/Stacks/bee.exr","spec":{"depth":"f32","extended_range":true,"format":{"compression":"zip","format":"open-exr","half":false}}}
{"map":"depth","output":6,"path":"C:/Stacks/bee-depth.tif","spec":{"depth":"u16","format":{"compression":"deflate","format":"tiff"},"profile":"untagged"}}

parallax

parallax.animate

Export rocking animation. Exports a looping back-and-forth parallax animation as GIF.

A sinusoidal camera excursion uses the stereo baseline. Frames are rendered and encoded one at a time, with infinite looping; unknown disocclusions appear black. GIF timing is in centiseconds. The selected output and its depth/confidence maps are read from one immutable snapshot.

Parameters:

Result:

Example:

{"folder":"exports","fps":16,"frames":32,"output":3}

parallax.mesh

Export 3D mesh. Exports a textured relative-depth relief as GLB or OBJ.

GLB embeds its PNG texture. OBJ writes model.obj, material.mtl and texture.png into the chosen folder. The surface uses confidence masking and weighted smoothing; depth discontinuities can leave holes. These are relative focus depths, not metric geometry. Existing files require overwrite.

Parameters:

Result:

Example:

{"folder":"exports/model","format":"glb","output":3}

parallax.preview

View 3D relief. Builds a textured relief for the orbit viewer.

Uses the selected output’s immutable depth and confidence maps and its visible retouch. Frame zero is nearest unless reverseDepth; geometry is relative, not metric. Samples below the confidence threshold remain holes. The preview is stored in the project cache.

Parameters:

Result:

Example:

{"output":3}

parallax.stereo

Export synthetic stereo. Exports parallel or cross-eyed stereo pairs, or a red-cyan anaglyph PNG.

Parallel camera reprojection converges at relative depth 0.5. Baseline is a fraction of image width; smaller depths move right in the left eye and left in the right eye. Cross-eyed output swaps the eyes. Unknown disocclusions and masked samples are transparent; no hidden surfaces are invented. Use reverseDepth for far-to-near captures.

Parameters:

Result:

Example:

{"folder":"exports","mode":"parallel","output":3,"settings":{"baseline":0.04}}

preset

preset.apply

Apply preset. Applies a preset, a file or a built-in one, on top of the project’s preferences.

Tables merge key by key and other values replace what was there, so presets layer: one for develop settings, another for output. groups applies only some of the preset’s groups (a partial preset). Give path (a TOML file) or builtin (an id from preset.list). Every group is checked before anything changes.

Parameters:

Result:

Examples:

{"path":"C:/Presets/rail.toml"}
{"groups":["develop"],"path":"C:/Presets/insect.toml"}
{"builtin":"insect-macro"}

preset.list

Built-in presets. The presets shipped with FloraStack: each one’s id, name, description and groups.

Apply one with preset.apply and its builtin id; in batch.run and watch.run, name it as the preset builtin:<id>.

Parameters: none.

Result:

Example:

{}

preset.read

Read preset. Reads a preset file: its name, description and preferences.

Parameters:

Result:

Example:

{"path":"C:/Presets/rail.toml"}

preset.save

Save preset. Saves the project’s preferences, or some groups of them, as a preset file.

The file is TOML, written atomically. An existing file is replaced only with overwrite. By default it holds only the settings changed from their defaults, so that it layers over what a project has; with complete, every setting of its groups, the defaults included, so that applying it gives these settings whatever the project had.

Parameters:

Result:

Examples:

{"groups":["develop"],"name":"Bee","path":"C:/Presets/bee.toml"}
{"complete":true,"name":"Rail","path":"C:/Presets/rail.toml"}

project

project.addFrames

Add frames. Adds image and camera RAW files to the end of the frame list.

paths lists files and folders; a folder adds the frame files directly in it (by extension, sorted by name). Every file is read once, to check that FloraStack reads it, to hash it and to keep its metadata summary. Files that can’t be read, or that are in the project already (the same path or the same contents), are reported in skipped. Runs as a job; the frames are added in one undo step when it ends, or not at all when it is cancelled.

Parameters:

Result:

Examples:

{"paths":["C:/Stacks/bee/IMG_0001.CR3","C:/Stacks/bee/IMG_0002.CR3"]}
{"paths":["C:/Stacks/bee"]}

project.checkFrames

Check frames. Lists the frames whose files are missing or changed since they were added.

Each frame’s file is compared with what was added, by its size and modification time, and by its contents when the time changed. A missing frame can still be stacked from the cache where it was aligned; a changed one must be added and aligned again. The desktop app asks this when a project opens.

Parameters: none.

Result:

Example:

{}

project.close

Close project. Closes the open project.

Refused while the project has unsaved changes, unless discardChanges. Its running jobs are cancelled and waited for; then the cache files that nothing refers to are removed, the undo history is dropped and the project folder’s lock is released.

Parameters:

Result:

Examples:

{}
{"discardChanges":true}

project.findOrphans

Find old temporary projects. Lists the temporary projects old enough to be moved to the trash.

Orphans are unnamed projects in the temporary-projects folder that no FloraStack has open and that haven’t been saved or opened for days days (30 by default).

Parameters:

Result:

Examples:

{}
{"days":7}

project.findStacks

Find stacks. Finds where each stack starts in a batch of files holding several, shot one after another.

paths lists files and folders, as project.addFrames takes them: a folder gives the frame files directly in it, sorted by name. Every file is read once, in that order, and compared with the one before it: a new stack starts where their capture times are further apart than split.gap seconds (by default 30 s, or 8 times the batch’s median gap when that is longer), where the next frame shows another scene (it doesn’t match the one before, scoring below split.minScore, and doesn’t look like it once blurred, correlating below split.minSimilarity), where the framing jumps (the scale by more than split.maxScaleStep percent, or the view by more than split.maxShift percent of the diagonal) or where the frame size changes. Frames of one stack differ only in focus and a little in scale, so out-of-focus frames at a stack’s ends stay with it. Needs no project and changes none: the result lists each stack’s files, and every boundary with its reasons. Files that can’t be read are listed in skipped and left out. Runs as a job.

Parameters:

Result:

Examples:

{"paths":["C:/Stacks/2024-05-01"]}
{"paths":["C:/Stacks/2024-05-01"],"split":{"gap":60,"maxScaleStep":3}}

project.frames

List frames. Lists the frames in order, with their files, hashes and metadata summaries.

Parameters: none.

Result:

Example:

{}

project.info

Project information. Describes the open project: its name, folder, frames, outputs and undo state.

Parameters: none.

Result:

Example:

{}

project.moveFrames

Move frames. Moves frames to another place in the frame list.

The frames, in the order given, go before the frame now at position to of the list without them (from 0; past the end means at the end).

Parameters:

Result:

Example:

{"frames":[7],"to":0}

project.new

New project. Creates a project folder and opens the new project, closing the project that is open.

With a name, the project folder is <name>.florastack in folder; without one, the project is temporary (unnamed) and goes in the temporary-projects folder, where orphan cleanup offers to move it to the trash once it is old and still unnamed. The project that is open is closed first, which is refused while it has unsaved changes, unless discardChanges.

Parameters:

Result:

Examples:

{"folder":"C:/Stacks","name":"Bee head"}
{}

project.open

Open project. Opens a project folder, closing the project that is open.

path is the .florastack folder or its project.json. A project from an older version is upgraded in memory and written in the current format at the next save. With readOnly, the project isn’t locked against other editors and can’t be changed. Cache files that nothing in the project refers to any more are removed.

Parameters:

Result:

Examples:

{"path":"C:/Stacks/Bee head.florastack"}
{"path":"C:/Stacks/Bee head.florastack","readOnly":true}

project.removeFrames

Remove frames. Removes frames from the frame list.

The files stay where they are. Outputs made from the frames keep their pixels and their record of what they were made from.

Parameters:

Result:

Example:

{"frames":[3,4]}

project.rename

Rename project. Gives the open project a name, which makes a temporary project permanent.

The project folder keeps its name; only the name in project.json changes.

Parameters:

Result:

Example:

{"name":"Bee head, 2026"}

project.save

Save project. Saves the open project to its project.json.

Saving is atomic: a failed save (a full disk) leaves the last good save as it was. The undo history stays.

Parameters: none.

Result:

Example:

{}

project.saveAs

Save project as. Saves the open project in another folder, where it stays open.

The project goes to <folder>/<name>.florastack, named after the project: name a temporary project first with project.rename. It is saved first. A temporary project is moved out of the temporary-projects folder (copied instead where moving isn’t possible, as to another drive); a named one is copied, and the original stays as it was saved. The undo history stays. Refused while a job is running, onto a folder that exists, and for a project whose frames are stored relative to its folder when the new folder is elsewhere.

Parameters:

Result:

Example:

{"folder":"C:/Users/me/Pictures/Stacks"}

project.setFramesEnabled

Enable or disable frames. Chooses whether frames go into stacks.

Parameters:

Result:

Example:

{"enabled":false,"frames":[1,2]}

project.trashOrphans

Move old temporary projects to the trash. Moves orphaned temporary projects to the trash.

Each path is checked again before it is moved: it must still be an orphan in the temporary-projects folder. Nothing is deleted; the projects can be restored from the trash.

Parameters:

Result:

Example:

{"paths":["C:/Users/me/AppData/Local/FloraStack/projects/untitled-20260901120000-0.florastack"]}

retouch

retouch.addLayer

Add retouch layer. Adds an empty retouch layer on top of an output’s.

Parameters:

Result:

Example:

{"name":"Antennae","output":3}

retouch.cancelPaint

Cancel live stroke. Takes back the stroke being drawn.

Parameters: none.

Result:

Example:

{}

retouch.close

Close retouching. Closes the output open for retouching, caching its result.

The result is cached as the output’s retouched map, so that opening it again needs no recomputation.

Parameters: none.

Result:

Example:

{}

retouch.mapFocus

Map sharpest frames. Maps each point of the output open for retouching to its sharpest frame.

Measures the output’s frames’ focus at a quarter of their size, as the depth-map method’s first pass does, and keeps which frame is sharpest at each point as the output’s sharpest map, for retouch.sharpest. A depth-map output needs none: its depth map tells. Runs beside other jobs.

Parameters: none.

Result:

Example:

{}

retouch.open

Open for retouching. Opens an output for retouching, with its visible strokes painted.

Reads the output and paints its visible retouch strokes over it, or reads the result cached when the project was last saved, and the map of each point’s sharpest frame when the output has one (a depth map’s own, or retouch.mapFocus’s). Then retouch.setSource picks what strokes paint from, retouch.stroke paints one, and edit.undo takes it back. One output is open for retouching at a time; opening another caches and closes the one open.

Parameters:

Result:

Example:

{"output":3}

retouch.paint

Paint live. Paints part of a stroke as it is drawn, without committing it.

begin starts a stroke with the settings and samples given; later calls add their samples to it. The result shows the stroke so far exactly as retouch.stroke will paint it, which commits it; retouch.cancelPaint takes it back. Returns the region that changed, in output pixels.

Parameters:

Result:

Example:

{"begin":true,"stroke":{"brush":"details","hardness":0.5,"opacity":1,"samples":[[100,120,1]],"size":40,"source":{"frame":7}}}

retouch.removeLayer

Remove retouch layer. Removes a retouch layer and its strokes.

Parameters:

Result:

Example:

{"layer":5,"output":3}

retouch.setLayerVisible

Show retouch layer. Shows or hides a retouch layer’s strokes.

Parameters:

Result:

Example:

{"layer":5,"output":3,"visible":false}

retouch.setSource

Set retouch source. Picks the frame or output that strokes paint from.

A frame is read and developed as stacking reads it, its brightness gain applied, and warped onto the output’s canvas, then kept in the cache, so that it is read rather than decoded the next time; another output must have the output’s size. Give frame or output. Runs beside other jobs; a newer call replaces one still running.

Parameters:

Result:

Examples:

{"frame":7}
{"output":2}

retouch.sharpest

Sharpest frame. The frame where a point of the output is sharpest.

From the depth map of a depth-map output, or the map retouch.mapFocus made. x and y are in pixels of the output.

Parameters:

Result:

Example:

{"x":1200.5,"y":840}

retouch.stroke

Retouch stroke. Paints a stroke onto the output open for retouching, as one undo step.

The stroke goes on top of layer’s strokes, or of the top layer’s, in a new layer when the output has none. Its samples are [x, y, pressure] in pixels of the output, rounded to a hundredth of a pixel. Brushes: details (the source’s detail, its brightness and color matched to the output’s, with a hard edge where there is fine detail), pixels (the source as it is), darken and lighten (only where the source is darker or lighter), and eraser (back to the output as stacked; no source). When it is the stroke retouch.paint drew, it is committed as painted.

Parameters:

Result:

Examples:

{"stroke":{"brush":"details","hardness":0.5,"opacity":1,"samples":[[100,120,1],[140,130,0.8]],"size":40,"source":{"frame":7}}}
{"layer":5,"stroke":{"brush":"eraser","hardness":0,"opacity":0.5,"samples":[[300,200,1]],"size":80}}

stack

stack.average

Stack by weighted average. Stacks the aligned frames by weighted average into a new output.

Blends every frame into every pixel, each weighted by its sharpness there: the Laplacian’s energy, averaged over radius pixels and raised to power, the weights smoothed over smoothing pixels. Fast, and a good fallback for simple subjects; where near and far detail overlap, the pyramid method is sharper. Uses the project’s settings (stack.get), or the ones given for this stack only, and the stored alignment, framed as the alignment settings say (align.info): align the stack first with align.run, and again after adding or enabling frames. Frames whose alignment was rejected are left out. Pixels that no frame covers, which only wide framing has, are transparent. Runs as a job; the output is added in one undo step when it ends, or not at all when it is cancelled.

Parameters:

Result:

Examples:

{}
{"name":"Average, smooth","radius":2.0,"smoothing":2.0}

stack.depthMap

Stack by depth map. Stacks the aligned frames by the depth-map method into a new output.

Finds, for every pixel, the frame in which it is sharpest, smooths that depth map with an edge-aware filter and takes each pixel from the frames at its depth, blending the two on either side: every pixel’s color and contrast are its frames’, for smooth tones and accurate color. Where the confidence (how clearly the sharpest frame stands out) is below the threshold, as in an out-of-focus background or on a smooth surface, the depth is filled from the confident pixels around instead. radius is the estimation radius the focus is measured over, smoothing the reach of the depth map’s smoothing, and threshold how the contrast threshold is chosen: auto (from the statistics: the pixels whose depth follows noise, or else the 10th percentile), level (the absolute level) or percentile (percentile percent of the pixels). Reads every frame twice. The output keeps the depth map (the frame index scaled to 16 bits, 0 for the first frame) and the confidence map (0.5 at the threshold) as its depth and confidence maps, which output.save writes with map. Where near and far detail overlap (hair, bristles), the pyramid method is sharper. Uses the project’s settings (stack.get), or the ones given for this stack only, and the stored alignment, as stack.average does. Runs as a job; the output is added in one undo step when it ends, or not at all when it is cancelled.

Parameters:

Result:

Examples:

{}
{"name":"Depth map, more filled","percentile":50,"threshold":"percentile"}
{"radius":3.0,"smoothing":16.0}

stack.get

Stacking settings. The stacking methods’ settings.

Every setting, with the keys the preferences don’t set at their defaults: for the weighted average (average), the radius sharpness is measured over, the smoothing of the blend and the power that sets how strongly the sharpest frame wins; for the pyramid method (pyramid), the number of levels, the grit suppression, the decisions (luminance or channels), the range limit, the tone compression and the coarse limit; for the depth-map method (depth_map), the estimation radius, the smoothing radius and the contrast threshold: how it is chosen (threshold: auto, level or percentile), and its level and percentile.

Parameters: none.

Result:

Example:

{}

stack.preview

Preview stack. Stacks the aligned frames at a quarter of their size, as a quick preview.

The weighted average of stack.average, or with method “pyramid” or “depth-map” the method of stack.pyramid or stack.depthMap, on frames reduced to a quarter of their size on each side with the settings scaled to match, so that it shows in seconds what the full stack will look like. Takes the same settings as that method’s command. The result is a linear 32-bit float TIFF in the project’s previews/ folder, as a path, kept until the project is closed: no output, no undo step. Runs beside other jobs as a preview; a newer call replaces an older one still running, so call it after every change of a setting.

Parameters:

Result:

Examples:

{}
{"smoothing":3.0}
{"grit":0.25,"method":"pyramid"}
{"level":0.002,"method":"depth-map","threshold":"level"}

stack.pyramid

Stack by pyramid. Stacks the aligned frames by the pyramid method into a new output.

Decomposes every frame into a Laplacian pyramid and keeps, at every level and position, the coefficients of the frame with the most local energy: the finest detail of every frame survives where near and far structure overlap (hair, bristles, antennae), without the veils the weighted average leaves around out-of-focus edges. The finest level is blended to keep noise down (grit), choices are made on luminance or on each channel (decisions), every pixel is held within the range the frames span there (rangeLimit), and the result is brought into [0, 1] as tone says; when that changes any pixel, the result before it is kept with the output for “retain extended range” files (output.save with extendedRange and 32-bit float). coarseLimit (off by default) keeps the coarse levels’ choices within that many frames of the frame in focus there. Uses the project’s settings (stack.get), or the ones given for this stack only, and the stored alignment, as stack.average does. Runs as a job; the output is added in one undo step when it ends, or not at all when it is cancelled.

Parameters:

Result:

Examples:

{}
{"grit":0.25,"name":"Pyramid, more detail"}
{"decisions":"channels","tone":"keep"}

stack.reset

Reset stacking settings. Puts every stacking setting back at its default.

Parameters: none.

Result:

Example:

{}

stack.set

Set stacking settings. Changes some of the stacking methods’ settings.

Only the keys given change, as when a preset is applied: {"average": {"radius": 2}} changes the weighted average’s radius and leaves the rest as it is. The result is checked whole, and a misspelled key is an error. The settings apply to the next stack and preview.

Parameters:

Result:

Examples:

{"average":{"radius":2.0}}
{"pyramid":{"grit":0.25,"tone":"clip"}}
{"depth_map":{"percentile":40,"threshold":"percentile"}}

stack.slabbed

Stack in slabs. Stacks the aligned frames in overlapping slabs by one method, then the slabs by another.

For very deep stacks. Splits the frames, in the order they are stacked, into slabs of slabSize consecutive frames, neighbors sharing at least overlap frames, stacks each slab with the slabs method and the slabs with the final method (the pyramid by default, for both), each with the project’s settings (stack.get) under the ones given for this stack, as stack.preview takes them: {"method": "pyramid", "grit": 0.25}. By default a slab holds the square root of the number of frames, rounded up, and neighbors share a fifth of a slab. Slabs are stacked one at a time, in the memory of one stack. Each slab becomes an output of its own, made from its frames, for retouching to take pixels from; the final output is made from the slabs’ outputs. With reuse (the default), a slab the project has an output of already, made from the same frames, development, alignment and settings, is taken from that output instead of being stacked again: run it again with other final settings and only the slabs’ outputs are stacked, not the frames. Uses the stored alignment, as stack.average does. Runs as a job; the outputs are added in one undo step when it ends, or not at all when it is cancelled.

Parameters:

Result:

Examples:

{}
{"final":{"method":"depth-map","percentile":40,"threshold":"percentile"},"name":"Slabbed depth map"}
{"final":{"grit":0.75},"overlap":3,"slabSize":12,"slabs":{"grit":0.25}}

stack.threshold

Show contrast threshold. Shows which parts of the stack fall below the depth map’s contrast threshold.

The depth-map method follows each pixel’s sharpest frame only where that frame stands out clearly; below the contrast threshold, in smooth or blurred areas, it fills the depth from the confident pixels around. This shows where that happens, at a quarter of the frames’ size: the sharpest frame’s luminance at each pixel, black below the threshold, transparent where no frame covers it, as an 8-bit TIFF in the project’s previews/ folder (each call removes the one before), with the threshold’s level and the share of the pixels below it. Takes the threshold settings of stack.depthMap, the project’s (stack.get) when left out. The first call reads every frame, as the depth-map method’s first pass does; later calls with the same frames, alignment, develop settings and radius reuse what it measured and take milliseconds, so call it on every move of a threshold slider. Runs beside other jobs as a preview; a newer call replaces an older one still running.

Parameters:

Result:

Examples:

{}
{"percentile":40,"threshold":"percentile"}
{"level":0.002,"threshold":"level"}

watch

watch.run

Watch capture folder. Ingests settled frames, aligns arrivals and updates a preview until capture goes quiet.

Watches files directly inside input, including existing images, using native events plus polling. A frame must have unchanged size and modification time for settleMs and decode successfully, with unchanged metadata before and after the read. Truncated or locked files are retried until the quiet timeout, then reported as warnings. Files rewritten after ingest are refused. New frames extend the neighbor alignment chain; job events expose the latest preview path and frame count. After idleSeconds without a new or changed frame, runs final alignment and exports one stack and its project plus summary.csv. Waits for the first frame indefinitely. Output must be outside input. Template tokens are the same as batch.run; preset depth-map thresholds need no interaction.

Parameters:

Result:

Example:

{"idleSeconds":5,"input":"C:/Capture","output":"C:/Results","preset":"C:/Presets/macro.toml"}

Suggest a change to this chapter