Match a full grayscale or RGB target to a reference using a rectangular region of interest. [more]
Keywords: linear fit, ROI, grayscale, RGB, scatter plot, process instance
[hide]
[hide]
ROI Linear Fit matches the intensity scale of a target image to a source image using a rectangular region of interest (ROI). It measures the fit inside that region and applies the resulting correction to the entire target. The source remains unchanged.
[hide]
Open two different main images that are already aligned and have identical pixel dimensions. Use two grayscale images or two RGB images. A grayscale image has one fit; RGB images have separate fits for the red, green, and blue channels. Mixing grayscale and RGB is not supported.
Work with linear image data for a linear-fitting workflow. The script reads actual pixel values: a ScreenTransferFunction (STF) affects only their display. The script does not align images, remove gradients, stretch images, or save your image files.
Choose a region containing corresponding, varying signal in both images. Avoid empty borders and regions dominated by saturated pixels. Equal dimensions do not guarantee alignment.
[hide]
1. In Images, select Source (reference), whose intensity scale you want to match, and Target (to modify), which will receive the correction.
2. In Region of interest, enter X, Y, Width, and Height, or select an existing preview in Copy ROI from preview.
3. In Fit settings, choose the rejection limits and whether to clip the final result. The default limits are 0 and 0.92; clipping is enabled.
4. Click the magnifier to preview the fit and scatter plot. This leaves both images unchanged.
5. Close the plot with the red cross. Adjust the region or settings and preview again if necessary.
6. Click the green checkmark to calculate a fresh fit and apply it to the entire target. The scatter plot opens afterward if that option is enabled.
7. Inspect the target. Use PixInsight Undo to revert the correction, or save your image when satisfied.
Closing the scatter plot after applying a fit does not undo the correction. Preview and Apply each use the current image data; Apply does not reuse a previously previewed calculation.
[hide]
Source (reference) sets the desired intensity scale. Target (to modify) is corrected in place, with Undo support. Select main images rather than previews. On a fresh launch, the source is unselected and the active main image is selected as the target when available.
The correction covers the full target, including pixels outside the ROI. An enabled target mask is temporarily disabled during application and its enabled state is restored afterward. Alpha channels are preserved. The target retains its sample format, so integer images remain subject to their existing precision.
[hide]
X and Y specify the top-left pixel of the rectangle, counting from zero. Width and Height specify its size in pixels. The same rectangle is used in both images and must lie entirely within their bounds.
For example, X = 100, Y = 200, Width = 300, Height = 150 selects columns 100 through 399 and rows 200 through 349. A fresh dialog starts with X = 0, Y = 0 and a 256 by 256 rectangle, reduced to fit the initially selected active target when needed.
Copy ROI from preview lists only previews belonging to the selected source or target. The list refreshes whenever either image selection changes. A selected preview stays selected while it still belongs to either image; otherwise the selection clears and the entered ROI coordinates remain unchanged. With no image selected, no previews are listed.
Selecting a preview copies only its rectangle: the fit always reads the main image pixels, even if the preview has been processed separately. Existing previews are preserved, and the copied coordinates remain usable after the preview is closed.
The rectangle must contain at least 32 pixels. A successful fit also requires enough varying, unclipped samples in each channel. A larger, representative region is usually more useful than the smallest allowed rectangle.
[hide]
Reject low and Reject high define the pixel-value interval used for fitting. A pair qualifies only when both its source value and its target value are strictly above Reject low and strictly below Reject high. Values exactly on either boundary are excluded. The limits must satisfy 0 <= Reject low < Reject high <= 1.
The defaults are Reject low = 0 and Reject high = 0.92. These limits refer to actual normalized samples, independently of STF. They control which ROI samples contribute to the fit; they do not restrict where the final correction is applied.
Clip final result to (zero through one) is enabled by default. It clips corrected values below zero to zero and values above one to one. Disable it only for a floating-point target if you want to retain values outside this range. Integer targets require clipping. No rescaling is performed.
The correction has the form: corrected target = offset + slope × original target. The offset and slope are determined with PixInsight’s native LinearFit using the ROI. One formula is applied to a grayscale image; each RGB channel receives its own formula.
[hide]
Show scatter plot after applying the fit is enabled by default. The plot uses a snapshot of the original target and source values captured before the correction. Disable this option if you want application to finish without opening a plot. The magnifier always opens a plot.
Plot sample limit sets the maximum number of displayed pixel pairs per channel. Its default is 12000 and its allowed range is 100 to 100000. When the ROI is smaller than the limit, all pairs are shown. Larger regions use a repeatable sample distributed across the rectangle.
The sample limit affects only the plot. Native LinearFit uses the full ROI subject to the rejection limits. Increasing the plot limit can reveal more detail or rare outliers, but does not change the fit.
[hide]
The horizontal axis shows original target pixel values. The vertical axis shows source/reference values at the corresponding ROI positions. A grayscale plot displays its single fit directly, with no channel selector; its title starts with the equation y = ... and has no prefix. For RGB, use the channel selector to inspect R, G, or B; the title prefixes the equation with the selected channel.
Colored points satisfy both rejection limits. Gray points fail at least one limit. The displayed count gives the number of sampled pairs and the total number of ROI pixels per channel.
The yellow line shows source approximately equal to offset plus slope times original target. It represents the same correction that is applied to the target, not a separate fit to the displayed points. The title displays rounded coefficients; application uses full precision.
The line shows the formula before final clipping. If clipping is enabled, application limits the output to zero through one, while the line remains straight.
A narrow distribution around the line suggests that a linear relation describes the selected samples reasonably well. Noise or different spectral content can increase scatter. Curvature, distinct groups, or a broad cloud may indicate that one linear correction does not describe the region adequately. The plot alone does not prove alignment or photometric accuracy.
[hide]
Select the channel to export, click the Save icon in the plot dialog, and choose a filename ending in .png or .svg. PNG exports are 1200 by 760 pixels; SVG exports use the corresponding vector canvas. Export RGB channels separately when needed.
Plots are saved only when you request an export. Cancelling the file dialog creates no file. The plot itself is a dialog and does not create an intermediate image window.
[hide]
Triangle — New instance. Drag it to the workspace to store the current settings in a process icon.
Magnifier — Preview fit. Calculate a fresh fit and display its scatter plot without modifying either image.
Green checkmark — Apply fit. Calculate and apply the correction to the full target.
Red cross — Close the current dialog. Closing the main dialog without applying leaves the target unchanged.
Documentation icon — Help. Open this manual inside PixInsight.
Save icon in the plot — Export the currently selected channel as PNG or SVG.
Hover over an icon to read its tooltip.
[hide]
Drag the triangle to the workspace. The icon stores the source and target image IDs; ROI X, Y, Width, and Height; both rejection limits; clipping; the post-apply plot preference; the plot sample limit; and the selected plot channel. It stores settings, not image data or fitted coefficients.
To reopen the custom dialog, double-click the icon and use the Script panel’s blue Apply Global circle. Save your process icons or project if you want to retain them for another session.
Dropping an instance onto a main image executes the fit directly. The dropped-on image replaces the saved target; the saved source and ROI remain in effect. The script recalculates the fit from current pixels. Dropping onto a preview is not supported.
For unattended execution, turn off Show scatter plot after applying the fit before creating the instance. A missing or renamed saved image must be selected again; it is not silently replaced. The ROI is stored as coordinates, so the preview used to define it does not need to remain open.
[hide]
Image selection or geometry error: select two different main images of the same dimensions and color type. Check that the ROI fits inside both images. The script cannot verify that stars or other structures are actually aligned.
Invalid rejection limits: use values between zero and one, with Reject low smaller than Reject high. Avoid an interval so narrow that it removes nearly all useful signal.
Insufficient samples or failed fit verification: try a larger or different region with more intensity variation and fewer saturated pixels. Each channel needs at least 32 usable, unclipped samples with variation. All channel corrections are checked before the target is changed.
Clipping error on an integer target: enable Clip final result to (zero through one), or use a floating-point target when you need values outside that range.
Plot error after application: if the correction succeeded but the chart could not be displayed, the error message explicitly states that the fit was applied. Use Undo on the target if you wish to revert it.
The script creates hidden ROI copies for its calculations and closes those copies after success, error, or normal abort. It preserves your source, existing previews, and unrelated images. Save the corrected target separately when you are ready.