Region of Interest Processing

Some operations support previewing only a Region of Interest (ROI) to speed up slow operations. This works in two ways:

  • Some operations use the live preview method (e.g. Asinh Transform). If the Preview check box is active and a ROI is set, only the ROI is previewed; if no ROI is set the whole image is previewed.

  • Other operations (e.g. Deconvolution) have no live preview. With no ROI set you apply to the whole image. With a ROI set you may either apply to the whole image (Apply) or preview on the ROI only (Preview in ROI).

  • As a graphical feature, ROI processing does not apply to scripting commands.

  • ROI processing does not apply to geometry-changing operations.

  • ROI processing does not apply to operations that need the whole image for a consistent result (e.g. CLAHE).

  • ROI processing does not apply to operations that combine multiple images (e.g. Star Recomposition).

How does it work?

A chunk of gfit is copied into gui.roi.fit with a bounding rectangle (gui.roi.selection). An operation then works on either gfit (whole image) or &gui.roi.fit (ROI only).

Changed in version 1.5: gfit is a pointer now, so the fit-selection idiom is fit = (previewing && gui.roi.active) ? &gui.roi.fit : gfit; — note gfit (not &gfit as in 1.4). gui.roi.fit is a fits value, so it still takes an &. The GUI header paths moved to src/gui-gtk4 as part of the port.

The dialog wires ROI support through a handful of helpers (a well-commented exemplar is src/gui-gtk4/scnr.c; src/gui-gtk4/asinh.c shows the two-function update_preview / process_all split):

  • Include gui-gtk4/callbacks.h and gui-gtk4/siril_preview.h.

  • In the dialog startup callback:

    • call roi_supported(TRUE) — this sets gui.roi.operation_supports_roi for you and the ROI border turns green;

    • write a small callback that runs when the ROI is created, changed or deleted (the exemplar is scnr_change_between_roi_and_image); run it once, then register it with add_roi_callback(your_callback);

    • call copy_gfit_to_backup().

  • At the start of the operation, call copy_gfit_to_backup() to start from a fresh copy of gfit (if a ROI is set, this also backs up the ROI).

  • Point args->fit at &gui.roi.fit or gfit as above, and set args->for_roi on the generic_img_args accordingly (see generic_image_worker).

  • When closing the dialog:

    • call roi_supported(FALSE) (the ROI border turns back to red);

    • call siril_preview_hide();

    • call remove_roi_callback(your_callback) so it no longer runs.

Changed in version 1.5: After a full-image operation you no longer need to re-populate the ROI by hand: generic_image_worker calls populate_roi() automatically on the swap path (the populate_roi_on_complete flag is deprecated and ignored). The ROI state is guarded by the ROI mutex, exposed to the core as gui_iface.lock_roi_mutex / unlock_roi_mutex (see Locking).

Typical symptoms that you have forgotten a step are the ROI changing colour on undo or when cancelling a ROI preview. The preview and backup machinery this builds on is documented in Preview and backup system.