tofscope 0.1.0__tar.gz → 0.1.2__tar.gz

{tofscope-0.1.0 → tofscope-0.1.2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Josh Taillon
+Copyright (c) 2026 Josh Taillon, datasophos LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

tofscope-0.1.2/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: tofscope
+Version: 0.1.2
+Summary: Multi-analysis ToF-SIMS exploration and calibrated 3D visualization
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: h5py>=3.11
+Requires-Dist: numpy>=2.0
+Requires-Dist: filelock>=3.16
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: psutil>=6
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/datasophos/ToFScope/main/docs/assets/tofscope-logo.svg" alt="ToFScope — FIB–SEM / TOF–SIMS" width="324">
+</p>
+
+# ToFScope
+
+[![PyPI version](https://img.shields.io/pypi/v/tofscope)](https://pypi.org/project/tofscope/)
+[![Documentation](https://img.shields.io/badge/docs-read-blue)](https://datasophos.github.io/ToFScope/)
+
+ToFScope is a browser-based application for exploring time-of-flight secondary ion mass spectrometry (ToF-SIMS) data. It allows you to analyze ion images, mass spectra, and depth profiles together so you can inspect an acquisition, compare signals, and save your analysis for later.
+
+ToFScope runs locally as a Python application and opens in your browser. It reads TOFWERK TOFexplorer[^trademark] HDF5 (`.h5`) acquisitions, and provides interactive tools for exploring their mass spectra, ion images, and depth profiles in two and three dimensions.
+
+**[Read the ToFScope documentation](https://datasophos.github.io/ToFScope/)** for installation, user guides, deployment, and developer information. Start with [Install and launch](https://datasophos.github.io/ToFScope/docs/getting-started/installation.html) or [Your first analysis](https://datasophos.github.io/ToFScope/docs/getting-started/first-analysis.html).
+
+![ToFScope Explore showing an ion map, mass spectrum, front projection, and depth profile from a real acquisition](https://raw.githubusercontent.com/datasophos/ToFScope/main/docs/assets/tofscope-explore.png)
+
+*Explore view showing an ion map, mass spectrum, front projection, and depth profile for a real acquisition.*
+
+## What you can do
+
+- **Explore an acquisition:** view ion maps, a mass spectrum, front projections, and depth profiles together; choose custom regions of interest and frame range.
+- **Compare signals:** use stored ion channels or define custom mass windows from the spectrum, then compare their profiles.
+- **Work with depth:** add calibration anchors to display profiles and projections in physical depth where calibration is known.
+- **Inspect peaks and isotopes:** find candidate atomic isotope ions and measure selected signals over a region and frame range.
+- **Visualize in 3D:** compare signals as volume overlays or tiled views, with controls for color, opacity, and threshold.
+- **Keep and share results:** export profiles as CSV or plots as PNG, and save data back into TOFexplorer-compatible `.h5` files.
+
+![ToFScope 3D visualizer showing an overlay of aluminum and titanium signals](https://raw.githubusercontent.com/datasophos/ToFScope/main/docs/assets/tofscope-3d.png)
+
+*3D volume view comparing aluminum and titanium signals across acquisition frames.*
+
+![Atomic identification dialog showing an aluminum-27 isotope candidate and mass spectrum](https://raw.githubusercontent.com/datasophos/ToFScope/main/docs/assets/tofscope-isotope-identification.png)
+
+*Atomic identification compares a measured mass-to-charge ratio with candidate isotope ions.*
+
+## Get started
+
+You need Python 3.11 or newer, [uv](https://docs.astral.sh/uv/getting-started/installation/), and a folder containing supported TOFexplorer `.h5` files. Install from PyPI:
+
+```sh
+uv tool install tofscope
+tofscope --data-root /path/to/acquisitions --output-root /path/to/saved-analyses
+```
+
+Replace the example paths with your folders. The output folder must be writable and have enough space for a full copy of an acquisition. ToFScope starts a local service and opens the app in your browser. Select a file to begin; keep the terminal open while you work and press **Ctrl-C** there to stop the app.
+
+For step-by-step installation, folder setup, and troubleshooting, see [Install and launch](https://datasophos.github.io/ToFScope/docs/getting-started/installation.html). See the [configuration reference](https://datasophos.github.io/ToFScope/docs/technical-documentation/configuration.html) for settings, and [deployment](https://datasophos.github.io/ToFScope/docs/technical-documentation/deployment.html) for hosted use and containers.
+
+## Your first analysis
+
+1. Open an acquisition and choose a stored signal, or create one from a mass window in the spectrum.
+2. Select a frame range and region of interest to explore its ion image and depth profile. Add other signals to compare profiles.
+3. Use **Depth calibration…** if you have known frame-to-depth measurements, or open **3D volume** to explore the signal spatially.
+4. Choose **Save as…** to save a new analysis copy. After a restart, open it through **Saved files** to resume your saved work.
+
+Saving leaves the source acquisition unchanged. Unsaved tabs and in-progress calculations do not survive a restart. Some raw files require preparation into a new copy before exploration; ToFScope previews that step and asks for confirmation.
+
+The [user guide](https://datasophos.github.io/ToFScope/docs/getting-started/index.html) covers signals, calibration, exports, isotope identification, saving, and 3D controls in more detail.
+
+## Current limitations
+
+ToFScope is under active development and is in an alpha state. The application may change substantially prior to a stable 1.0.0 release.
+See the [user guide](https://datasophos.github.io/ToFScope/docs/getting-started/index.html) for details.
+If you have ideas of features to add, or notice any bugs, please open an [issue](https://github.com/datasophos/ToFScope/issues)!
+
+## Developing ToFScope
+
+The frontend is built with React and TypeScript; the service backend uses Python and FastAPI. Node.js is needed to develop or rebuild the frontend, but not to run the packaged application. From a source checkout:
+
+```sh
+uv sync --frozen
+uv run tofscope --data-root /path/to/acquisitions --output-root /path/to/saved-analyses
+```
+
+For frontend and Python checks, build instructions, and distribution validation, see the [developer commands](https://datasophos.github.io/ToFScope/docs/technical-documentation/building-and-testing.html).
+
+For a diagram-led overview of the application, see [ToFScope architecture](https://datasophos.github.io/ToFScope/docs/technical-documentation/architecture.html).
+
+To build or preview the documentation site, see [maintaining the documentation](https://datasophos.github.io/ToFScope/docs/technical-documentation/documentation.html).
+
+## License
+
+ToFScope is available under the [MIT License](https://github.com/datasophos/ToFScope/blob/main/LICENSE).
+
+---
+
+[^trademark]: TOFWERK and TOFexplorer are names owned by [TOFWERK AG](https://www.tofwerk.com/). They are used here solely to identify the products and file formats supported by ToFScope. ToFScope is an independent project and is not affiliated with, endorsed by, or sponsored by TOFWERK AG.

{tofscope-0.1.0 → tofscope-0.1.2}/README.md

@@ -1,14 +1,19 @@
 <p align="center">
-  <img src="docs/assets/tofscope-logo.svg" alt="ToFScope — FIB–SEM / TOF–SIMS" width="324">
+  <img src="https://raw.githubusercontent.com/datasophos/ToFScope/main/docs/assets/tofscope-logo.svg" alt="ToFScope — FIB–SEM / TOF–SIMS" width="324">
 </p>
 
 # ToFScope
 
+[![PyPI version](https://img.shields.io/pypi/v/tofscope)](https://pypi.org/project/tofscope/)
+[![Documentation](https://img.shields.io/badge/docs-read-blue)](https://datasophos.github.io/ToFScope/)
+
 ToFScope is a browser-based application for exploring time-of-flight secondary ion mass spectrometry (ToF-SIMS) data. It allows you to analyze ion images, mass spectra, and depth profiles together so you can inspect an acquisition, compare signals, and save your analysis for later.
 
-ToFScope runs locally as a Python application and opens in your browser. It reads [TOFWERK TOFexplorer](#trademark-disclaimer) HDF5 (`.h5`) acquisitions, and provides interactive tools for exploring their mass spectra, ion images, and depth profiles in two and three dimensions.
+ToFScope runs locally as a Python application and opens in your browser. It reads TOFWERK TOFexplorer[^trademark] HDF5 (`.h5`) acquisitions, and provides interactive tools for exploring their mass spectra, ion images, and depth profiles in two and three dimensions.
+
+**[Read the ToFScope documentation](https://datasophos.github.io/ToFScope/)** for installation, user guides, deployment, and developer information. Start with [Install and launch](https://datasophos.github.io/ToFScope/docs/getting-started/installation.html) or [Your first analysis](https://datasophos.github.io/ToFScope/docs/getting-started/first-analysis.html).
 
-![ToFScope Explore showing an ion map, mass spectrum, front projection, and depth profile from a real acquisition](docs/assets/tofscope-explore.png)
+![ToFScope Explore showing an ion map, mass spectrum, front projection, and depth profile from a real acquisition](https://raw.githubusercontent.com/datasophos/ToFScope/main/docs/assets/tofscope-explore.png)
 
 *Explore view showing an ion map, mass spectrum, front projection, and depth profile for a real acquisition.*
 
@@ -21,26 +26,26 @@ ToFScope runs locally as a Python application and opens in your browser. It read
 - **Visualize in 3D:** compare signals as volume overlays or tiled views, with controls for color, opacity, and threshold.
 - **Keep and share results:** export profiles as CSV or plots as PNG, and save data back into TOFexplorer-compatible `.h5` files.
 
-![ToFScope 3D visualizer showing an overlay of aluminum and titanium signals](docs/assets/tofscope-3d.png)
+![ToFScope 3D visualizer showing an overlay of aluminum and titanium signals](https://raw.githubusercontent.com/datasophos/ToFScope/main/docs/assets/tofscope-3d.png)
 
 *3D volume view comparing aluminum and titanium signals across acquisition frames.*
 
-![Atomic identification dialog showing an aluminum-27 isotope candidate and mass spectrum](docs/assets/tofscope-isotope-identification.png)
+![Atomic identification dialog showing an aluminum-27 isotope candidate and mass spectrum](https://raw.githubusercontent.com/datasophos/ToFScope/main/docs/assets/tofscope-isotope-identification.png)
 
 *Atomic identification compares a measured mass-to-charge ratio with candidate isotope ions.*
 
 ## Get started
 
-You need Python 3.11 or newer, [uv](https://docs.astral.sh/uv/getting-started/installation/), and a folder containing supported TOFexplorer `.h5` files. From a clone of this repository:
+You need Python 3.11 or newer, [uv](https://docs.astral.sh/uv/getting-started/installation/), and a folder containing supported TOFexplorer `.h5` files. Install from PyPI:
 
 ```sh
-uv tool install .
+uv tool install tofscope
 tofscope --data-root /path/to/acquisitions --output-root /path/to/saved-analyses
 ```
 
 Replace the example paths with your folders. The output folder must be writable and have enough space for a full copy of an acquisition. ToFScope starts a local service and opens the app in your browser. Select a file to begin; keep the terminal open while you work and press **Ctrl-C** there to stop the app.
 
-For a step-by-step installation, including folder setup and troubleshooting, see the [macOS setup guide](docs/macos-tofscope.md). For configuration, hosted use, and containers, see [deployment](docs/deployment.md).
+For step-by-step installation, folder setup, and troubleshooting, see [Install and launch](https://datasophos.github.io/ToFScope/docs/getting-started/installation.html). See the [configuration reference](https://datasophos.github.io/ToFScope/docs/technical-documentation/configuration.html) for settings, and [deployment](https://datasophos.github.io/ToFScope/docs/technical-documentation/deployment.html) for hosted use and containers.
 
 ## Your first analysis
 
@@ -51,12 +56,12 @@ For a step-by-step installation, including folder setup and troubleshooting, see
 
 Saving leaves the source acquisition unchanged. Unsaved tabs and in-progress calculations do not survive a restart. Some raw files require preparation into a new copy before exploration; ToFScope previews that step and asks for confirmation.
 
-The [user guide](docs/user-guide.md) covers signals, calibration, exports, isotope identification, saving, and 3D controls in more detail.
+The [user guide](https://datasophos.github.io/ToFScope/docs/getting-started/index.html) covers signals, calibration, exports, isotope identification, saving, and 3D controls in more detail.
 
 ## Current limitations
 
 ToFScope is under active development and is in an alpha state. The application may change substantially prior to a stable 1.0.0 release.
-See the [user guide](docs/user-guide.md) and [project roadmap](TODO.md) for details.
+See the [user guide](https://datasophos.github.io/ToFScope/docs/getting-started/index.html) for details.
 If you have ideas of features to add, or notice any bugs, please open an [issue](https://github.com/datasophos/ToFScope/issues)!
 
 ## Developing ToFScope
@@ -68,14 +73,16 @@ uv sync --frozen
 uv run tofscope --data-root /path/to/acquisitions --output-root /path/to/saved-analyses
 ```
 
-For frontend and Python checks, build instructions, and distribution validation, see the [developer commands](docs/user-guide.md#building-and-testing). Scientific and implementation evidence is available in [docs/validation](docs/validation/).
+For frontend and Python checks, build instructions, and distribution validation, see the [developer commands](https://datasophos.github.io/ToFScope/docs/technical-documentation/building-and-testing.html).
+
+For a diagram-led overview of the application, see [ToFScope architecture](https://datasophos.github.io/ToFScope/docs/technical-documentation/architecture.html).
+
+To build or preview the documentation site, see [maintaining the documentation](https://datasophos.github.io/ToFScope/docs/technical-documentation/documentation.html).
 
 ## License
 
-ToFScope is available under the [MIT License](LICENSE).
+ToFScope is available under the [MIT License](https://github.com/datasophos/ToFScope/blob/main/LICENSE).
 
 ---
 
-### Trademark disclaimer
-
-TOFWERK and TOFexplorer are names owned by [TOFWERK AG](https://www.tofwerk.com/). They are used here solely to identify the products and file formats supported by ToFScope. ToFScope is an independent project and is not affiliated with, endorsed by, or sponsored by TOFWERK AG.
+[^trademark]: TOFWERK and TOFexplorer are names owned by [TOFWERK AG](https://www.tofwerk.com/). They are used here solely to identify the products and file formats supported by ToFScope. ToFScope is an independent project and is not affiliated with, endorsed by, or sponsored by TOFWERK AG.

{tofscope-0.1.0 → tofscope-0.1.2}/pyproject.toml

@@ -4,8 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tofscope"
-version = "0.1.0"
+version = "0.1.2"
 description = "Multi-analysis ToF-SIMS exploration and calibrated 3D visualization"
+readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
 dependencies = ["h5py>=3.11", "numpy>=2.0", "filelock>=3.16", "fastapi>=0.115", "uvicorn>=0.30", "psutil>=6"]
@@ -20,6 +21,9 @@ dev = [
     "playwright>=1.50",
     "rosettasciio==0.15.0",
 ]
+docs = [
+    "great-docs==0.17.0",
+]
 
 [tool.setuptools.packages.find]
 where = ["src"]

tofscope-0.1.2/src/tofscope/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

{tofscope-0.1.0 → tofscope-0.1.2}/src/tofscope/application/analyses.py

@@ -2,6 +2,8 @@ from collections import OrderedDict
 from dataclasses import dataclass, field, replace
 from threading import RLock
 from uuid import uuid4
+
+import numpy as np
 from tofscope.storage.acquisitions import SourceChanged
 from tofscope.application.models import (
     AnalysisSnapshot,
@@ -13,6 +15,31 @@ from tofscope.application.commands import AllDepth
 from tofscope.science.signals import SignalRecipe
 
 
+DEFAULT_MIN_MZ = 20.0
+
+
+def strongest_spectral_peak(peaks, mass_axis, spectrum):
+    """Estimate stored-channel intensity from its inclusive spectrum window.
+
+    The sum spectrum is a fast proxy; it need not match stored ion-map totals.
+    Peaks below m/z 20 are excluded unless no peak meets that threshold.
+    Nonfinite spectrum samples are ignored, and ties retain peak-table order.
+    """
+    axis = np.asarray(mass_axis, dtype=np.float64)
+    finite = np.isfinite(spectrum)
+    eligible = [peak for peak in peaks if peak["mass"] >= DEFAULT_MIN_MZ] or peaks
+    best = eligible[0]
+    best_score = float("-inf")
+    for peak in eligible:
+        included = finite & (axis >= peak["low"]) & (axis <= peak["high"])
+        if not included.any():
+            continue
+        score = np.sum(spectrum, where=included, dtype=np.float64)
+        if score > best_score:
+            best, best_score = peak, score
+    return best
+
+
 class CapacityError(ValueError):
     pass
 
@@ -90,10 +117,10 @@ class AnalysisService:
     def initial(self, owner, dataset, aid=None, revision=0):
         with self.repository.metadata(owner, dataset, aid) as m:
             nz, ny, nx, _ = m.shape
-            default = min(m.peaks, key=lambda p: abs(p["mass"] - 27))
+            default = strongest_spectral_peak(m.peaks, m.mass_axis, m.sum_spectrum)
             frames = (0, nz - 1)
             recipe = SignalRecipe(
-                label=f"{default['label']} · {default['mass']:g} Th",
+                label=f"{default['label']} · m/z {default['mass']:g}",
                 source="stored",
                 stored_index=default["index"],
                 intervals=((default["low"], default["high"]),),

{tofscope-0.1.0 → tofscope-0.1.2}/src/tofscope/application/explore.py

@@ -20,7 +20,7 @@ class ExploreService:
             raise ValueError("Coverage outside acquisition.")
         p = s.peaks[index]
         return SignalRecipe(
-            label=f"{p.label} · {p.mass:g} Th",
+            label=f"{p.label} · m/z {p.mass:g}",
             source="stored",
             stored_index=index,
             intervals=((p.low, p.high),),

{tofscope-0.1.0 → tofscope-0.1.2}/src/tofscope/cli.py

@@ -1,12 +1,9 @@
 """One Python service/port, loopback by default; Node is build-time only."""
 
 import argparse
-from dataclasses import asdict
 import hashlib
-from importlib.resources import files
 import json
 import os
-from pathlib import Path
 import secrets
 import socket
 import sys
@@ -14,7 +11,12 @@ import threading
 import time
 import urllib.request
 import webbrowser
+from dataclasses import asdict
+from importlib.resources import files
+from pathlib import Path
+
 import uvicorn
+
 from tofscope import __version__
 from tofscope.api.app import create_app
 from tofscope.config import load_settings
@@ -56,6 +58,9 @@ def run_service(settings, browser=False):
         socket.AF_INET6 if ":" in settings.host else socket.AF_INET, socket.SOCK_STREAM
     )
     try:
+        if os.name != "nt":
+            # Rebind promptly after closed connections leave the port in TIME_WAIT.
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
         sock.bind((settings.host, settings.port))
         sock.listen(128)
     except OSError:
@@ -106,8 +111,11 @@ def main(argv=None):
     p.add_argument("--port", type=int)
     p.add_argument("--mode", choices=["local", "proxy"])
     p.add_argument("--no-browser", action="store_true")
+    p.add_argument("--json", action="store_true", help="Print the doctor report as JSON")
     p.add_argument("--version", action="version", version=__version__)
     a = p.parse_args(argv)
+    if a.json and a.command != "doctor":
+        p.error("--json is only available with doctor")
     try:
         settings = load_settings(
             a.config,
@@ -126,16 +134,19 @@ def main(argv=None):
         )
         if a.command == "doctor":
             assets = asset_status()
-            public = asdict(settings)
-            public.update(
-                version=__version__,
-                asset_version=assets["version"],
-                scope="Explore-only",
-                writes_available=False,
-                save_copies_available=True,
-                notes="Managed array budget excludes Python/HDF5/browser allocator overhead; one API process.",
-            )
-            print(json.dumps(public, default=str, indent=2))
+            if a.json:
+                public = asdict(settings)
+                public.update(
+                    version=__version__,
+                    asset_version=assets["version"],
+                    scope="Explore-only",
+                    writes_available=False,
+                    save_copies_available=True,
+                    notes="Managed array budget excludes Python/HDF5/browser allocator overhead; one API process.",
+                )
+                print(json.dumps(public, default=str, indent=2))
+            else:
+                print("Everything looks good: configuration loaded and frontend assets verified.")
             return 0
         if a.command == "open":
             credential = json.loads((settings.runtime_dir / "launch.json").read_text())

{tofscope-0.1.0 → tofscope-0.1.2}/src/tofscope/science/signals.py

@@ -17,7 +17,7 @@ def _integer(value):
 
 
 def interval_label(intervals):
-    return ' ∪ '.join(f'{low:.4f}–{high:.4f}' for low,high in intervals)+' Th'
+    return 'm/z ' + ' ∪ '.join(f'{low:.4f}–{high:.4f}' for low,high in intervals)
 
 
 @dataclass(frozen=True)