PixInsight Connector

Register image files onto a reference image file with StarAlignment, file to file (no views are opened). Targets run in batches of at most batch_size (20 at most), one StarAlignment execution per batch. Registered files (<name><output_postfix>.xisf) go to output_dir, which must lie inside <workspace>/output (a relative path is resolved there) or the state folder. matrix_only: StarAlignment in OutputMatrix mode, reporting the registration per target without keeping any image file; its output directory is a temporary folder under <workspace>/agentic/scratch/align_files that is deleted afterwards, and any file written there is listed. Per target the result gives the outputData values StarAlignment reports (output file, star pair matches, errors, transformation elements, as this PixInsight names them). Runs without geometry confirmation dialogs.

Align a target image to a reference image using StarAlignment. The target is replaced in place with the aligned version.

Apply a mask to a target view. The mask protects areas where it is black (0) and allows processing where it is white (1). Use inverted=true to flip this.

Stretch a view in place with PixInsight's auto-stretch (the ScreenTransferFunction Auto Stretch computation), applied as a HistogramTransformation. Per channel, sigma = 1.4826 × MAD (the median absolute deviation from the median). A channel whose median is below 0.5 gets shadows clipping c0 = median + shadows_clipping × sigma, clamped to [0,1] (0 when sigma is 0), and midtones balance m = MTF(target_bg, median − c0), where MTF(m, x) = (m − 1)·x / ((2m − 1)·x − m); a channel whose median is above 0.5 is treated as inverted: highlights clipping c1 = median − shadows_clipping × sigma (1 when sigma is 0) and m = MTF(c1 − median, target_bg). linked: one transform for R, G and B, with c0 (or c1) the mean over channels of the per-channel clipping points (a channel with sigma 0 adds 0, or 1 for c1) and the mean median in place of the median; the image is treated as inverted only when every channel median is above 0.5. The defaults of shadows_clipping, target_bg and linked are PixInsight's auto-stretch defaults. Fails, changing nothing, when the clipping point leaves no range for a midtones balance.

Stop a job started by run_pjsr or run_pjsr_file with `async`. A job PixInsight has not started yet is removed and never runs. A running job is stopped at its next processEvents() call, where an error with MCP_CANCELLED ends the script; a native process call (a single long process, a file save) cannot be interrupted, so the stop takes effect after it returns, and what the script already changed stays changed. Without job_id: the running job. job_status reports the outcome.

List catalogue stars over a plate-solved view from PixInsight's local Gaia database: one Gaia search centred on the image, with a radius reaching its corners (plus margin_fraction), down to mag_limit. Per star: image x, y, RA, Dec, G, BP-RP where the catalogue has them, whether it falls inside the frame, and for in-frame stars the peak luminance in a 5x5 box (with saturated = peak >= saturation_level when that is given). data_release omitted: releases are asked get-info in the order DR3/SP, DR3, EDR3, DR2 and the earliest of them that reports valid is searched; a failed search is reported, not retried on another release. supplement adds stars the catalogue lacks (marked with their name); a Gaia star within merge_px of one is replaced by it. Sorted by G, brightest at the top. The full list is written to a JSON file under <workspace>/agentic/scratch/catalog; the reply carries it inline up to 200 stars.

Clone an image to a backup view, which can be restored from later with restore_from_clone. The clone keeps the image's FITS keywords, astrometric solution and view properties.

Close an image window to free memory.

Close and delete a mask window to free memory.

Combine 3 mono views into a single RGB color image using ChannelCombination. All 3 views must have identical dimensions. Returns the view ID of the combined image.

Compare two open views of the same width, height and channel count, pixel by pixel, over the whole image or a rectangle. Per channel: maximum, mean and 99th-percentile absolute difference, and the fraction of samples outside [0, 1] in each view. "identical" is true when every absolute difference is 0. The 99th percentile is taken over at most 2,000,000 evenly spaced samples (p99Samples says how many); maximum and mean use every sample. Neither view is changed.

