Skip to content

Live Image Editor

The Live Image Editor is a non-destructive editor for the latest FITS result of a run. It is opened from the Live Editor button in the Latest image panel or by clicking the preview.

Working image and persistence

The source FITS remains unchanged. The editor keeps its current working state in:

runs/<run-id>/outputs/live_edit.fits

This file contains the current linear float image. It is written after every successful operation, undo, redo, repeat, and reset. The active operation history is stored separately from a complete edit timeline in the PI runtime data for the run; the timeline includes explicit undo and redo actions.

Reset restores the immutable source FITS, replaces live_edit.fits, clears undo/redo and chat history, and refreshes the run preview. Old derived live_edit PNG/JPEG files are removed so they cannot be mistaken for the current FITS.

Preview and FITS values

The editor preview is generated from the current in-memory float image. It does not run another image operation. Linear values are mapped directly from [0, 1] to 8-bit for the browser preview; no histogram stretch or gamma correction is applied. The FITS remains the authoritative data representation. JPEG encoding can introduce small compression differences, but not an additional brightness or contrast adjustment.

Each successful operation keeps the previous preview. Clicking the image or the Previous/Current badge toggles between the state before and after the operation.

Controls and parameter dialogs

Operations with editable parameters open a shared dialog above the image view. The dialog can be dragged by its header and remains constrained to the visible browser area.

Changing a slider or selection generates a debounced live preview. The preview is calculated on a copy of the current working image and does not modify live_edit.fits, history, or undo/redo.

The Before/Current view checkbox at the lower left controls the display:

  • enabled: the live preview with the selected parameters is shown;
  • disabled: the unchanged current working state is shown.

Apply executes and stores the operation with the visible parameters. Cancel discards timers and pending preview responses, restores the canonical current image, and writes nothing to history.

Slider limits match backend validation. Examples include 0.5…5 for sharpening radius, 0.5…10 for local-contrast radius, 0.1…5 for levels gamma, and 0…1 for strength and protection values. Related controls such as black and white points are additionally constrained so the black point remains below the white point.

Operations

The editor supports brightness, contrast, saturation, sharpening, denoising, bilateral filtering, green removal, CLAHE/local detail, levels, shadow recovery, highlight recovery, color balance, local contrast, chroma denoise, curves, crop, inversion, reset, vibrance, color temperature, purple-fringe removal, banding reduction, star desaturation, and dehaze. Parameters are validated and clamped by the backend before the operation is applied.

Crop is available from chat with an explicit instruction such as “crop 10% border”. The backend converts the percentage into pixel coordinates and clamps the rectangle to the current image dimensions.

Signed operations such as brightness, contrast, saturation, vibrance, and color temperature can expose +/- adjustment controls. Non-invertible or one-sided operations do not use +/-.

Apply again repeats the last non-adjustable operation with exactly the same parameters. It calls the backend repeat endpoint directly and does not invoke the AI. The repeated operation is added to undo/redo and operation history.

Sharpening uses an unsharp-mask style operation (Gaussian blur plus weighted subtraction). Denoising uses OpenCV non-local means; its float image is temporarily converted to 8-bit and converted back. These operations are deterministic for the same input and parameters.

Levels, shadow recovery, highlight recovery, color balance, local contrast, and chroma denoise are executed locally and deterministically. The AI only proposes initial values; the chat endpoint does not apply them to the working image. The parameter editor displays the proposal as a non-persistent preview and provides fine-tuning controls. Only Apply changes live_edit.fits and history; Cancel leaves the state from before the AI proposal completely unchanged. Local contrast has strength and radius, chroma denoise has strength, structure protection, and soft/strong mode. Color balance supports global RGB values plus separate shadow, midtone, and highlight corrections.

Curves are edited only in the graphical curve editor and are never generated by the AI. The initial curve is diagonal. Clicking the graph adds a control point, dragging moves it, and double-click or right-click removes an internal point. Endpoints remain available. The display and image operation use the same clamped Catmull-Rom spline. Curves also supports live preview, Before/Current view, Apply, and Cancel.

Chat, history, and repeating

Chat entries containing executed operations are clickable. After confirming Apply this command again?, the stored operation is executed locally with exactly the same parameters; AI is not invoked.

AI suggestions, GUI adjustments, curves, repeated operations, and preset operations use the same structured operation format:

  • operation_history contains the currently effective operation sequence and reconstructs the current image;
  • edit_history contains the complete timeline including apply, undo, and redo;
  • chat_history contains visible messages and their associated operations.

A live preview alone is not recorded in any history. Only Apply creates a history and undo entry.

AI use

Configure AI and API key

Set up the optional AI integration once under Tools → AI & API:

  1. Select a provider and a model.
  2. Paste the API key for that provider without leading or trailing whitespace and select Save Key.
  3. Use Fetch status to verify the connection. A model can use image data when its vision status is shown as supported.

The key is stored in the local PI AuthStorage, not in tile_compile.yaml, configuration revisions, run data, image files, or chat history. Alternatively, a provider environment variable can be set in a local .env file. The complete current list of supported key and credential variables is in .env.example. A 401 error such as invalid x-api-key means that the provider rejected the active key; save the correct key again for that provider or check the .env entry.

When the optional PI sidecar is available, an API key is configured for a provider, and a model is selected, the chat request is sent to that model. The sidecar receives:

  • the user instruction;
  • recent operation history;
  • a JPEG vision preview of the current image (sent periodically to limit vision API cost).

The model returns a structured operation and parameters. The C++ backend validates the operation, applies it locally, persists live_edit.fits, and returns the new preview. The AI never writes the FITS file directly.

If no model/API key is available, the backend uses a local parser for supported simple commands. The command text selects the operation and local image statistics derive conservative strengths for brightness, contrast, and saturation. No network request is required in this mode. For free-form AI instructions with no matching local operation, chat points to Tools → AI & API.

API keys are handled by the PI/sidecar authentication mechanisms and are not written into image files, operation history, or FITS headers.

Timeline presets

The current effective operation sequence can be stored as a preset and applied to another run. The preset area provides Save as, Save, a dropdown, and Apply.

Save as asks for a name and creates a new JSON preset. Save overwrites the selected preset only after confirmation. The file stores the active operations (the exact effective image state) and the complete timeline for traceability. Presets are global and stored in .pi_memory/presets, so they can be used for any run. Applying a preset executes the operations sequentially on the current image without AI; each applied operation is then available in the normal undo stack.

Exports

The Export PNG and Export FITS actions write explicit export files to:

runs/<run-id>/outputs/live_image_export_<session-id>.png
runs/<run-id>/outputs/live_image_export_<session-id>.fits

These exports are separate from the canonical live_edit.fits working file.