DeepStarMask

2.1 Launching DeepStarMask

DeepStarMask is a standard PixInsight process — we set its parameters on the process dialog and apply it to a view. To launch it:

1. Open the image we want a star mask for.
2. In Process Explorer or via the PROCESS menu, locate DeepStarMask under any of the DeepSkyColors, Mask, or StarMask categories.
3. The DeepStarMask interface opens.
4. Tune the parameters, ideally with the Dynamic Live Preview open. Then, apply the process to the target view (drag the triangle onto the image, or drag the instance onto the view).

Applying the process creates a new mask image named <view>_stars — single-channel by default, or a three-channel RGB mask when Mask type is set to Color (see 3.2). A short detection report is printed to the Process Console (number of stars detected, masked, rejected, contained, and the final mask coverage).

2.2 Licensing

DeepStarMask runs on a trial-then-registered licensing model. During the trial period, the tool is fully functional with no feature restrictions. When the trial expires, DeepStarMask will display a notice at startup and will not open until a valid registration key is entered (see 3.5 Registration and licensing). No internet connection is needed: keys are validated offline.

3.1 Star detection

This group governs which structures are recognized as stars. DeepStarMask uses PixInsight's multiscale wavelet star detector, so these controls map to well-understood detection behavior:

• Scale (layers): The number of wavelet layers, which sets the largest star size that can be detected. More layers catch bigger stars; fewer layers restrict detection to smaller ones.

• Noise layers: The number of small-scale layers treated as noise and removed before detection. Higher values suppress the detection of noise as spurious stars, at the cost of possibly missing the very smallest real stars.

• Min structure size: The smallest structure, in square pixels, accepted as a star. Three low values have special meanings: 1 = no minimum, which keeps the tiniest 2×2 / 3×3 stars (the default); 0 = automatic, an adaptive minimum that often excludes the smallest stars; and any value > 1 = an explicit minimum, useful to ignore small artifacts (hot pixels, cosmic rays). The range is 0–100: a star mask is about stars, and structures larger than that are almost never what we are after.

• Sensitivity: Overall detection sensitivity (0–1). Higher detects more, fainter stars.

• Peak response: Peak sensitivity (0–1). Lower values accept flatter, saturated star cores (bright stars whose centers clip), so they are not skipped.

• Max distortion: A roundness gate at the detection stage (1 = round only). Lower values accept more elongated structures; raise it to reject star-shaped knots.

• Include clustered stars: Detect stars that sit close to their neighbors. With this off, the detector suppresses blended/close sources (they have no clean centroid), which can miss many stars in rich fields. It is recommended on for complete masks. Note: enabling it also raises the chance of picking up bright nebula structures as stars — see 3.3.

• Recover faint peaks: Turns on a second, independent detector that works directly on the pixels rather than on wavelet layers. It adds every local maximum whose peak rises above the local sky by more than the Peak threshold. This is how we capture the tiniest 1–2 px stars, which the wavelet detector above cannot catch reliably — they live at the finest scale that Noise layers removes, where the detector's response to individual small stars is inconsistent (they seem to appear and disappear as we nudge the settings). Off by default.

• Peak threshold: How far (in sigma above the local sky) a local maximum must rise to be kept as a star. Lower includes fainter and smaller stars, all the way down toward the noise floor; higher keeps only brighter peaks. Active only when Recover faint peaks is on.

The two detectors are complementary. The wavelet detector measures each larger star's size and shape, so its halo can be sized correctly; Recover faint peaks then guarantees the small point sources are included as well. Between them, if a star is brighter than its surroundings by the margin we choose, it makes it into the mask — we have the last word, which is exactly what a parametric detector alone cannot promise for the finest stars. The one caveat: on bright nebula, a very low Peak threshold also picks up noise peaks, so we raise it until the result is clean.

Detecting every star —

With Include clustered stars on and the smallest stars allowed, even crowded fields are detected completely.

3.2 Mask synthesis: profiling, Growth, Feather

Once stars are detected, this group decides how each one becomes mask coverage.

Star profiling selects the model used for the solid part of the mask:

• Light spread (default) — the mask covers each star plus its glow by measuring how far the star's light actually spreads above the local sky. This is a measurement of the data, not a PSF model; it follows each star's real footprint. This is the normal mask.

• Star core — the mask is built from each star's detected core signature: a disk sized to its detected area, instead of measuring the spread. Useful for a tight, predictable mask, or for inspecting what was detected.

Mask type selects how many channels the mask has:

• Grayscale (default) — a single-channel mask built from each star's luminance. The same coverage is applied to every channel of the target. This is the classic star mask, and the right choice for most work.

• Color — a three-channel RGB mask. Stars are still detected once (on luminance), but each channel's coverage is then synthesized independently from its own data, so a star that is brighter or wider in one channel gets a wider mask there. This lets a downstream process act per channel — useful for selective star-color or halo work. It requires an RGB target; on a mono image it falls back to grayscale. All the profiling, Growth, Feather and nebula controls below act on every channel in exactly the same way.

Growth sets how far the solid part of the mask extends around each star. The crucial point is that the extent is not a fixed number of pixels — it is relative to each star's own size, so a single setting scales automatically: large, bright stars get large fills and faint stars stay tight.

• In Light spread mode, Growth controls how faint a level the fill flows down to: higher Growth lowers the brightness threshold (measured against the local sky and noise), so the solid region reaches further into the faint halo.

• In Star core mode, Growth scales the core disk directly — the solid radius is the detected core radius multiplied by Growth.

Either way, raising Growth only ever grows the mask — it moves in one direction. (In Light spread mode the fill is additionally bounded by Max spread ratio; once it reaches that cap it simply holds steady rather than shrinking — see 3.3.)

Feather adds a smooth, soft margin outside the solid region — an even gradient that falls off from the solid edge all the way to the sky. Its width is scaled to each star's size, so it remains visible even on small, steep stars, not only on the largest ones. A Feather of 0 gives a hard edge; higher values give a wider, gentler transition. The whole added band is a true gradient (no near-solid inner ring). Feather applies in both profiling modes (in Star core mode it softens the core disk).

Growth and Feather —

Growth sets how far the solid mask extends (relative to each star); Feather softens the margin beyond it with an even gradient.

3.3 Keeping nebula out of the mask

A bright star sitting on bright nebula is the classic failure case for star masks: the measured fill can escape the star and flow into the surrounding nebula, producing a blob far larger than the star. DeepStarMask has two controls (both relevant only in Light spread mode, which is the mode that measures a fill) to contain this:

• Max spread ratio — an upper bound on the measured fill, expressed as a multiple of the star's own detected size. If a star's fill grows beyond this many times its detected area, DeepStarMask treats it as having leaked into the nebula and contains the mask back to the star. Because it is a multiple of the star's size, it scales with each star. It is a cap, not a target: it only acts on stars whose fill is actually overflowing — for well-behaved stars (whose fill is set by Growth), changing it has no effect. Lower values contain more aggressively (good against bright nebula); higher values allow big, genuine halos. The range runs up to 60 so that genuinely large stars (with very wide glow) can keep their full measured shape instead of being capped — raise it until the cap stops clipping them. Default 8.

• Min roundness — rejects bright nebula patches that the detector mistook for stars. A star's bright body is round; a nebula knot resolves to a lobed, irregular region. Detections rounder than this threshold are kept, less-round ones are skipped. 0 turns it off. Raise it until the lobed patches disappear; back off if real (spiky or merged) stars start dropping. This is a deliberately conservative tool — it cannot perfectly separate every round-ish nebula patch from a real star, so use it gently.

The detection report in the Process Console tells us how often each defense fired: rejected (roundness) counts patches skipped by Min roundness, and contained (oversized) counts fills capped by Max spread ratio.

Containing a leak —