Compress bright values in place above a knee that varies per pixel. A luminance image (Rec.709 weights for colour) is blurred with a Gaussian of sigma blur_sigma and divided by its maximum, giving L in [0,1]; the knee is min_clamp + (max_clamp − min_clamp)·(1 − L), so it equals min_clamp where L = 1 and max_clamp where L = 0. mode soft: a value above the knee becomes knee + headroom·(1 − exp(−rate·(value − knee)/headroom)); mode hard: min(value, knee). The same expression is applied to every channel and the result is truncated to [0,1].

Subtract the scaled R channel of an RGB view from an Ha view, in place. Ha = max(0, Ha - continuum_factor * R). Runs as 64-bit PixelMath truncated to [0,1]; reports the new median and max.

Copy the astrometric solution (WCS) and observation keywords from a source image file to a target view. Source and target must have the same dimensions; the target's pixels are unchanged.

Create three masks from percentiles of the image's own luminance. Subject pixels are those brighter than the background median + 5 MAD, sampled inside a circle of radius 0.35 * min(width, height) around their brightness-weighted centroid. Core = above the subject percentile 85 + 10 * core_bias; shell = a triangular ramp between the 25th percentile and the core level, peaking at their midpoint; outer = subject level up to the 25th percentile. Each is feathered over 20 px outside the circle and Gaussian-blurred with sigma 5, 10 and 20. Creates views azone_core, azone_shell and azone_outer, replacing views of those names; fewer than 50 sampled subject pixels is an error.

Create a luminance mask from a color view: Y = 0.2126R + 0.7152G + 0.0722B, then an optional blur and shadow clip.

Create a mono view from a weighted sum of Ha and OIII. It is ha_weight * Ha + oiii_weight * OIII, replacing any view of that name; with max_value the result is min(…, max_value); it is then truncated to [0,1]. Reports the new view's median and max.

Create core, shell and halo masks from three fixed luminance thresholds. Luminance is the Rec.709 luma of a color view, the samples of a gray one: core = above core_clip, shell = shell_clip to core_clip, halo = halo_clip to shell_clip, each ramped linearly from 0 to 1 across its band and Gaussian-blurred with sigma 8, 12 and 20. Creates views mask_core, mask_shell and mask_halo, replacing views of those names. Requires halo_clip < shell_clip < core_clip < 1.

Crop pixels off the edges of an image, in place. Amounts are pixels to remove from each side. All four amounts 0 (or omitted) runs nothing and leaves the image, and its astrometric solution, unchanged. Crop runs with noGUIMessages, so PixInsight writes its warnings to the Process Console instead of opening a confirmation dialog. A crop deletes the image's astrometric solution (PixInsight behaviour); the result says when one was removed.

Describe one PixInsight process by its PJSR constructor name: whether it can run on a view and/or globally, its current parameter values and their types, and any named numeric constants it exposes for those parameters.

Add Ha and OIII (mono views) to an RGB view in place, through a temporary luminance mask. R += ha_strength * Ha; B += oiii_strength * OIII; G += f * ha_strength * g_ha_fraction * Ha + (1 - f) * g_strength * OIII, with f = (OIII*Ha)^(1-OIII*Ha). Each channel above max_output becomes max_output + (x - max_output) * rolloff. The mask is the Rec.709 luminance of the target, Gaussian-blurred with sigma mask_blur, then 0 below mask_clip and (x - mask_clip) / (1 - mask_clip) above it; it is removed afterwards. Runs as 64-bit PixelMath truncated to [0,1]; reports the median and the R and B maxima.

Create a folder, with any missing parents, inside the workspace's output folder or state folder. A relative path is resolved under <workspace>/output; an absolute one must lie inside <workspace>/output or the state folder (<workspace>/agentic by default), and a path anywhere else is refused. An existing folder is left as it is. Returns the absolute path.

