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 single-channel mask image named <view>_stars. A short detection report is printed to the Process Console (number of stars detected, masked, rejected, contained, and the final mask coverage).

DeepStarMask at startup —

The DeepStarMask tool the moment we open it.

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 minimum size, in square pixels, for a structure to be considered a star (0 = automatic). Raise it to ignore the smallest detections. 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.

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.

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: a star on bright nebula whose fill leaks outward. Right: the same star 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 shows the mask on the image (not in isolation) 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, overlay (the mask tinted over the image), and side-by-side. The source image is captured when we open the preview; it can be the main view or a selected preview region.

Nuclear 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.

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 overlay and side-by-side modes — which is why DeepStarMask uses it as its single, canonical preview. The same engine is shared across our Deep Sky Colors tools, so its controls feel the same everywhere.

The Dynamic Live Preview —

The mask shown applied to the image, with the preview's own zoom, STF and display-mode toolbar. The Detection and Downsample menus, the Preview and Nuclear buttons, control the speed/accuracy of the live render.

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.