Files
spectrometer/spectro_core.py
T
starcells ccc7c62569 统一默认输出目录命名
- 命名规则移入 spectro_core.default_output_directory(root, stem, indices)

- wavelength_calibration 默认改为 calibration_exports/<recording>_f<frame>,与 peak_exports 一致;输入为 peaks.json 时镜像其所在目录名

- 新增 3 项命名测试
2026-11-14 14:54:27 +08:00

876 lines
36 KiB
Python

#!/usr/bin/env python3
"""Shared core for the spectro tools: loading, calibration, peak detection, output.
Extracted from peak_finder.py so that wavelength_calibration.py, wavelength_player.py
and hq_average.py can call the same code instead of keeping their own copies.
No command line and no matplotlib at import time; plotting helpers stay in the
scripts that need them. Everything here is pure NumPy.
"""
from __future__ import annotations
import csv
import importlib.util
import json
import math
import sys
from pathlib import Path
from typing import Optional
import numpy as np
CORE_DIR = Path(__file__).resolve().parent
GAUSS_TO_FWHM = 2.3548200450309493
def load_hq(module_dir: Optional[str] = None) -> object:
"""Import hq_spectrum.py from this folder (or ``module_dir``) by path."""
candidates = [Path(module_dir).expanduser()] if module_dir else [CORE_DIR, Path.cwd()]
for directory in candidates:
path = directory / "hq_spectrum.py"
if path.is_file():
spec = importlib.util.spec_from_file_location("hq_spectrum_shared", path)
module = importlib.util.module_from_spec(spec)
sys.modules[spec.name] = module
spec.loader.exec_module(module)
return module
try: # last resort: a normal import from sys.path
import hq_spectrum as module # type: ignore
except ImportError as exc:
raise RuntimeError("cannot find hq_spectrum.py; put it beside spectro_core.py "
"or use --module-dir") from exc
return module
def is_saturated(image: np.ndarray, roi, x_center: float, full_scale: float,
band: tuple[int, int] = (-2, 4), threshold: float = 0.01) -> bool:
"""True when a meaningful fraction of the pixels near ``x_center`` is clipped."""
x0 = max(0, min(int(x_center) + band[0], image.shape[1]))
x1 = max(0, min(int(x_center) + band[1], image.shape[1]))
block = image[roi.y0:roi.y1, x0:x1]
if block.size == 0:
return False
return float(np.mean(block >= 0.995 * full_scale)) > threshold
def _num(value, digits: int = 6) -> str:
"""Format a value for CSV output; non-finite values become empty cells."""
if value is None:
return ""
if isinstance(value, (bool, np.bool_)):
return "1" if value else "0"
if isinstance(value, str):
return value
try:
number = float(value)
except (TypeError, ValueError):
return str(value)
if not np.isfinite(number):
return ""
return f"{number:.{digits}g}"
def write_csv(path: Path, fields: list[str], rows) -> None:
with path.open("w", newline="", encoding="utf-8") as handle:
writer = csv.writer(handle)
writer.writerow(fields)
for row in rows:
writer.writerow(row)
def _jsonable(value):
"""Convert NumPy scalars/arrays and Paths into plain JSON values."""
if isinstance(value, dict):
return {str(k): _jsonable(v) for k, v in value.items()}
if isinstance(value, (list, tuple)):
return [_jsonable(v) for v in value]
if isinstance(value, np.ndarray):
return [_jsonable(v) for v in value.tolist()]
if isinstance(value, (np.floating, np.integer, np.bool_)):
return value.item()
if isinstance(value, Path):
return str(value)
return value
def write_json(path, value) -> None:
"""Write JSON with NumPy/Path values converted and a trailing newline."""
Path(path).write_text(json.dumps(_jsonable(value), indent=2) + "\n", encoding="utf-8")
class Calibration:
"""Polynomial sensor-pixel -> wavelength saved by wavelength_calibration.py."""
def __init__(self, path, offset_nm: float = 0.0):
self.path = Path(path).expanduser().resolve()
try:
self.data = json.loads(self.path.read_text(encoding="utf-8-sig"))
except OSError as exc:
raise ValueError(f"cannot read calibration {self.path}: {exc}") from exc
except json.JSONDecodeError as exc:
raise ValueError(f"calibration {self.path} is not valid JSON: {exc}") from exc
if not isinstance(self.data, dict):
raise ValueError("calibration JSON must contain an object")
coeff = np.asarray(self.data.get("coefficients_descending"), dtype=float)
if coeff.ndim != 1 or len(coeff) not in (2, 3):
raise ValueError("calibration needs 2 or 3 descending coefficients")
if not np.all(np.isfinite(coeff)) or coeff[0] == 0:
raise ValueError("calibration coefficients must be finite and the leading one nonzero")
if self.data.get("order", len(coeff) - 1) != len(coeff) - 1:
raise ValueError("calibration order does not match coefficient count")
self.coeff = coeff
span = np.asarray(self.data.get("calibrated_pixel_range"), dtype=float)
if span.shape != (2,) or not np.all(np.isfinite(span)) or span[0] >= span[1]:
raise ValueError("calibration has an invalid calibrated_pixel_range")
self.span = span
self.offset_nm = float(offset_nm)
if not np.isfinite(self.offset_nm):
raise ValueError("wavelength offset must be finite")
self.width: Optional[int] = None
self._grid_px = None
self._grid_nm = None
def __call__(self, x):
return np.polyval(self.coeff, np.asarray(x, dtype=float)) + self.offset_nm
def dispersion(self, x) -> np.ndarray:
"""Local nm per sensor pixel (never zero over a validated sensor)."""
return np.polyval(np.polyder(self.coeff), np.asarray(x, dtype=float))
def set_width(self, width: int) -> None:
self.width = int(width)
grid = np.arange(self.width, dtype=float)
values = np.asarray(self(grid), dtype=float)
order = np.argsort(values)
self._grid_px = grid[order]
self._grid_nm = values[order]
def inverse(self, wavelength):
"""Sensor pixel of a wavelength; used for the secondary plot axis only."""
if self._grid_nm is None:
raise ValueError("calibration width is unknown")
return np.interp(np.asarray(wavelength, dtype=float), self._grid_nm, self._grid_px)
@property
def nm_span(self) -> tuple[float, float]:
values = sorted(np.asarray(self(self.span), dtype=float).tolist())
return float(values[0]), float(values[1])
def describe(self) -> str:
low, high = self.nm_span
text = (f"JSON calibration ({self.data.get('wavelength_medium', 'air')}); "
f"confirmed {low:.2f}-{high:.2f} nm; outside = extrapolation")
if self.offset_nm:
text += f"; manual offset {self.offset_nm:+.3f} nm"
return text
def validate_geometry(self, source, tell=None) -> None:
"""Refuse a recording whose sensor geometry differs from the calibration."""
tell = tell or (lambda *args, **kwargs: None)
derivative = self.dispersion([0.0, float(source.full_size[0] - 1)])
if np.any(np.abs(derivative) < 1e-12) or derivative[0] * derivative[1] <= 0:
raise ValueError("calibration is not monotonic over this recording width")
reference = self.data.get("recording")
metadata = Path(reference) / "meta.json" if reference else None
if metadata is not None and metadata.is_file():
reference_meta = json.loads(metadata.read_text(encoding="utf-8-sig"))
size = (int(reference_meta["width"]), int(reference_meta["height"]))
if size != tuple(source.full_size):
raise ValueError("recording dimensions differ from the calibration recording; "
"recalibrate this sensor mode")
else:
tell("note : calibration reference recording unavailable; sensor size not checked")
if self.data.get("pattern") and self.data["pattern"] != source.pattern:
tell(f"note : calibration pattern {self.data['pattern']} differs from "
f"recording pattern {source.pattern}")
def _rank_filter(y: np.ndarray, width: int, reducer) -> np.ndarray:
"""Running min/max over the window [i - width, i + width] with edge padding."""
width = max(0, int(width))
values = np.asarray(y, dtype=float)
if width == 0 or values.size <= 1:
return values.copy()
n = values.size
padded = np.pad(values, (width, width), mode="edge")
out = padded[width:width + n].copy()
for shift in range(-width, width + 1):
start = width + shift
reducer(out, padded[start:start + n], out=out)
return out
def _min_filter(y: np.ndarray, width: int) -> np.ndarray:
return _rank_filter(y, width, np.minimum)
def _max_filter(y: np.ndarray, width: int) -> np.ndarray:
return _rank_filter(y, width, np.maximum)
def estimate_baseline(y: np.ndarray, window_samples: int, smooth) -> np.ndarray:
"""Morphological opening baseline; removes peaks narrower than the window."""
width = max(0, int(window_samples))
if width == 0 or np.size(y) <= 2:
return np.zeros_like(np.asarray(y, dtype=float))
opened = _max_filter(_min_filter(np.asarray(y, dtype=float), width), width)
return smooth(opened.astype(np.float32), max(1, width // 2)).astype(float)
def estimate_noise(net: np.ndarray) -> float:
"""Robust noise proxy from the median absolute first difference."""
if np.size(net) < 3:
return 0.0
diff = np.diff(np.asarray(net, dtype=float))
mad = float(np.median(np.abs(diff - np.median(diff))))
return mad / (0.6745 * math.sqrt(2.0))
def parabola_center(x: np.ndarray, y: np.ndarray, index: int) -> float:
"""Sub-sample vertex of the parabola through three samples (NaN if unusable)."""
if index <= 0 or index >= y.size - 1:
return float("nan")
y0, y1, y2 = float(y[index - 1]), float(y[index]), float(y[index + 1])
denominator = y0 - 2.0 * y1 + y2
if not np.isfinite(denominator) or denominator == 0.0:
return float("nan")
delta = 0.5 * (y0 - y2) / denominator
if not np.isfinite(delta) or abs(delta) > 1.0:
return float("nan")
step = float(x[index + 1] - x[index])
return float(x[index] + delta * step)
def half_max_crossings(x: np.ndarray, net: np.ndarray, index: int,
max_span: int) -> tuple[float, float]:
"""Linearly interpolated x positions where the net signal falls to half max."""
peak = float(net[index])
if not np.isfinite(peak) or peak <= 0.0:
return float("nan"), float("nan")
half = 0.5 * peak
span = max(1, int(max_span))
left = index
floor_index = max(0, index - span)
while left > floor_index and net[left] > half:
left -= 1
right = index
ceiling = min(net.size - 1, index + span)
while right < ceiling and net[right] > half:
right += 1
left_x = right_x = float("nan")
if left < index and net[left] <= half:
rise = float(net[left + 1] - net[left])
left_x = float(x[left] + (half - net[left]) / rise * (x[left + 1] - x[left])) \
if rise > 0 else float(x[left])
if right > index and net[right] <= half:
fall = float(net[right - 1] - net[right])
right_x = float(x[right] - (net[right] - half) / fall * (x[right] - x[right - 1])) \
if fall > 0 else float(x[right])
return left_x, right_x
def _core(x: np.ndarray, amplitude: float, center: float, width: float,
shape: str) -> np.ndarray:
offset = x - center
if shape == "lorentz":
return amplitude / (1.0 + (offset / width) ** 2)
return amplitude * np.exp(-0.5 * (offset / width) ** 2)
def _shape_model(x: np.ndarray, params: np.ndarray, xref: float, shape: str) -> np.ndarray:
amplitude, center, width, c0, c1 = params
return _core(x, amplitude, center, width, shape) + c0 + c1 * (x - xref)
def _multi_model(x: np.ndarray, params: np.ndarray, xref: float, shape: str,
peaks: int) -> np.ndarray:
"""1..N shape components plus a linear background; params = 3*N + 2."""
total = np.zeros_like(x, dtype=float)
for index in range(peaks):
amplitude, center, width = params[3 * index:3 * index + 3]
total = total + _core(x, amplitude, center, width, shape)
return total + params[3 * peaks] + params[3 * peaks + 1] * (x - xref)
def fit_profile(x: np.ndarray, y: np.ndarray, start: list[float], shape: str,
bounds: list[tuple[float, float]], max_iter: int = 200,
peaks: int = 1, shared_width: bool = False) -> dict:
"""Fit 1..N peak components + linear background; returns parameters and flags.
``shared_width`` fits one common line width for all components, which is the
physically sensible and numerically stable model for an unresolved doublet.
Parameter layout: per component ``A, mu(, sigma)`` then ``c0, c1``; with a
shared width the single ``sigma`` is appended before ``c0, c1``.
"""
x = np.asarray(x, dtype=float)
y = np.asarray(y, dtype=float)
peaks = int(peaks)
per_peak = 2 if shared_width else 3
background = per_peak * peaks
if x.size < background + 3 or not np.all(np.isfinite(y)):
return {"ok": False}
xref = float(np.mean(x))
lower = np.array([bound[0] for bound in bounds], dtype=float)
upper = np.array([bound[1] for bound in bounds], dtype=float)
params = np.clip(np.asarray(start, dtype=float), lower, upper)
def model(values, parameters):
shared = parameters[2 * peaks] if shared_width else None
total = np.zeros_like(values, dtype=float)
for index in range(peaks):
if shared_width:
amplitude, center = parameters[2 * index], parameters[2 * index + 1]
width = shared
else:
amplitude, center, width = parameters[3 * index:3 * index + 3]
total = total + _core(values, amplitude, center, width, shape)
return total + parameters[background] + parameters[background + 1] * (values - xref)
residual = y - model(x, params)
cost = float(np.sum(residual * residual))
if not np.isfinite(cost):
return {"ok": False}
lam = 1e-3
converged = False
for _ in range(max_iter):
base = model(x, params)
jacobian = np.empty((x.size, params.size))
for j in range(params.size):
step = 1e-6 * max(1.0, abs(params[j]))
probe = params.copy()
probe[j] += step
jacobian[:, j] = (model(x, probe) - base) / step
normal = jacobian.T @ jacobian
gradient = jacobian.T @ residual
diagonal = np.diag(np.diag(normal)) + 1e-12 * np.eye(params.size)
relative = 1.0
stepped = False
for _ in range(40):
try:
delta = np.linalg.solve(normal + lam * diagonal, gradient)
except np.linalg.LinAlgError:
lam *= 10.0
continue
trial = np.clip(params + delta, lower, upper)
trial_residual = y - model(x, trial)
trial_cost = float(np.sum(trial_residual * trial_residual))
if np.isfinite(trial_cost) and trial_cost < cost:
relative = (cost - trial_cost) / max(cost, 1e-30)
params, residual, cost = trial, trial_residual, trial_cost
lam = max(lam / 3.0, 1e-15)
stepped = True
break
lam *= 10.0
if not stepped or relative < 1e-12:
converged = True
break
rms = float(np.sqrt(cost / max(1, x.size)))
# Parameter errors from the normal matrix at the final parameters; scale the
# columns first because amplitude, centre and width differ by orders of magnitude.
try:
base = model(x, params)
jacobian = np.empty((x.size, params.size))
for j in range(params.size):
step = 1e-6 * max(1.0, abs(params[j]))
probe = params.copy()
probe[j] += step
jacobian[:, j] = (model(x, probe) - base) / step
normal = jacobian.T @ jacobian
scale = np.sqrt(np.maximum(np.diag(normal), 1e-300))
correlation = normal / np.outer(scale, scale)
try:
inverse = np.linalg.inv(correlation)
except np.linalg.LinAlgError:
inverse = np.linalg.pinv(correlation)
variance = cost / max(1, x.size - params.size)
errors = np.sqrt(np.clip(np.diag(inverse) * variance, 0.0, None)) / scale
except (np.linalg.LinAlgError, ValueError, FloatingPointError):
errors = np.full(params.size, float("nan"))
components = []
usable = bool(converged and np.isfinite(params).all())
for index in range(peaks):
if shared_width:
amplitude = float(params[2 * index])
center = float(params[2 * index + 1])
width = float(params[2 * peaks])
low, high = lower[2 * peaks], upper[2 * peaks]
amplitude_err = float(errors[2 * index])
center_err = float(errors[2 * index + 1])
width_err = float(errors[2 * peaks])
else:
amplitude = float(params[3 * index])
center = float(params[3 * index + 1])
width = float(params[3 * index + 2])
low, high = lower[3 * index + 2], upper[3 * index + 2]
amplitude_err = float(errors[3 * index])
center_err = float(errors[3 * index + 1])
width_err = float(errors[3 * index + 2])
width_at_bound = bool(width <= low * (1 + 1e-6) or width >= high * (1 - 1e-6))
if amplitude <= 0 or width <= 0 or width_at_bound:
usable = False
if not x[0] - 1.0 <= center <= x[-1] + 1.0:
usable = False
fwhm = 2.0 * width if shape == "lorentz" else GAUSS_TO_FWHM * width
components.append({"amplitude": amplitude, "center": center,
"width": width, "fwhm": float(fwhm),
"amplitude_err": amplitude_err, "center_err": center_err,
"width_err": width_err,
"width_at_bound": width_at_bound})
first = components[0]
return {
"ok": usable,
"peaks": peaks,
"params": params.tolist(),
"xref": xref,
"components": components,
"center": first["center"],
"width": first["width"],
"amplitude": first["amplitude"],
"fwhm": first["fwhm"],
"c0": float(params[background]),
"c1": float(params[background + 1]),
"rms": rms,
"converged": converged,
"at_bound": any(item["width_at_bound"] for item in components),
"n_points": int(x.size),
}
def model_values(x, params, xref: float, shape: str) -> np.ndarray:
if not params:
return np.full(np.shape(x), np.nan, dtype=float)
return _shape_model(np.asarray(x, dtype=float), np.asarray(params, dtype=float), xref, shape)
def peak_prominence(net: np.ndarray, index: int) -> tuple[float, float]:
"""True topographic prominence of a local maximum and the level it sits on.
Walk outwards until the profile rises above the peak or the array ends; the
prominence base is the higher of the two minima on the way. Unlike a fixed
window this keeps resolved doublets apart and rejects shoulders.
"""
height = float(net[index])
left = index
left_min = height
while left > 0:
left -= 1
value = float(net[left])
if value > height:
break
if value < left_min:
left_min = value
right = index
right_min = height
while right < net.size - 1:
right += 1
value = float(net[right])
if value > height:
break
if value < right_min:
right_min = value
base = max(left_min, right_min)
return height - base, base
def find_peak_candidates(net: np.ndarray, min_distance: int, min_height: float,
min_prominence: float, max_peaks: int) -> list[dict]:
"""Local maxima with plateau centring, true prominence and neighbour suppression."""
n = net.size
if n < 3 or max_peaks <= 0:
return []
candidates = []
index = 1
while index < n - 1:
if net[index] > net[index - 1]:
end = index
while end + 1 < n and net[end + 1] == net[index]:
end += 1
if end + 1 < n and net[end] > net[end + 1]:
candidates.append((index + end) // 2)
index = end + 1
else:
index += 1
if not candidates:
return []
candidates.sort(key=lambda i: float(net[i]), reverse=True)
kept: list[dict] = []
for index in candidates:
height = float(net[index])
if height < min_height:
continue
if any(abs(index - other["sample"]) < max(1, int(min_distance)) for other in kept):
continue
prominence, base = peak_prominence(net, index)
if prominence < min_prominence:
continue
kept.append({"sample": int(index), "height_adu": height,
"base_adu": base, "prominence_adu": float(prominence)})
if len(kept) >= max_peaks:
break
return kept
def refine_peak(x: np.ndarray, net: np.ndarray, raw: np.ndarray, candidate: dict,
noise: float, step_px: float, fwhm_span: int, fit_window: int,
shape: str, saturated: bool, baseline_value: float = 0.0) -> dict:
"""Measure one detected peak: centre, width, height, area and fit quality."""
index = candidate["sample"]
n = net.size
left_x, right_x = half_max_crossings(x, net, index, fwhm_span)
fwhm_measured = (right_x - left_x
if np.isfinite(left_x) and np.isfinite(right_x) else float("nan"))
if fit_window > 0:
window_px = float(fit_window) * step_px
elif np.isfinite(fwhm_measured):
window_px = float(np.clip(2.0 * fwhm_measured, 8.0 * step_px, 90.0 * step_px))
else:
window_px = 15.0 * step_px
lower = int(index)
while lower > 0 and x[index] - x[lower] < window_px:
lower -= 1
upper = int(index)
while upper < n - 1 and x[upper] - x[index] < window_px:
upper += 1
center_parabola = parabola_center(x, net, index)
start_center = center_parabola if np.isfinite(center_parabola) else float(x[index])
start_width = fwhm_measured / (2.0 if shape == "lorentz" else GAUSS_TO_FWHM)
if not np.isfinite(start_width) or start_width <= 0:
start_width = 2.0 * step_px
span_px = float(x[upper] - x[lower])
bounds = [
(0.0, 10.0 * candidate["height_adu"] + 1.0),
(x[lower] - span_px, x[upper] + span_px),
(0.4 * step_px, max(4.0 * start_width, 0.5 * span_px)),
(-5.0 * candidate["height_adu"] - 1.0, 5.0 * candidate["height_adu"] + 1.0),
(-1e4, 1e4),
]
fit = fit_profile(x[lower:upper + 1], net[lower:upper + 1],
[candidate["height_adu"], start_center, start_width, 0.0, 0.0],
shape, bounds)
if fit.get("ok") and (fit["amplitude"] < 0.25 * candidate["height_adu"]
or fit["rms"] > 0.2 * fit["amplitude"]):
# Reject a fit that misses the measured peak: keep the robust estimators.
fit["ok"] = False
if fit.get("ok"):
center, fwhm, source = fit["center"], fit["fwhm"], "fit"
elif np.isfinite(center_parabola):
# Model-free vertex of the measured maximum: still a peak position.
center, fwhm, source = center_parabola, fwhm_measured, "apex"
else:
# Flat or saturated top makes the parabola unusable; report the sample
# where the maximum was detected rather than a window-dependent moment.
center, fwhm, source = float(x[index]), fwhm_measured, "sample"
height = float(net[index])
if fit.get("ok") and fit["amplitude"] > height:
height = float(fit["amplitude"])
return {
"sample_index": int(index),
"sensor_x_px": float(x[index]),
"center_px": float(center),
"center_source": source,
"center_parabola_px": float(center_parabola) if np.isfinite(center_parabola) else float("nan"),
"center_fit_px": float(fit["center"]) if fit.get("ok") else float("nan"),
"center_err_px": float(fit["components"][0]["center_err"]) if fit.get("ok") else float("nan"),
"sigma_px": float(fit["width"]) if fit.get("ok") else float("nan"),
"fwhm_px": float(fwhm) if np.isfinite(fwhm) else float("nan"),
"fwhm_halfmax_px": float(fwhm_measured) if np.isfinite(fwhm_measured) else float("nan"),
"height_net_adu": height,
"prominence_adu": float(candidate["prominence_adu"]),
"raw_adu": float(raw[index]),
"baseline_adu": float(baseline_value),
"snr": float(height / noise) if noise > 0 else float("inf"),
"area_net_adu_px": float(np.sum(np.maximum(net[lower:upper + 1], 0.0)) * step_px),
"saturated": bool(saturated),
"fit_ok": bool(fit.get("ok")),
"fit_rms_adu": float(fit["rms"]) if fit.get("ok") else float("nan"),
"fit_shape": shape,
"fit_params": fit.get("params") if fit.get("ok") else None,
"fit_xref": fit.get("xref") if fit.get("ok") else None,
"deblended": False,
"window_lo_px": float(x[lower]),
"window_hi_px": float(x[upper]),
"window_lo_sample": int(lower),
"window_hi_sample": int(upper),
}
def _fit_pair(x: np.ndarray, net: np.ndarray, first: dict, second: dict,
shape: str, step_px: float, noise: float) -> Optional[list[dict]]:
"""Joint two-component fit of a blended pair; None if it is not trustworthy."""
lower = min(first["window_lo_sample"], second["window_lo_sample"])
upper = max(first["window_hi_sample"], second["window_hi_sample"])
xx = x[lower:upper + 1]
yy = net[lower:upper + 1]
if xx.size < 11:
return None
starts: list[float] = []
bounds: list[tuple[float, float]] = []
separation = abs(float(second["sensor_x_px"]) - float(first["sensor_x_px"]))
widths = []
for peak in (first, second):
height = max(float(peak["height_net_adu"]), 1.0)
# Start from the detected maximum, not from the biased single-peak fit.
center = float(peak["sensor_x_px"])
width = float(peak["sigma_px"]) if np.isfinite(peak["sigma_px"]) and peak["sigma_px"] > 0 \
else 2.0 * step_px
widths.append(width)
starts.extend([height, center])
bounds.extend([(0.0, 10.0 * height + 1.0),
(center - 3.5 * step_px, center + 3.5 * step_px)])
# One shared line width: two components of the same blend come from the same
# instrument, and independent widths make the fit ill-conditioned.
shared = max(0.4 * step_px, min(max(widths), 0.5 * max(separation, step_px)))
starts.append(shared)
bounds.append((0.4 * step_px, max(8.0 * max(widths), 4.0 * step_px)))
scale = max(float(first["height_net_adu"]), float(second["height_net_adu"]), 1.0)
starts.extend([0.0, 0.0])
bounds.extend([(-3.0 * scale, 3.0 * scale), (-1e4, 1e4)])
fit = fit_profile(xx, yy, starts, shape, bounds, peaks=2, shared_width=True)
if not fit.get("ok"):
return None
components = fit["components"]
if components[1]["center"] - components[0]["center"] < 0.5 * step_px:
# The two components collapsed onto each other: this is one feature.
return None
if abs(components[0]["center"] - first["sensor_x_px"]) > 3.5 * step_px:
return None
if abs(components[1]["center"] - second["sensor_x_px"]) > 3.5 * step_px:
return None
updated = []
for peak, component in zip((first, second), components):
merged = dict(peak)
merged.update({
"center_px": float(component["center"]),
"center_fit_px": float(component["center"]),
"center_err_px": float(component["center_err"]),
"center_source": "pair",
"sigma_px": float(component["width"]),
"fwhm_px": float(component["fwhm"]),
"height_net_adu": float(component["amplitude"]),
"snr": float(component["amplitude"] / noise) if noise > 0 else float("inf"),
"fit_ok": True,
"fit_rms_adu": float(fit["rms"]),
"fit_params": [component["amplitude"], component["center"],
component["width"], 0.0, 0.0],
"fit_xref": float(fit["xref"]),
"deblended": True,
})
updated.append(merged)
return updated
def deblend_close_peaks(x: np.ndarray, net: np.ndarray, peaks: list[dict], shape: str,
step_px: float, noise: float, blend_factor: float = 1.2) -> list[dict]:
"""Refit unresolved pairs jointly instead of pulling their centres together."""
ordered = sorted(peaks, key=lambda item: item["sensor_x_px"])
result: list[dict] = []
index = 0
while index < len(ordered):
current = ordered[index]
if index + 1 < len(ordered):
neighbour = ordered[index + 1]
width_a = current["fwhm_px"] if np.isfinite(current["fwhm_px"]) else 4.0 * step_px
width_b = neighbour["fwhm_px"] if np.isfinite(neighbour["fwhm_px"]) else 4.0 * step_px
# Use the detected maxima: the fitted centres of a blend can cross.
separation = float(neighbour["sensor_x_px"] - current["sensor_x_px"])
if 0.0 < separation <= blend_factor * 0.5 * (width_a + width_b):
pair = _fit_pair(x, net, current, neighbour, shape, step_px, noise)
if pair is not None:
result.extend(pair)
index += 2
continue
result.append(current)
index += 1
return result
def dedupe_channel_peaks(peaks: list[dict], min_distance_px: float) -> list[dict]:
"""Drop repeated maxima closer than the peak distance, using detection positions.
The fitted centre of a blended line is pulled towards its neighbour, so the
distance is measured between the raw local maxima (``sensor_x_px``) and not
between the refined centres; otherwise a resolved doublet can collapse.
"""
kept: list[dict] = []
for peak in sorted(peaks, key=lambda item: item["height_net_adu"], reverse=True):
if any(abs(peak["sensor_x_px"] - other["sensor_x_px"]) < min_distance_px
for other in kept):
continue
kept.append(peak)
kept.sort(key=lambda item: item["sensor_x_px"])
return kept
def summarise_line(members: dict[str, dict]) -> dict:
"""Combine the per-channel peaks of one line into a line record (no id)."""
for channel, item in members.items():
item["channel"] = channel
items = list(members.values())
strongest = max((item["height_net_adu"] for item in items), default=0.0)
weights = np.array([
max(0.0, item["height_net_adu"]) if item["height_net_adu"] >= 0.25 * strongest else 0.0
for item in items
], dtype=float)
positions = np.array([item["center_px"] for item in items], dtype=float)
center = (float(np.dot(weights, positions) / weights.sum())
if weights.sum() > 0 else float(np.mean(positions)))
primary = max(items, key=lambda item: item["snr"])
return {
"sensor_x_px": center,
"center_spread_px": float(positions.max() - positions.min()),
"channels": members,
"channel_names": "".join(c for c in ("R", "G", "B") if c in members),
"n_channels": len(members),
"primary_channel": primary["channel"],
"height_net_adu": primary["height_net_adu"],
"max_height_net_adu": float(strongest),
"snr": primary["snr"],
"fwhm_px": primary["fwhm_px"],
"area_net_adu_px": primary["area_net_adu_px"],
"saturated": any(item["saturated"] for item in items),
"sample_index": primary["sample_index"],
"sample_step_px": None,
}
def merge_coincident_lines(lines: list[dict], tolerance_px: float = 1.5) -> list[dict]:
"""Join lines that ended up at the same place in complementary channels.
Weak lines can be detected a few pixels apart in different CFA channels; if
the refined centres agree to better than one sample they are one line.
"""
merged: list[dict] = []
for line in sorted(lines, key=lambda item: item["sensor_x_px"]):
target = None
for other in merged:
if abs(line["sensor_x_px"] - other["sensor_x_px"]) < tolerance_px:
target = other
break
if target is None:
merged.append({"sensor_x_px": line["sensor_x_px"],
"channels": dict(line["channels"])})
continue
combined = dict(target["channels"])
for channel, peak in line["channels"].items():
other = combined.get(channel)
if other is None or peak["snr"] > other["snr"]:
combined[channel] = peak
target["channels"] = combined
summaries = [summarise_line(item["channels"]) for item in merged]
summaries.sort(key=lambda entry: entry["sensor_x_px"])
for index, summary in enumerate(summaries, 1):
summary["id"] = f"P{index:03d}"
return summaries
def group_channels(peaks: dict[str, list[dict]], tolerance_px: float,
merge_tolerance_px: float = 1.5) -> list[dict]:
"""Merge per-channel peaks that belong to the same spectral line."""
# Cluster on the detected local maxima, not on the fitted centres: a single
# peak fit inside a blend is pulled towards its neighbour and would wrongly
# merge two resolved lines.
flat = [(item["sensor_x_px"], channel, item)
for channel, items in peaks.items() for item in items]
flat.sort(key=lambda row: row[0])
groups: list[list[tuple[float, str, dict]]] = []
for entry in flat:
if groups and entry[0] - groups[-1][-1][0] <= tolerance_px:
groups[-1].append(entry)
else:
groups.append([entry])
lines = []
for group in groups:
members: dict[str, dict] = {}
for _, channel, item in group:
other = members.get(channel)
# One line cannot have two centres in the same CFA channel.
if other is None or item["snr"] > other["snr"]:
members[channel] = item
summary = summarise_line(dict(members))
summary["id"] = ""
lines.append(summary)
return merge_coincident_lines(lines, merge_tolerance_px)
def attach_wavelength(lines: list[dict], calibration: Optional[Calibration]) -> None:
"""Add wavelength, extrapolation flag and per-channel wavelength data."""
for line in lines:
for item in line["channels"].values():
if calibration is not None:
item["wavelength_nm"] = float(calibration(item["center_px"]))
item["extrapolated"] = bool(
item["center_px"] < calibration.span[0] or item["center_px"] > calibration.span[1])
item["dispersion_nm_per_px"] = float(calibration.dispersion(item["center_px"]))
item["fwhm_nm"] = float(abs(item["fwhm_px"] * item["dispersion_nm_per_px"]))
else:
item["wavelength_nm"] = float("nan")
item["extrapolated"] = False
item["dispersion_nm_per_px"] = float("nan")
item["fwhm_nm"] = float("nan")
if calibration is not None:
line["wavelength_nm"] = float(calibration(line["sensor_x_px"]))
line["extrapolated"] = bool(
line["sensor_x_px"] < calibration.span[0] or line["sensor_x_px"] > calibration.span[1])
line["dispersion_nm_per_px"] = float(calibration.dispersion(line["sensor_x_px"]))
line["fwhm_nm"] = float(abs(line["fwhm_px"] * line["dispersion_nm_per_px"]))
else:
line["wavelength_nm"] = float("nan")
line["extrapolated"] = False
line["dispersion_nm_per_px"] = float("nan")
line["fwhm_nm"] = float("nan")
line.update({"match_species": "", "match_nm": float("nan"),
"match_delta_nm": float("nan"), "match_label": ""})
line["x_plot"] = line["wavelength_nm"] if calibration is not None else line["sensor_x_px"]
def default_output_directory(root: str, stem: str, indices) -> Path:
"""Folders that name the analysed frame(s), shared by every tool.
`<root>/<stem>_f0007` for one frame and `<root>/<stem>_f0005-0007_avg3`
for an averaged stack, so exports of different frames never overwrite each
other.
"""
indices = list(indices)
if not indices:
raise ValueError("at least one frame index is required")
if len(indices) > 1:
return Path(root) / f"{stem}_f{indices[0]:04d}-{indices[-1]:04d}_avg{len(indices)}"
return Path(root) / f"{stem}_f{indices[0]:04d}"