Write an image to a file in the workspace's output or state folder. A relative file_path is resolved under <workspace>/output; an absolute one must lie inside <workspace>/output or the state folder (<workspace>/agentic by default), and a path anywhere else is refused. Format comes from the extension: .tif/.tiff, .png, .jpg/.jpeg, .xisf, .fits. TIFF and PNG default to 16-bit, JPEG to 8-bit; use 32 for float. The file keeps the image's FITS keywords, astrometric solution and view properties (formats that cannot store them drop them). The working image is not changed. Missing parent folders are created.

Create a mono view from the B channel of an RGB view minus its scaled R channel. OIII = max(0, B - continuum_factor * R); any view of that name is replaced. Reports the new view's median and max.

Search PixInsight's built-in filter and camera QE database by name (case-insensitive substring). A grouped name also matches each name it stands for ("Sony IMX411/455/461/533/571" matches "IMX533"); results are ordered exact name, then substring, then grouped-name matches. Use it to pick exact names for run_spfc or run_spcc. Sensor QE curves have channel Q.

Get dimensions, channel count, and color status for one or more views. Every channel must have identical dimensions before ChannelCombination.

Get image statistics: median, MAD, min, max, per-channel medians, and per channel the fraction of samples at exactly 0 and at exactly 1 (clampFractions).

Raise the luminance of an RGB view in place where Ha exceeds it, keeping colour ratios. With Y the Rec.709 luminance, each channel is multiplied by (Y + strength * max(Ha - Y, 0)) / Y. Runs as 64-bit PixelMath truncated to [0,1].

Add Ha to the red channel of an RGB view in place, where Ha exceeds R by a given fraction. Where Ha > R * (1 + brightness_limit), R becomes R + strength * (Ha - R); elsewhere R, and G and B everywhere, are unchanged. With max_output and rolloff, R above max_output becomes max_output + (R - max_output) * rolloff. Runs as 64-bit PixelMath truncated to [0,1]; reports the new R maximum and the image median and max.

Report what this PixInsight installation has, by asking PixInsight. gaia: Gaia get-info for DR2, EDR3, DR3 and DR3/SP (valid, database files, magnitude range, mean spectra) and a 0.1-degree search on the lowest valid release. mars: one MultiscaleGradientCorrection run per MARS file (from PixInsight settings, or mars_files) on a temporary synthetic plate-solved image; per file: readable, missing or corrupt, and how many MARS reference images cover the probe position. xterminators: BlurXTerminator, NoiseXTerminator and StarXTerminator run once each on a temporary 64x64 image; reports version, ML model version and gpu/cpu from their console banner (null when not printed). processes: the PixInsight core version and build, whether MultiscaleAdaptiveStretch, MultiscaleGradientCorrection, BlurXTerminator, NoiseXTerminator and StarXTerminator are installed processes, and whether ImageSolver, AstrometricSolutionVerifier, DistortionEvaluator, FFTRegistration and MosaicByCoordinates are installed scripts, with the version each script declares; nothing is run. system: free and total memory, free space on the workspace volume. Temporary images are closed; open images are not touched. Without ra_deg/dec_deg the probe position is RA 0, Dec 0 and coverage is reported as null.

Report on a job started by run_pjsr or run_pjsr_file with `async`: its state (queued, running, ending = stopped in PixInsight with its result not yet collected, done, failed, cancelled, stopped), elapsed time, seconds since the running script last called processEvents(), its latest mcpProgress() text, and, once it has ended, its result or error and PixInsight console errors. Without job_id: the running job, else the most recent one. Read-only; it does not use PixInsight, so it answers while a job runs.

Run LinearFit to scale a linear image to match a reference view. The reference is not modified.

List all currently open images in PixInsight with their dimensions and color status.

List the runtime tool packs discovered at server startup, with load status, tool counts, why any pack was skipped, and which core tools packs replaced. Read-only.

List every PixInsight process available on this installation, by its PJSR constructor name (e.g. "SCNR", "PixelMath"). Read-only; classifies by prototype chain and never instantiates a process to build the list.

