@@ -116,6 +116,8 @@ binning → intensity transform → gamma → normalization.
## Reproducible headless example
+
+
This example generates its own deterministic synthetic ring image. It is not
an experimental result or a performance benchmark.
diff --git a/assets/readme/hero-generation.json b/assets/readme/hero-generation.json
new file mode 100644
index 0000000..83fbf03
--- /dev/null
+++ b/assets/readme/hero-generation.json
@@ -0,0 +1,12 @@
+{
+ "name": "RingSentry",
+ "subtitle": "Reproducible diffraction-image preprocessing",
+ "palette": "Deep midnight navy, luminous cyan, restrained warm amber",
+ "motif": "A precise flat detector plane with concentric powder-diffraction rings, a delicately visible pixel matrix, and a second refined detector plane linked by a simple short processing path. Keep rings circular on the plane; this is a conceptual motif, no measurements.",
+ "tool": "image_gen built-in; model identifier not exposed",
+ "revision": null,
+ "prompt": "Create one exceptionally polished scientific software README cover banner, wide landscape approximately 2.4:1 aspect ratio, premium editorial art direction, high resolution. Project: RingSentry. Palette: Deep midnight navy, luminous cyan, restrained warm amber. Concept: A precise flat detector plane with concentric powder-diffraction rings, a delicately visible pixel matrix, and a second refined detector plane linked by a simple short processing path. Keep rings circular on the plane; this is a conceptual motif, no measurements. Compose generous negative space and sharply legible refined sans-serif typography integrated with the scientific motif. Exact text, no other copy: \"RingSentry\" large, \"Reproducible diffraction-image preprocessing\" smaller, and a discreet \"Conceptual illustration\". Make name/subtitle read immediately at GitHub width. Restrained three-dimensional material, carefully controlled highlights, precise linework, sophisticated hierarchy and balanced composition. No generic AI neon clouds, no random particles, no badges, no claims, no photoreal experimental data, no fake application screenshot, no watermarks or publisher branding. This is an editorial cover, not a quantitative paper figure.",
+ "created_on": "2026-09-27",
+ "purpose": "README conceptual cover only, not experimental data or software output",
+ "sha256": "e44ca17190194571e85abe4dfa48d096ad2ca2dbed02abed8e5d22b67c7defa9"
+}
diff --git a/assets/readme/hero.png b/assets/readme/hero.png
new file mode 100644
index 0000000..de76a61
Binary files /dev/null and b/assets/readme/hero.png differ
diff --git a/assets/readme/section-01-safety.svg b/assets/readme/section-01-safety.svg
index ce0f4af..1ad6c59 100644
--- a/assets/readme/section-01-safety.svg
+++ b/assets/readme/section-01-safety.svg
@@ -1,9 +1,7 @@
-
- Avoid silent damage before analysis
- Section 01: SAFETY
- 01 · SAFETY
- Avoid silent damage before analysis
- 01
-
+
+01 · SAFETY Avoid silent damage before analysis
+01 · SAFETY
+Avoid silent damage before analysis
+01
diff --git a/assets/readme/section-02-workflow.svg b/assets/readme/section-02-workflow.svg
index bda5ce3..31d0e91 100644
--- a/assets/readme/section-02-workflow.svg
+++ b/assets/readme/section-02-workflow.svg
@@ -1,9 +1,7 @@
-
- Preview · preflight · batch · report
- Section 02: WORKFLOW
- 02 · WORKFLOW
- Preview · preflight · batch · report
- 02
-
+
+02 · WORKFLOW Preview · preflight · batch · report
+02 · WORKFLOW
+Preview · preflight · batch · report
+02
diff --git a/docs/joss/submission-record.json b/docs/joss/submission-record.json
index ca51b57..f304632 100644
--- a/docs/joss/submission-record.json
+++ b/docs/joss/submission-record.json
@@ -45,7 +45,8 @@
},
"ai_assistance": {
"current_round": "OpenAI Codex, GPT-6, 2026-09-27: repository audit, packaging, tests, documentation, manuscript and bibliography preparation, validation and Git integration.",
- "historical_disclosure": "Retain project-specific disclosures; AbsSAXS AI history is not copied to these projects."
+ "historical_disclosure": "Retain project-specific disclosures; AbsSAXS AI history is not copied to these projects.",
+ "visual_revision": "2026-09-27: Codex revised reproducible manuscript figure scripts, captured real application widgets and prepared conceptual README covers using the built-in image-generation tool (model identifier not exposed). Prompt and image provenance are retained in the repository. Final author review remains pending."
},
"submission_date": null,
"related_publications": [
diff --git a/docs/joss/visual-provenance.md b/docs/joss/visual-provenance.md
new file mode 100644
index 0000000..121eb7e
--- /dev/null
+++ b/docs/joss/visual-provenance.md
@@ -0,0 +1,16 @@
+# Visual sources and reproduction
+
+The September 2026 visual revision separates editorial illustrations from research-software evidence.
+
+- `assets/readme/hero.png` is an AI-generated **conceptual illustration** for the README. It is not detector data, a calculated result, or an application screenshot. The prompt, tool description and file hash are in `hero-generation.json` beside it. The built-in image tool did not expose a model identifier; no specific model-version claim is made.
+- The editable section headers use repository-owned SVG. The previous SVG cover remains as an alternative source asset.
+- Manuscript diagrams and numerical plots are generated by the repository scripts below, with SVG and PDF vector exports and 450 dpi PNGs. Scientific arrays, reflection positions, and solver observations are not modified by an image-generation model.
+- Numerical demonstrations use only the bundled synthetic fixtures and actual software calculations. AnisoScope's interface figure, where applicable, is captured from real Qt widgets; the capture JSON records its inputs and hash.
+
+From the repository root, with the project's dependencies and Matplotlib installed:
+
+```bash
+python paper/figures/make_figures.py
+```
+
+Inspect the generated images and recompile `paper/paper.md` using the official draft-PDF workflow after any figure change. The README cover is not included as a scientific manuscript figure. Synthetic verification is not independent reproduction of the Acta Materialia experimental study.
diff --git a/paper/figures/architecture_workflow.pdf b/paper/figures/architecture_workflow.pdf
index 7a9dd9a..ee3dbf4 100644
Binary files a/paper/figures/architecture_workflow.pdf and b/paper/figures/architecture_workflow.pdf differ
diff --git a/paper/figures/architecture_workflow.png b/paper/figures/architecture_workflow.png
index 767db29..be34983 100644
Binary files a/paper/figures/architecture_workflow.png and b/paper/figures/architecture_workflow.png differ
diff --git a/paper/figures/architecture_workflow.svg b/paper/figures/architecture_workflow.svg
index 9dcbec4..d95afc3 100644
--- a/paper/figures/architecture_workflow.svg
+++ b/paper/figures/architecture_workflow.svg
@@ -1,7 +1,7 @@
-
+
@@ -9,7 +9,7 @@
image/svg+xml
- RingSentry paper/figures/make_figures.py
+ Matplotlib v3.10.8, https://matplotlib.org/
@@ -20,265 +20,340 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
- RingSentry architecture and auditable processing workflow
+ a
- Main batch path (GUI-orchestrated; per-file core data path)
+ Batch workflow
- 1 Entry / GUI
+ 01 Configure
- main.py → App
- explicit
- parameters
+ GUI settings
- 2 Discover / load
+ 02 Load
- core.loader
- files → 2D arrays
+ Detector arrays
- 3 QC / preflight
+ 03 Inspect
- core.quality
- read-only QC / plan
+ Read-only QC
- 4 Processing
+ 04 Process
- core.worker
- → apply_processing
+ Ordered steps
- 5 Write / report
+ 05 Export
- core.writer
- + gui.app report
+ Data + reports
- apply_processing: fixed, explicit operation order
+ b
- 1 Dark subtraction → 2 Flat correction → 3 Background offset → 4 Validate clipping parameters
+ Fixed numerical operation order
- 5 ROI → 6 Mask → 7 Absolute clipping → 8 Percentile clipping
+ 01
- 9 Negative clipping → 10 Hot-pixel suppression → 11 Rotate / flip → 12 Block-mean binning
+ Dark subtraction
- 13 Intensity transform → 14 Gamma → 15 Normalization
+ 02
- Independent tools (separate GUI tabs and core modules; not batch stages)
+ Flat correction
- Independent: CBF zero-value repair
+ 03
- core.overexposure_repair
+ Background offset
- Scan → target mask → write / read-back
- → verify → CSV / configuration / QC reports
+ 04
- Configured zeros only; cannot recover
- true saturated intensity.
+ Validate clipping
- Independent: Q geometry calculator
+ 05
- core.diffraction_model
+ Region of interest
- User λ / distance / pixel size /
- beam center → ideal-planar Q / 2θ / r / d
- + detector view / export
+ 06
- No image calibration, integration, peak fitting,
- or refinement.
+ Mask
- Scope: inspectable preprocessing, quality control, geometry conversion, and export of 2D detector images.
+ 07
+
+
+ Absolute clipping
+
+
+ 08
+
+
+ Percentile clipping
+
+
+ 09
+
+
+ Negative clipping
+
+
+ 10
+
+
+ Hot-pixel suppression
+
+
+ 11
+
+
+ Rotate / flip
+
+
+ 12
+
+
+ Block-mean binning
+
+
+ 13
+
+
+ Intensity transform
+
+
+ 14
+
+
+ Gamma
+
+
+ 15
+
+
+ Normalization
+
+
+ c
+
+
+ Independent tools
+
+
+ CBF zero-value repair
+
+
+ Target mask → write → verify
+ Configured zeros; not saturation recovery
+
+
+ Ideal planar geometry
+
+
+ Wavelength + detector geometry
+ Q, 2θ, radius and d-spacing conversion
+
+
+ Preprocessing and QC precede downstream integration or fitting.
-
-
+
diff --git a/paper/figures/make_figures.py b/paper/figures/make_figures.py
index cedd2ab..149880b 100644
--- a/paper/figures/make_figures.py
+++ b/paper/figures/make_figures.py
@@ -1,429 +1,229 @@
-"""Generate the two repository-owned figures used by the JOSS manuscript.
-
-The script uses only RingSentry source code and a deterministic synthetic
-array. It does not load experimental data or report performance results.
-"""
-
-from __future__ import annotations
+"""Reproducible publication graphics; no experimental measurements are synthesized."""
import argparse
-import sys
+import numpy as np
from pathlib import Path
-from typing import Dict, Iterable, Optional, Sequence, Tuple
-
+import sys
import matplotlib
-matplotlib.use("Agg", force=True)
-
+matplotlib.use("Agg")
import matplotlib.pyplot as plt
-from matplotlib.patches import FancyArrowPatch, FancyBboxPatch
-import numpy as np
-
-
-REPOSITORY_ROOT = Path(__file__).resolve().parents[2]
-if str(REPOSITORY_ROOT) not in sys.path:
- sys.path.insert(0, str(REPOSITORY_ROOT))
-
-from core.processing import apply_processing
-from core.quality import analyze_image_quality
-from examples.minimal_preprocessing import (
- PROCESSING_OPTIONS,
- SYNTHETIC_SEED,
- generate_synthetic_detector_image,
-)
-
-
-FIGURE_STEMS = ("architecture_workflow", "synthetic_processing")
-SUPPORTED_FORMATS = ("svg", "png", "pdf")
+from matplotlib.patches import FancyBboxPatch, FancyArrowPatch
-COLORS = {
- "blue": "#0072B2",
- "sky": "#56B4E9",
- "green": "#009E73",
- "orange": "#E69F00",
- "vermillion": "#D55E00",
- "ink": "#202124",
- "gray": "#666666",
- "light_blue": "#E8F3F8",
- "light_green": "#E8F5F0",
- "light_orange": "#FFF3DC",
- "light_gray": "#F5F5F5",
- "white": "#FFFFFF",
-}
+INK = "#142C3D"
+MUTED = "#516570"
+RULE = "#CCD7DC"
+ACCENT = "#087F8C"
+LIGHT = "#EFF7F8"
+WARM = "#B86B20"
-def configure_style() -> None:
- """Apply one accessible publication style to both figures."""
+def style():
matplotlib.rcParams.update(
{
"font.family": "sans-serif",
- "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans"],
- # The manuscript scales these 180 mm figures down slightly. Keep
- # the source text at or above 8 pt so the final PDF remains legible.
- "font.size": 8.4,
- "axes.titlesize": 8.8,
- "axes.labelsize": 8.4,
- "xtick.labelsize": 8.4,
- "ytick.labelsize": 8.4,
- "legend.fontsize": 8.4,
- "figure.titlesize": 9.6,
- "axes.linewidth": 0.6,
- "lines.linewidth": 1.0,
- "savefig.dpi": 600,
+ "font.sans-serif": ["Arial", "DejaVu Sans"],
+ "font.size": 10,
+ "axes.labelsize": 10,
+ "axes.titlesize": 11,
+ "xtick.labelsize": 9,
+ "ytick.labelsize": 9,
+ "text.color": INK,
+ "axes.labelcolor": INK,
+ "axes.edgecolor": RULE,
+ "axes.linewidth": 0.7,
+ "lines.linewidth": 1.5,
"svg.fonttype": "none",
- "svg.hashsalt": "ringsentry-joss-figures",
+ "svg.hashsalt": "publication-20260927",
"pdf.fonttype": 42,
- "ps.fonttype": 42,
+ "savefig.facecolor": "white",
}
)
-def _add_stage_box(
- ax,
- x: float,
- y: float,
- width: float,
- height: float,
- number: str,
- title: str,
- body: str,
- facecolor: str,
- edgecolor: str,
-) -> None:
- patch = FancyBboxPatch(
- (x, y),
- width,
- height,
- boxstyle="round,pad=0.008,rounding_size=0.012",
- facecolor=facecolor,
- edgecolor=edgecolor,
- linewidth=0.8,
- )
- ax.add_patch(patch)
- ax.text(
- x + 0.012,
- y + height - 0.020,
- f"{number} {title}",
- ha="left",
- va="top",
- fontsize=8.6,
- fontweight="bold",
- color=COLORS["ink"],
- )
- ax.text(
- x + width / 2.0,
- y + height - 0.063,
- body,
- ha="center",
- va="top",
- fontsize=8.4,
- linespacing=1.25,
- color=COLORS["ink"],
- )
+def canvas(height=4.6):
+ fig = plt.figure(figsize=(7.2, height), facecolor="white")
+ ax = fig.add_axes([0, 0, 1, 1], xlim=(0, 1), ylim=(0, 1))
+ ax.axis("off")
+ return fig, ax
-def _add_arrow(ax, start: Tuple[float, float], end: Tuple[float, float]) -> None:
- arrow = FancyArrowPatch(
- start,
- end,
- arrowstyle="-|>",
- mutation_scale=8,
- linewidth=0.8,
- color=COLORS["ink"],
- shrinkA=2,
- shrinkB=2,
- )
- ax.add_patch(arrow)
-
-
-def _add_independent_tool(
- ax,
- x: float,
- y: float,
- width: float,
- height: float,
- title: str,
- module: str,
- body: str,
- caution: str,
- edgecolor: str,
-) -> None:
- patch = FancyBboxPatch(
- (x, y),
- width,
- height,
- boxstyle="round,pad=0.010,rounding_size=0.012",
- facecolor=COLORS["white"],
- edgecolor=edgecolor,
- linewidth=0.8,
- linestyle=(0, (5, 2.5)),
- )
- ax.add_patch(patch)
- ax.text(
- x + 0.016,
- y + height - 0.018,
- title,
- ha="left",
- va="top",
- fontsize=8.6,
- fontweight="bold",
- color=edgecolor,
- )
- ax.text(
- x + 0.016,
- y + height - 0.052,
- module,
- ha="left",
- va="top",
- fontsize=8.4,
- color=COLORS["gray"],
- )
- ax.text(
- x + 0.016,
- y + height - 0.082,
- body,
- ha="left",
- va="top",
- fontsize=8.4,
- linespacing=1.25,
- color=COLORS["ink"],
- )
- ax.text(
- x + 0.016,
- y + 0.014,
- caution,
- ha="left",
- va="bottom",
- fontsize=8.4,
- fontweight="bold",
- color=COLORS["ink"],
+def label(ax, x, y, text, size=10, weight="normal", color=INK, ha="left", va="center"):
+ return ax.text(
+ x, y, text, fontsize=size, fontweight=weight, color=color, ha=ha, va=va, linespacing=1.45
)
-def create_architecture_workflow():
- """Create the verified RingSentry architecture and workflow diagram."""
- # 7.1 in = 180.3 mm, kept below Nature's 183 mm two-column width.
- fig, ax = plt.subplots(figsize=(7.1, 5.6))
- ax.set_xlim(0.0, 1.0)
- ax.set_ylim(0.0, 1.0)
- ax.axis("off")
+def panel(ax, x, y, letter, title):
+ label(ax, x, y, letter, 12, "bold", ACCENT)
+ label(ax, x + 0.038, y, title, 11, "bold")
- ax.text(
- 0.5,
- 0.970,
- "RingSentry architecture and auditable processing workflow",
- ha="center",
- va="top",
- fontsize=9.6,
- fontweight="bold",
- color=COLORS["ink"],
- )
- ax.text(
- 0.025,
- 0.910,
- "Main batch path (GUI-orchestrated; per-file core data path)",
- ha="left",
- va="center",
- fontsize=8.4,
- color=COLORS["gray"],
- )
- y = 0.685
- height = 0.170
- stage_specs = (
- (
- 0.025,
- 0.150,
- "1",
- "Entry / GUI",
- "main.py → App\nexplicit\nparameters",
- COLORS["light_blue"],
- COLORS["blue"],
- ),
- (
- 0.189,
- 0.174,
- "2",
- "Discover / load",
- "core.loader\nfiles → 2D arrays",
- COLORS["light_blue"],
- COLORS["blue"],
- ),
- (
- 0.377,
- 0.180,
- "3",
- "QC / preflight",
- "core.quality\nread-only QC / plan",
- COLORS["light_green"],
- COLORS["green"],
- ),
- (
- 0.571,
- 0.214,
- "4",
- "Processing",
- "core.worker\n→ apply_processing",
- COLORS["light_orange"],
- COLORS["orange"],
- ),
- (
- 0.799,
- 0.176,
- "5",
- "Write / report",
- "core.writer\n+ gui.app report",
- COLORS["light_blue"],
- COLORS["blue"],
- ),
- )
- for x, width, number, title, body, face, edge in stage_specs:
- _add_stage_box(ax, x, y, width, height, number, title, body, face, edge)
-
- for left, right in (
- (0.175, 0.189),
- (0.363, 0.377),
- (0.557, 0.571),
- (0.785, 0.799),
- ):
- _add_arrow(ax, (left, y + height / 2.0), (right, y + height / 2.0))
-
- process_box = FancyBboxPatch(
- (0.025, 0.365),
- 0.950,
- 0.225,
- boxstyle="round,pad=0.010,rounding_size=0.012",
- facecolor=COLORS["light_gray"],
- edgecolor=COLORS["orange"],
- linewidth=0.75,
- )
- ax.add_patch(process_box)
- ax.text(
- 0.045,
- 0.565,
- "apply_processing: fixed, explicit operation order",
- ha="left",
- va="top",
- fontsize=8.6,
- fontweight="bold",
- color=COLORS["ink"],
- )
- ordered_lines = (
- "1 Dark subtraction → 2 Flat correction → 3 Background offset → "
- "4 Validate clipping parameters",
- "5 ROI → 6 Mask → 7 Absolute clipping → 8 Percentile clipping",
- "9 Negative clipping → 10 Hot-pixel suppression → 11 Rotate / flip → "
- "12 Block-mean binning",
- "13 Intensity transform → 14 Gamma → 15 Normalization",
+def box(ax, x, y, w, h, title, body="", accent=ACCENT, face=LIGHT, size=9.5):
+ ax.add_patch(
+ FancyBboxPatch(
+ (x, y),
+ w,
+ h,
+ boxstyle="round,pad=0,rounding_size=0.012",
+ linewidth=0.7,
+ edgecolor=RULE,
+ facecolor=face,
+ )
)
- for index, line in enumerate(ordered_lines):
- ax.text(
- 0.500,
- 0.510 - index * 0.041,
- line,
- ha="center",
- va="center",
- fontsize=8.4,
- color=COLORS["ink"],
+ ax.plot(
+ [x + 0.015, x + 0.015],
+ [y + 0.02, y + h - 0.02],
+ color=accent,
+ lw=2.1,
+ solid_capstyle="round",
+ )
+ label(ax, x + 0.034, y + h - 0.037, title, 10, "bold", accent, va="top")
+ if body:
+ label(ax, x + 0.034, y + h - 0.099, body, size, va="top")
+
+
+def arrow(ax, a, b, color=MUTED, style="-"):
+ ax.add_patch(
+ FancyArrowPatch(
+ a,
+ b,
+ arrowstyle="-|>",
+ mutation_scale=10,
+ linewidth=1,
+ color=color,
+ linestyle=style,
+ shrinkA=2,
+ shrinkB=2,
)
- _add_arrow(ax, (0.680, 0.685), (0.680, 0.600))
-
- ax.text(
- 0.5,
- 0.335,
- "Independent tools (separate GUI tabs and core modules; not batch stages)",
- ha="center",
- va="center",
- fontsize=8.4,
- fontweight="bold",
- color=COLORS["gray"],
)
- _add_independent_tool(
+
+
+def save(fig, folder, stem, formats=("png", "svg", "pdf")):
+ folder.mkdir(parents=True, exist_ok=True)
+ for ext in formats:
+ meta = (
+ {"Date": None}
+ if ext == "svg"
+ else ({"CreationDate": None, "ModDate": None} if ext == "pdf" else {})
+ )
+ fig.savefig(folder / f"{stem}.{ext}", dpi=450, metadata=meta)
+ plt.close(fig)
+
+
+def clean_axes(ax):
+ ax.spines[["top", "right"]].set_visible(False)
+ ax.tick_params(length=3, width=0.6, color=RULE)
+ ax.grid(axis="y", color=RULE, linewidth=0.5, alpha=0.6)
+ ax.set_axisbelow(True)
+
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+from core.processing import apply_processing
+from core.quality import analyze_image_quality
+from examples.minimal_preprocessing import (
+ PROCESSING_OPTIONS,
+ SYNTHETIC_SEED,
+ generate_synthetic_detector_image,
+)
+
+
+def create_architecture_workflow():
+ fig, ax = canvas(5.5)
+ panel(ax, 0.035, 0.95, "a", "Batch workflow")
+ names = [
+ ("01 Configure", "GUI settings"),
+ ("02 Load", "Detector arrays"),
+ ("03 Inspect", "Read-only QC"),
+ ("04 Process", "Ordered steps"),
+ ("05 Export", "Data + reports"),
+ ]
+ for i, (title, body) in enumerate(names):
+ x = 0.035 + i * 0.192
+ box(ax, x, 0.75, 0.165, 0.135, title, body, size=8.8)
+ if i < 4:
+ arrow(ax, (x + 0.165, 0.814), (x + 0.192, 0.814))
+ panel(ax, 0.035, 0.68, "b", "Fixed numerical operation order")
+ operations = [
+ "Dark subtraction",
+ "Flat correction",
+ "Background offset",
+ "Validate clipping",
+ "Region of interest",
+ "Mask",
+ "Absolute clipping",
+ "Percentile clipping",
+ "Negative clipping",
+ "Hot-pixel suppression",
+ "Rotate / flip",
+ "Block-mean binning",
+ "Intensity transform",
+ "Gamma",
+ "Normalization",
+ ]
+ for i, t in enumerate(operations):
+ col, row = divmod(i, 5)
+ x = 0.048 + col * 0.32
+ y = 0.608 - row * 0.053
+ label(ax, x, y, f"{i + 1:02d}", 9, "bold", ACCENT)
+ label(ax, x + 0.049, y, t, 9.2)
+ panel(ax, 0.035, 0.30, "c", "Independent tools")
+ box(
ax,
- 0.025,
- 0.055,
- 0.455,
- 0.245,
- "Independent: CBF zero-value repair",
- "core.overexposure_repair",
- "Scan → target mask → write / read-back\n"
- "→ verify → CSV / configuration / QC reports",
- "Configured zeros only; cannot recover\ntrue saturated intensity.",
- COLORS["vermillion"],
- )
- _add_independent_tool(
+ 0.035,
+ 0.068,
+ 0.448,
+ 0.177,
+ "CBF zero-value repair",
+ "Target mask → write → verify\nConfigured zeros; not saturation recovery",
+ accent=WARM,
+ face="#FCF6EF",
+ size=8.8,
+ )
+ box(
ax,
- 0.520,
- 0.055,
- 0.455,
- 0.245,
- "Independent: Q geometry calculator",
- "core.diffraction_model",
- "User λ / distance / pixel size /\n"
- "beam center → ideal-planar Q / 2θ / r / d\n"
- "+ detector view / export",
- "No image calibration, integration, peak fitting,\nor refinement.",
- COLORS["green"],
- )
- ax.text(
- 0.5,
- 0.008,
- "Scope: inspectable preprocessing, quality control, geometry conversion, "
- "and export of 2D detector images.",
- ha="center",
- va="bottom",
- fontsize=8.4,
- color=COLORS["gray"],
+ 0.515,
+ 0.068,
+ 0.448,
+ 0.177,
+ "Ideal planar geometry",
+ "Wavelength + detector geometry\nQ, 2θ, radius and d-spacing conversion",
+ size=8.8,
+ )
+ label(
+ ax,
+ 0.035,
+ 0.025,
+ "Preprocessing and QC precede downstream integration or fitting.",
+ 8.8,
+ color=MUTED,
)
return fig
-def _radial_mean(
- arr: np.ndarray, radius_scale: float = 1.0
-) -> Tuple[np.ndarray, np.ndarray]:
- data = np.asarray(arr, dtype=np.float64)
- yy, xx = np.indices(data.shape, dtype=np.float64)
- center_x = (data.shape[1] - 1) / 2.0
- center_y = (data.shape[0] - 1) / 2.0
- radius = np.hypot(xx - center_x, yy - center_y) * float(radius_scale)
- radius_bin = np.floor(radius).astype(np.int64)
+def _radial_mean(arr, radius_scale=1.0):
+ data = np.asarray(arr, dtype=float)
+ yy, xx = np.indices(data.shape, dtype=float)
+ r = np.floor(
+ np.hypot(xx - (data.shape[1] - 1) / 2, yy - (data.shape[0] - 1) / 2) * radius_scale
+ ).astype(int)
finite = np.isfinite(data)
- sums = np.bincount(radius_bin[finite], weights=data[finite])
- counts = np.bincount(radius_bin[finite])
- valid = counts > 0
- means = np.full(counts.shape, np.nan, dtype=np.float64)
- means[valid] = sums[valid] / counts[valid]
- return np.arange(means.size, dtype=np.float64) + 0.5, means
-
-
-def _display_normalize(values: np.ndarray) -> np.ndarray:
- values = np.asarray(values, dtype=np.float64)
- finite = np.isfinite(values)
- result = np.full(values.shape, np.nan, dtype=np.float64)
- if not np.any(finite):
- return result
- vmin = float(np.min(values[finite]))
- vmax = float(np.max(values[finite]))
- if vmax > vmin:
- result[finite] = (values[finite] - vmin) / (vmax - vmin)
- else:
- result[finite] = 0.0
- return result
-
-
-def _array_fact_line(label: str, arr: np.ndarray) -> str:
- finite_count = int(np.count_nonzero(np.isfinite(arr)))
- return (
- f"{label}: {arr.shape[0]} × {arr.shape[1]}, {arr.dtype}, "
- f"finite {finite_count:,}/{arr.size:,}"
- )
+ sums = np.bincount(r[finite], weights=data[finite])
+ counts = np.bincount(r[finite])
+ means = np.full(counts.shape, np.nan)
+ means[counts > 0] = sums[counts > 0] / counts[counts > 0]
+ return np.arange(len(means)) + 0.5, means
+
+
+def _display_normalize(a):
+ return (a - np.nanmin(a)) / (np.nanmax(a) - np.nanmin(a))
def create_synthetic_processing():
- """Create a no-real-data demonstration using the shipped example seam."""
raw = generate_synthetic_detector_image()
processed = apply_processing(raw, **PROCESSING_OPTIONS)
- quality = analyze_image_quality(
+ qc = analyze_image_quality(
raw,
metadata={
"source_kind": "synthetic",
@@ -432,222 +232,68 @@ def create_synthetic_processing():
},
source_name="synthetic_diffraction_rings",
)
-
- fig = plt.figure(figsize=(7.1, 5.2), constrained_layout=False)
- grid = fig.add_gridspec(
- 1,
- 3,
- left=0.070,
- right=0.980,
- bottom=0.360,
- top=0.795,
- wspace=0.48,
- width_ratios=(1.0, 1.0, 1.35),
- )
- raw_ax = fig.add_subplot(grid[0, 0])
- processed_ax = fig.add_subplot(grid[0, 1])
- profile_ax = fig.add_subplot(grid[0, 2])
-
- fig.text(
- 0.5,
- 0.950,
- "Deterministic synthetic preprocessing example",
- ha="center",
- va="top",
- fontsize=9.6,
- fontweight="bold",
- color=COLORS["ink"],
- )
- fig.text(
- 0.5,
- 0.875,
- "Fixed-seed synthetic image and settings from the shipped minimal "
- "preprocessing example; processed by the RingSentry core",
- ha="center",
- va="center",
- fontsize=8.4,
- color=COLORS["gray"],
- )
-
- raw_image = raw_ax.imshow(raw, origin="upper", cmap="cividis", interpolation="nearest")
- raw_ax.set_title("Raw synthetic matrix", pad=5)
- raw_ax.set_xlabel("Detector x (pixels)")
- raw_ax.set_ylabel("Detector y (pixels)")
- raw_colorbar = fig.colorbar(
- raw_image,
- ax=raw_ax,
- orientation="horizontal",
- fraction=0.060,
- pad=0.175,
- aspect=28,
- )
- raw_colorbar.set_label("Synthetic intensity (a.u.)", fontsize=8.4, labelpad=2)
- raw_colorbar.ax.tick_params(labelsize=8.4, width=0.5, length=2.0)
-
- processed_image = processed_ax.imshow(
- processed,
- origin="upper",
- cmap="cividis",
- interpolation="nearest",
- vmin=0.0,
- vmax=1.0,
- )
- processed_ax.set_title("Processed matrix", pad=5)
- processed_ax.set_xlabel("Output x (pixels)")
- processed_ax.set_ylabel("Output y (pixels)")
- processed_colorbar = fig.colorbar(
- processed_image,
- ax=processed_ax,
- orientation="horizontal",
- fraction=0.060,
- pad=0.175,
- aspect=28,
- )
- processed_colorbar.set_label("Normalized value", fontsize=8.4, labelpad=2)
- processed_colorbar.ax.tick_params(labelsize=8.4, width=0.5, length=2.0)
-
- raw_radius, raw_profile = _radial_mean(raw)
- scale = float(PROCESSING_OPTIONS.get("bin_factor", 1))
- processed_radius, processed_profile = _radial_mean(
- processed, radius_scale=scale
- )
- profile_ax.plot(
- raw_radius,
- _display_normalize(raw_profile),
- color=COLORS["blue"],
- linestyle="-",
- marker="o",
- markevery=8,
- markersize=2.8,
- label="Raw synthetic",
- )
- profile_ax.plot(
- processed_radius,
- _display_normalize(processed_profile),
- color=COLORS["orange"],
- linestyle="--",
- marker="s",
- markevery=7,
- markersize=2.7,
- label="Processed",
- )
- profile_ax.set_title("Radial mean (display-normalized)", pad=5)
- profile_ax.set_xlabel("Radius (input-pixel equivalent)")
- profile_ax.set_ylabel("Separately normalized mean (a.u.)")
- profile_ax.set_ylim(-0.04, 1.08)
- profile_ax.grid(axis="y", color="#D0D0D0", linewidth=0.5, linestyle=":")
- profile_ax.spines["top"].set_visible(False)
- profile_ax.spines["right"].set_visible(False)
- profile_ax.legend(loc="upper right", frameon=False, handlelength=2.6)
- for label, axis in zip(("a", "b", "c"), (raw_ax, processed_ax, profile_ax)):
- axis.text(
- -0.16,
- 1.10,
- label,
- transform=axis.transAxes,
- ha="left",
- va="top",
- fontsize=10.0,
- fontweight="bold",
- color=COLORS["ink"],
+ assert np.isfinite(raw).all() and np.isfinite(processed).all()
+ assert qc is not None
+ fig = plt.figure(figsize=(7.2, 5.7))
+ a = fig.add_axes([0.10, 0.52, 0.31, 0.38])
+ b = fig.add_axes([0.59, 0.52, 0.31, 0.38])
+ for ax, arr, title, xlab, unit in [
+ (a, raw, "a Raw synthetic image", "Detector", "Intensity (a.u.)"),
+ (b, processed, "b Processed image", "Output", "Normalized value"),
+ ]:
+ im = ax.imshow(arr, cmap="cividis", origin="upper", interpolation="nearest")
+ ax.set_title(title, loc="left", fontweight="bold", pad=12)
+ ax.set_xlabel(f"{xlab} x (pixels)")
+ ax.set_ylabel(f"{xlab} y (pixels)")
+ cb = fig.colorbar(im, ax=ax, fraction=0.047, pad=0.025)
+ cb.set_label(unit, fontsize=9)
+ cb.ax.tick_params(labelsize=8, length=2)
+ c = fig.add_axes([0.10, 0.12, 0.8, 0.245])
+ for arr, scale, color, ls, mark, title in [
+ (raw, 1.0, ACCENT, "-", "o", "Raw"),
+ (processed, float(PROCESSING_OPTIONS.get("bin_factor", 1)), WARM, "--", "s", "Processed"),
+ ]:
+ r, p = _radial_mean(arr, scale)
+ c.plot(
+ r,
+ _display_normalize(p),
+ color=color,
+ ls=ls,
+ marker=mark,
+ markevery=9,
+ ms=3,
+ label=title,
)
-
- findings = ", ".join(item.category for item in quality.findings) or "none"
- processing_text = (
- "Processing: background offset 35 → percentile clipping 0.5–99.5 →\n"
- "negative clipping → "
- "2 × block mean → log1p → min–max normalization"
- )
- fact_text = (
- f"Seed: {SYNTHETIC_SEED} | Shipped example: examples/minimal_preprocessing.py\n"
- f"{_array_fact_line('Raw', raw)}\n"
- f"{_array_fact_line('Processed', processed)}\n"
- f"QC findings: {findings}; review_required={str(quality.review_required).lower()}\n"
- f"{processing_text}"
+ c.set_title(
+ "c Radial means · independently normalized for display",
+ loc="left",
+ fontweight="bold",
+ pad=9,
)
+ c.set(xlabel="Radius (input-pixel equivalent)", ylabel="Scaled intensity", ylim=(-0.04, 1.1))
+ c.legend(frameon=False, loc="upper right", ncol=2, fontsize=9)
+ clean_axes(c)
fig.text(
- 0.055,
- 0.055,
- fact_text,
- ha="left",
- va="bottom",
- fontsize=8.4,
- linespacing=1.35,
- color=COLORS["ink"],
- bbox={
- "boxstyle": "round,pad=0.32",
- "facecolor": COLORS["light_gray"],
- "edgecolor": "#B8B8B8",
- "linewidth": 0.7,
- },
+ 0.10,
+ 0.025,
+ f"Synthetic example · seed {SYNTHETIC_SEED} · 128 × 128 → 64 × 64 pixels",
+ fontsize=9,
+ color=MUTED,
)
return fig
-def _save_figure(fig, output_dir: Path, stem: str, formats: Iterable[str]) -> None:
- output_dir.mkdir(parents=True, exist_ok=True)
- for fmt in formats:
- output_path = output_dir / f"{stem}.{fmt}"
- metadata: Optional[Dict[str, object]]
- if fmt == "svg":
- metadata = {"Creator": "RingSentry paper/figures/make_figures.py", "Date": None}
- elif fmt == "pdf":
- metadata = {
- "Creator": "RingSentry paper/figures/make_figures.py",
- "CreationDate": None,
- "ModDate": None,
- }
- else:
- metadata = {"Software": "RingSentry paper/figures/make_figures.py"}
- fig.savefig(
- output_path,
- format=fmt,
- dpi=600,
- metadata=metadata,
- )
- print(f"WROTE {output_path.resolve()}")
-
-
-def generate_figures(output_dir: Path, formats: Sequence[str]) -> None:
- configure_style()
- creators = (
- (FIGURE_STEMS[0], create_architecture_workflow),
- (FIGURE_STEMS[1], create_synthetic_processing),
- )
- for stem, creator in creators:
- figure = creator()
- try:
- _save_figure(figure, output_dir, stem, formats)
- finally:
- plt.close(figure)
-
-
-def _parse_args(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
- parser = argparse.ArgumentParser(
- description="Generate the RingSentry JOSS architecture and synthetic figures."
- )
- parser.add_argument(
- "--output-dir",
- type=Path,
- default=Path(__file__).resolve().parent,
- help="Destination directory (default: paper/figures).",
- )
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--output-dir", type=Path, default=Path(__file__).resolve().parent)
parser.add_argument(
- "--formats",
- nargs="+",
- choices=SUPPORTED_FORMATS,
- default=list(SUPPORTED_FORMATS),
- help="One or more output formats; default: svg, pdf, and png.",
+ "--formats", nargs="+", choices=["png", "svg", "pdf"], default=["png", "svg", "pdf"]
)
- return parser.parse_args(argv)
-
-
-def main(argv: Optional[Sequence[str]] = None) -> int:
- args = _parse_args(argv)
- formats = tuple(dict.fromkeys(args.formats))
- generate_figures(args.output_dir, formats)
- return 0
+ args = parser.parse_args()
+ style()
+ save(create_architecture_workflow(), args.output_dir, "architecture_workflow", args.formats)
+ save(create_synthetic_processing(), args.output_dir, "synthetic_processing", args.formats)
if __name__ == "__main__":
- raise SystemExit(main())
+ main()
diff --git a/paper/figures/synthetic_processing.pdf b/paper/figures/synthetic_processing.pdf
index abb8bb3..c98cef2 100644
Binary files a/paper/figures/synthetic_processing.pdf and b/paper/figures/synthetic_processing.pdf differ
diff --git a/paper/figures/synthetic_processing.png b/paper/figures/synthetic_processing.png
index 96fca8c..487a19f 100644
Binary files a/paper/figures/synthetic_processing.png and b/paper/figures/synthetic_processing.png differ
diff --git a/paper/figures/synthetic_processing.svg b/paper/figures/synthetic_processing.svg
index a9a73db..af5fdf1 100644
--- a/paper/figures/synthetic_processing.svg
+++ b/paper/figures/synthetic_processing.svg
@@ -1,7 +1,7 @@
-
+
@@ -9,7 +9,7 @@
image/svg+xml
- RingSentry paper/figures/make_figures.py
+ Matplotlib v3.10.8, https://matplotlib.org/
@@ -20,907 +20,934 @@
-
-
-
+
-
-
- 0
+ 0
-
- 50
+ 50
-
- 100
+ 100
- Detector x (pixels)
+ Detector x (pixels)
-
-
- 0
+ 0
-
- 25
+ 20
-
- 50
+ 40
-
- 75
+ 60
-
- 100
+ 80
-
- 125
+ 100
-
- Detector y (pixels)
+
+
+
+
+
+
+ 120
+
+
+
+ Detector y (pixels)
-
-
-
-
-
- a
+
- Raw synthetic matrix
+ a Raw synthetic image
-
-
+
-
+
-
- 0
+ 0
-
+
-
- 20
+ 20
-
+
-
- 40
+ 40
-
+
-
- 60
+ 60
- Output x (pixels)
+ Output x (pixels)
-
-
+
+
-
- 0
+ 0
-
-
+
+
-
- 20
+ 10
-
-
+
+
-
- 40
+ 20
-
-
+
+
-
- 60
+ 30
-
- Output y (pixels)
+
+
+
+
+
+
+ 40
+
+
+
+
+
+
+
+
+ 50
+
+
+
+
+
+
+
+
+ 60
+
+
+
+ Output y (pixels)
-
-
-
-
-
- b
-
-
- Processed matrix
+
+ b Processed image
-
-
-
-
+
+
+
+
+
-
-
- 0
+
+ 40
-
-
+
+
-
-
- 20
+
+ 45
-
-
+
+
-
-
- 40
+
+ 50
-
-
+
+
-
-
- 60
+
+ 55
-
-
+
+
-
-
- 80
+
+ 60
-
- Radius (input-pixel equivalent)
+
+ Intensity (a.u.)
-
-
-
-
-
+
+
+
+
+
+
+
+
+
-
-
- 0.0
+
+ 0.0
-
-
-
-
+
+
-
-
- 0.2
+
+ 0.2
-
-
-
-
+
+
-
-
- 0.4
+
+ 0.4
-
-
-
+
-
-
- 0.6
+
+ 0.6
-
+
-
-
-
-
- 0.8
+
+ 0.8
-
-
-
-
+
+
-
-
- 1.0
-
-
-
- Separately normalized mean (a.u.)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- c
-
-
- Radial mean (display-normalized)
-
-
-
-
-
-
-
- Raw synthetic
-
-
-
-
+ 1.0
-
- Processed
+
+ Normalized value
-
-
+
-
+
+
+
+
-
-
-
+
+
+
-
-
+
+
+ 0
+
+
+
+
+
+
+
+
+ 20
+
+
+
+
+
+
- 40
+ 40
-
-
+
+
-
- 50
+ 60
-
-
+
+
-
- 60
+ 80
- Synthetic intensity (a.u.)
+ Radius (input-pixel equivalent)
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
-
- 0.00
+ 0.00
-
-
+
+
+
+
-
- 0.25
+ 0.25
-
-
+
+
+
+
-
- 0.50
+ 0.50
-
+
+
+
-
- 0.75
+ 0.75
-
+
+
+
-
- 1.00
+ 1.00
- Normalized value
+ Scaled intensity
+
+
+
+
+
+
+
+
+
+
+
+
+
-
+
-
+
+ c Radial means · independently normalized for display
+
+
+
+
+
+
+
+ Raw
+
+
+
+
+
+
+ Processed
+
-
- Deterministic synthetic preprocessing example
-
-
- Fixed-seed synthetic image and settings from the shipped minimal preprocessing example; processed by the RingSentry core
-
-
-
-
- Seed: 20260730 | Shipped example: examples/minimal_preprocessing.py
- Raw: 128 × 128, float32, finite 16,384/16,384
- Processed: 64 × 64, float32, finite 4,096/4,096
- QC findings: none; review_required=false
- Processing: background offset 35 → percentile clipping 0.5–99.5 →
- negative clipping → 2 × block mean → log1p → min–max normalization
+
+ Synthetic example · seed 20260730 · 128 × 128 → 64 × 64 pixels
-
-
+
-
-
+
-
-
+
diff --git a/paper/paper.md b/paper/paper.md
index 5923a00..cdc8546 100644
--- a/paper/paper.md
+++ b/paper/paper.md
@@ -41,7 +41,7 @@ The application separates the `tkinter` interface from numerical and I/O modules
The processing function converts an input to a two-dimensional `float32` array and applies enabled operations in a documented order: dark subtraction, flat correction, background subtraction, region-of-interest cropping, masking, absolute and percentile limits, negative clipping, local median/MAD hot-pixel suppression, right-angle rotations and flips, block-mean binning, intensity transform, gamma, and normalization. Flat correction expects a relative detector-response map; RingSentry does not normalize raw flat counts automatically. Invalid flat denominators and masked pixels become non-finite values within the pipeline. Writers for compatible floating-point formats preserve these values. CSV and DAT matrices replace non-finite values with zero and add category counts to batch records; external software may render non-finite TIFF values inconsistently. PNG generation follows a distinct fixed-range display path.
-
+
Core behavior is testable without opening the GUI. The test suite covers numerical processing, QC, diffraction geometry, EDF and FabIO interoperability, output semantics, CBF replacement safeguards, interface error handling, metadata consistency, and the end-to-end synthetic example. The example generates two analytic rings with seeded noise, processes the array, and saves quantitative NPY data, a display PNG, and a machine-readable summary.
@@ -62,6 +62,8 @@ RingSentry is distributed under the MIT License from [GitHub](https://github.com
OpenAI Codex assisted earlier repository inspection, requirements and literature organization, tests, documentation, figures and manuscript preparation in July and August 2026. The exact hosted model version for that earlier work was not retained. In September 2026, OpenAI Codex (GPT-6) assisted submission preparation, metadata alignment, research-use documentation and automated verification. The author must review and confirm the complete disclosure and all new AI-assisted outputs before submission.
+The README cover is AI-generated conceptual artwork. Manuscript diagrams and numerical plots are produced by repository scripts; scientific data are not retouched by an image-generation model.
+
# Acknowledgements
No external funding was received for this software. There was no sponsor involvement. The author declares no competing interests.
+ 