Left: two stars on bright nebula, applying a Light spread mask (driven by star glow, not by star core's profile), and the spread leaking outward due to nebulosity behind, not star glow. Right: the same stars contained by Max spread ratio.

3.4 Dynamic Live Preview

This is the heart of interactive tuning. Instead of guessing and re-applying, we open a dedicated Dynamic Preview window that shows the star mask applied to our image and refreshes live as we move any control. The group has a small two-button toolbar plus two option menus.

Preview button (blue-ring icon) — opens or closes the Dynamic Preview window. The window can show the mask on the image, just the mask, or just the image, and has its own toolbar: zoom (in / out / fit / 1:1), an STF auto-stretch (so a linear image is not near-black), and mask display modes — image only, mask only, and overlay (the mask tinted over the image). The source image is captured when we open the preview; it can be the main view or a selected preview region. A preview is recommended when the source image is over 2048px on its longest side.

Nuclear Preview button (red-ring icon) — a one-shot that renders the preview once at full resolution: every star detected and synthesized exactly as the applied mask will be. We use it to confirm the exact result, since the live preview works on a downscaled copy for speed (so the very smallest stars may not show). It can take a moment on large frames; the result stays in the window until our next parameter change replaces it with a fast live render. It is enabled whenever the image is larger than 1024 px (where the live preview is downscaled), and disabled for smaller images, where the live preview is already full resolution.

How the speed works. The live preview computes on a downscaled copy of our image: detection at a resolution we choose, and synthesis plus display at about 1024 px. That keeps tuning fast even on very large frames. Two menus govern the speed/accuracy trade, and both affect only the preview — never the applied mask:

• Detection — the resolution at which the live preview detects stars. A heavy downscale shrinks small stars below a detectable size, so detecting at a higher resolution recovers them; the cost is a (cached) re-detection whenever we change a detection parameter, while synthesis tuning stays fast. The menu offers only resolutions at or below our image's size, plus Full resolution. When we open the preview, DeepStarMask picks a sensible default automatically — 2048 px for large images, 1024 px for smaller ones (never higher than 2048) — and we can change it for the session.

• Downsample — how the source is reduced for detection (this does not affect the displayed image or the applied mask). Preserve peaks keeps every block's brightest pixel, so the faintest small stars survive the downscale — but the grainy background it produces makes Noise layers behave erratically in the preview. Clean background keeps detection — and especially Noise layers — behaving like the real image; recover small stars by raising the Detection resolution instead. This menu is disabled at Full resolution detection, where there is no downscale to choose.

When our image already fits within about 1024 px, the live preview is full resolution to begin with: there is nothing to downscale, so the Detection and Downsample menus and the Nuclear button are all disabled. This is why working on smaller previews is recommended.

Because the Dynamic Preview is a genuine image-display engine (not PixInsight's built-in Real-Time Preview), it can show the mask applied with or withour overlay, and we can zoom in up to 32x and move around the preview, which is why DeepStarMask uses it, rather than PixInsight's internal RT Preview window. The same engine is shared across our Deep Sky Colors tools.

The preview's bottom toolbar. The Dynamic Preview window carries its own toolbar along the bottom, with controls for how the preview is displayed. None of them change the mask we apply — they are viewing aids only:

• Scale — the zoom field. We type any value from 1.0x to 32.0x (the trailing "x" is optional) and press Enter, or click outside the field, to apply it. This is how we zoom right in to inspect the mask edge around individual stars.

• Mask preview modes — three buttons choose what the preview shows: Image only (hide the mask and just look at the picture), Mask only (the mask on its own, as a grayscale image), and Mask overlay (the image with the masked-out pixels tinted red — the most useful view for judging coverage on the actual stars). A fourth button, Invert mask, shows the mask inverted in the preview only; it does not change the mask we apply. The convenient part is how we switch: clicking the button of the mode we are already in flips back to the mode we came from, and repeated clicks keep toggling between those two. So we can leave, say, Mask overlay and Image only on the same finger and A/B between them with single clicks, instead of hunting across the toolbar.

• Quality — how the preview bitmap is resampled for display: Smooth (bilinear interpolation, the natural choice for ordinary viewing) or Precise (nearest-neighbor, giving crisp, square pixel boundaries when we are zoomed in to examine individual mask pixels). Display only; it has no effect on the mask.

• STF — two screen-stretch buttons that auto-stretch the displayed image so a linear (unstretched) frame is not shown almost black. Linked computes a single stretch from the pooled RGB statistics and applies it to all three channels, preserving color balance; Unlinked stretches each channel independently. Clicking whichever STF button is currently active turns the stretch back off. As with the rest of the toolbar, STF changes only how the image looks on screen — never the mask or the underlying data.

The Dynamic Preview's bottom toolbar —

From this toolbar we control how the preview is displayed: the Scale (zoom) field, the mask display modes (image only / mask only / overlay, plus invert), the Quality resampling menu, and the STF auto-stretch buttons. These affect the on-screen preview only, not the mask we apply.

3.5 Registration and licensing

The Preferences button (the wrench icon on the process interface bar) opens the DeepStarMask license information dialog. This dialog reports the current license state:

• Licensed — shows the email the module is licensed to.
• Trial — shows the number of trial days remaining.
• Expired — prompts us to register to keep using the tool.

When the module is not yet licensed, the dialog shows a "Click here to register" link. Clicking it opens the registration dialog, where we enter our email and license key. The fields are validated as we type, and the Register button enables only once a valid email/key pair is entered. After a successful registration the info dialog refreshes in place to the "licensed to" state — no need to reopen it.