Replace the lightness of an RGB view with a grayscale L view using LRGBCombination, in place on the RGB view. Only the L channel is enabled, so the RGB view keeps its own color channels. lightness and saturation are LRGBCombination's transfer-function midtones balances mL and mc (0.5 leaves that component unchanged). When linear_fit_reject_high is given, the call also runs LinearFit on the L view (modified in place, ahead of the combination) against a temporary luminance image 0.2126 R + 0.7152 G + 0.0722 B of the RGB view; when it is omitted, no LinearFit runs. Chrominance noise reduction and highlight clipping are left at PixInsight's defaults.

Measure chroma, (max - min) / max, of the bright pixels of a colour view: every 8th pixel whose mean of R, G and B is above brightness_threshold. Returns JSON: median_chroma, mean_chroma, p25_chroma, p75_chroma, bright_pixel_count. A mono view is an error.

Count image blocks with pixels above a level. Tiles the image in block_size px blocks and samples every 3rd pixel; a sample counts when its luminance or any channel is above level, and a block counts when more than block_fraction of its samples do. Returns JSON: blocks_over, total_blocks, locations (up to 10 counted blocks in descending fraction order: x, y, fraction). luminance is 0.2126R + 0.7152G + 0.0722B.

Measure how much of the brightest region is above a level. Around the brightest 64 px block (mean luminance), counts pixels with any channel above level in a 128 px box (every 2nd pixel) and a 32 px box (every pixel), both centred on that block and held inside the image. Returns JSON: fraction_above_wide, fraction_above_inner, peak (largest luminance in the wide box), core_center [x, y], wide_box, inner_box. luminance is 0.2126R + 0.7152G + 0.0722B.

Measure the texture of the bright subject zone. Subject pixels have luminance above median + 5 x (median |luminance - median| on a 32 px grid). The ROI is a circle around the luminance-weighted centroid of compact subject pixels (8 px grid, at least 2 of 4 neighbours 3 px away also subject), radius = their 90th-percentile distance held to [50 px, 0.45 x min(width, height)]. The shell zone is the P20..P92 band of the subject pixels in the ROI (every 4th pixel). local_stddev = median luminance stddev of 16 px blocks in the ROI whose samples are at least 40% shell; tonal_span = P90 - P10 of the shell pixels; gradient_energy = mean Sobel energy on shell pixels. With reference_id, the reference is measured over the same ROI and retention is current / reference for each value (null where the reference value is at most 0.0001, or 0.001 for tonal_span). Returns JSON: current, reference, retention, shell_zone, roi, shell_pixel_count, block_count. Fewer than 100 subject pixels in the ROI of either view is an error. luminance is 0.2126R + 0.7152G + 0.0722B.

Measure concentric oscillation around the brightest region. The centre is the middle of the brightest 64 px block (mean luminance); the radial luminance profile is averaged over 36 angles for radii 1..150 px (held inside the image). Along the profile, derivatives within ±0.001 carry no sign; at each sign change the summed |derivative| of the run it ends is its amplitude, and it is counted when that amplitude is above min_amplitude. Returns JSON: oscillations, max_amplitude (of the counted ones), center [x, y], profile_sample (the profile at radii 1..30). luminance is 0.2126R + 0.7152G + 0.0722B.

Measure HSV saturation, (max - min) / max, of subject pixels of a colour view: every 8th pixel whose luminance is above the luminance of the channel medians + 5 x (median |luminance - that| on a 32 px grid). Returns JSON: median, p90, p99, max, subject_pixel_count. A mono view is an error. luminance is 0.2126R + 0.7152G + 0.0722B.

Measure sharpness as the mean Sobel gradient energy (gx² + gy²) of luminance over every 4th pixel of a region. The region is roi_x/roi_y/roi_w/roi_h when all four are given (it must lie inside the image), else the central half of the image in each dimension. Returns JSON: sharpness, samples, roi {x, y, w, h}. luminance is 0.2126R + 0.7152G + 0.0722B.

Measure a star layer (a mostly black view holding stars). Over every 4th pixel whose largest channel is above 0.005 (nonzero_pixel_count), reports the fraction whose largest channel is above each of the given levels, the interquartile range of their HSV saturation (color_diversity), and the median (max - min) / max of the 20 brightest by R+G+B (bright_star_chroma). Also the largest channel value (max) and the image median (the mean of the channel medians for colour). Returns JSON: max, median, fraction_above {level: fraction}, color_diversity, bright_star_chroma, nonzero_pixel_count.

Measure the stars of a view by pixel sampling. Candidates are local maxima of luminance found by a 16 px grid scan above median + 5 x MAD, refined within 5x5, de-duplicated within 20 px (at most 100 kept); the 30 brightest are measured. FWHM of a star = 2 x the mean radius, over the four axis directions (up to 10 px), where luminance drops below half its peak, located to a fraction of a pixel by linear interpolation between the samples either side; colour diversity of a star = max - min of its peak RGB divided by the largest channel. Returns JSON: median_fwhm_px, color_diversity (median), stars_found, stars_measured, median_peak, p25_peak, background_median, star_background_contrast (median_peak / background_median, 0 when background_median <= 0.001), and up to 10 samples of each. luminance is 0.2126R + 0.7152G + 0.0722B.

Measure subject brightness, detail and contrast. The image is split into 32 px blocks; a block is subject when its luminance median is above median + 8 x 1.4826 x MAD. subject_brightness = median of subject block medians; background_median = median of the other block medians; contrast_ratio = subject_brightness / background_median (0 when that is at most 0.001); detail_score = mean Sobel energy of luminance over every 4th pixel of up to 50 subject blocks; subject_count = subject blocks; subject_threshold = median + 3 x 1.4826 x MAD. Returns JSON: subject_brightness, detail_score, contrast_ratio, subject_count, background_median, subject_threshold. luminance is 0.2126R + 0.7152G + 0.0722B.

Measure subject and background tones. Every 8th pixel is subject when its luminance is above the background (luminance of the channel medians) + 5 x (median |luminance - background| on a 32 px grid) and at least 2 of its 4 neighbours 3 px away are too; every other sample is background. separation = subject median / background median; core_brightness = mean of the brightest 5% of subject samples; core_to_disk = core_brightness / subject median; faint_structure_visibility = (subject P10 - background P90) / background P90; subject_fraction = subject samples / all samples; roi_mode is compound_roi when a second luminance-weighted cluster, outside 0.15 x width of the centroid and holding over 15% of the weight, lies more than 0.25 x width away, else single. Denominators are held to at least 0.001. Returns JSON: separation, subject_median, background_median, core_brightness, faint_structure_visibility, core_to_disk, subject_fraction, roi_mode, subject_pixel_count. luminance is 0.2126R + 0.7152G + 0.0722B.

Measure background uniformity via 4-corner median stddev. Lower score means more uniform.

Masked three-scale LocalHistogramEqualization on a view, in one call, with an optional HDRMultiscaleTransform pass. The mask is the image lightness (CIE L* for colour, the image itself for mono) mapped as max((L - mask_clip_low) / (1 - mask_clip_low), 0), raised to the power 1/mask_gamma and blurred with a Gaussian of sigma mask_blur (0 = no blur). LHE then runs at the large, mid and fine radius in that order through the mask; the large and mid scales use lhe_slope_limit, the fine scale lhe_fine_slope_limit; other LHE parameters are PixInsight's defaults. Giving hdrmt_layers adds an HDRMultiscaleTransform pass through the same mask. The mask is closed afterwards. Reports a detail score before and after: the mean squared Sobel gradient of luminance (Rec.709 weights) over pixels brighter than median + 8 x 1.4826 x MAD, sampled every 8 pixels.

Open an XISF/FITS image file in PixInsight. Returns the view ID assigned by PixInsight. Automatically closes any crop_mask windows that come with XISF files.