AstroFrame/README.md
Elijah a8e7a87b94
All checks were successful
Release AstroFrame / packages (push) Successful in 1m13s
Release 1.1.0 with adaptive RAM and interactive previews
Replace fixed process, heap, frame and worker caps with physical RAM admission and CPU-scaled concurrency. Round Windows job budgets to native allocation boundaries. Add persistent cursor-centered zoom, drag and reset, fresh launches, cerulean update indicators and grey native startup backgrounds. Validate with isolated fixtures and a fake updater.
2026-10-04 09:33:44 -07:00

84 lines
10 KiB
Markdown

# AstroFrame
An independent Windows/Linux desktop application for selecting astrophotography light frames before Siril. The spatial-reference engine uses deterministic image measurements, aligned session background models and forced stellar photometry. It is experimental: general classification accuracy and stack parity have **not** been established.
## Run on Windows
For packaged installations, run `AstroFrame-win-x64-Setup.exe`. Linux users can use `AstroFrame-linux-x64.AppImage` and the accompanying `install-linux.sh` for an application-menu entry. Both target x64 PCs. See [installation and releases](docs/releases.md) for Debian/Arch prerequisites and package-building instructions.
**Settings → Updates** shows the installed version and update status, with automatic and manual checks. Installed packages check the [public repository releases](https://git.elijahkuntz.com/Elijah/AstroFrame/releases) on startup and every six hours. A newer stable release turns Settings cerulean blue and adds an update indicator. **Install update and restart** downloads the release package and restarts after saving; active analysis/export must finish first. Preferences and projects survive updates. Git pushes become app updates only after a versioned release and its packages are published.
Open `artifacts/AstroFrame/AstroFrame.Desktop.exe`. This self-contained build does not require Python, a GPU, or a separate .NET installation. Keep the entire application folder together.
Analysis scales its memory budget with physical RAM and samples available headroom before admitting each frame. It reserves one quarter of RAM (up to 8 GiB) for the OS and other applications, counts concurrent frame reservations atomically, and stops safely after 20 seconds of sustained pressure once active frames finish. Windows enforces a process ceiling of physical RAM minus that reserve; the old fixed process, heap and per-frame caps have been removed. Per-frame estimates include working buffers and are bounded by half the machine budget, with the existing 100 MP FITS limit retained. Up to 16 workers are selected from CPU capacity, leaving two logical processors unused where possible. Only one ordinary desktop instance runs at a time. The page file is not treated as available physical RAM. Windows uses software rendering.
`Open Sample Survey.cmd` opens all supplied datasets, including NGC 7000. `Open NGC 7000.cmd` opens its separate project. Normal launches start with an empty session. Saved projects and decisions remain available when explicitly reopened or when their source folder is selected again. Reopening a completed project uses saved measurements. New display caches are generated on demand for older projects without recomputing classifications; subsequent previews use cached linear thumbnails. An explicit project can also be opened with `AstroFrame.Desktop.exe --project "project folder"`.
To analyze another dataset, choose **Analyze lights**, select the folder containing original `.fit`, `.fits`, or `.fts` files, and wait for analysis. Subfolders are included. New projects are saved separately under `%LOCALAPPDATA%/AstroFrame/Projects/` on Windows (the equivalent local application-data location on Linux). The input folder is not used for project storage.
## Review
- Select an observing session from the selector above the workspace. The Graphite palette uses neutral charcoal and silver with muted decision colors. The Atlas layout puts exposures on the left, a large preview in the center, and quality graphs and evidence on the right. Baselines never mix targets, exposure settings, gain, filter, camera, dimensions, or Bayer patterns. Gaps over two hours and coordinate changes split sessions.
- Select a quality measurement and click the graph to inspect an exposure. One graph shows the selected metric, including stellar flux when selected. Capture order uses UTC timestamps; gaps between sessions are marked rather than drawn to elapsed-time scale.
- Filter **REVIEW** or **REJECT**, and sort by concern, star count, stellar flux, or FWHM.
- Toggle **Compare nearby** and **Spatial overlay**. Red fill shows transient sky structure in the aligned reference grid. Region outlines show forced stellar flux loss. Previews have independent display stretches; use measured flux to compare transparency.
- Use **Frame view** for an area-averaged exposure preview, or **Nebula view** for additional averaging of faint diffuse structure. Adjust **Stretch** to brighten the display. These controls never affect measurements, classifications or original files.
- Scroll the mouse wheel over either preview to zoom around the cursor, and hold the left mouse button to drag. Zoom and image position persist across frames and are shared with the nearby comparison. **Reset view** restores the fitted, centered image. These display controls do not alter source pixels or analysis.
- Press **1**, **2**, **3** for KEEP, REVIEW, REJECT. Decisions save and advance. **J/K** navigates. **Reset** restores the automatic decision. **Ctrl+Z** undoes a manual decision.
- Decision evidence and measurements remain visible below the quality graph. Hover over an evidence line to read its full technical detail, and scroll the panel for additional measurements. Preview stretch and manual decisions sit below the image. Existing notes remain in saved projects and exports; the note editor has been removed. Automatic decisions and human overrides remain separate.
KEEP means consistent measurements; it does not certify a perfect frame. REVIEW means a substantial deviation or measurement uncertainty. REJECT requires strong, coherent transient sky structure, agreement between cloud/flux/star-loss measurements, severe combined morphology degradation, or catastrophic star disappearance. Small ellipticity variations alone do not trigger review.
The earlier engine missed obvious clouds and falsely reviewed a clear frame. Its rolling background baselines and detection-only flux measurements have been replaced. Analysis-version changes request reanalysis while preserving manual decisions. Display changes have their own cache version, so preview upgrades do not invalidate quality measurements.
## Export to Siril
**Export accepted** writes sequentially named original FITS files into an empty output directory outside the source tree. KEEP frames are included by default; unresolved REVIEW frames are an explicit option. Hardlinks avoid duplicate image storage on compatible filesystems; otherwise a byte-for-byte copy is used. Copies are available as an explicit choice.
Choose the current session, one target across all sessions, or the entire project. A multi-target export uses separate target directories, preventing unrelated fields from being mixed into a single Siril input folder.
Hardlinks share file contents with originals. AstroFrame never writes FITS pixels. Process exported inputs into separate outputs in Siril; use copies for tools that overwrite their inputs. Cancellation retains completed exported files and removes incomplete copy files. Choose a new empty directory for another export.
Exports include `accepted.txt` with accepted output paths and `decisions.csv` with all decisions, timestamps, exposure durations, and review notes. Siril can load the exported FITS directory normally. The CSV is an audit manifest, not a native Siril sequence.
## Build and validate
The [server release workflow](.forgejo/workflows/release.yml) builds and publishes both platforms when a stable version tag such as `v1.0.3` is pushed. Set the matching version with `./packaging/Set-Version.ps1 -Version 1.0.3`, commit/push the source, then push the tag. It uses the existing Docker runner and automatically supplied Forgejo token. Pushes and manual Actions runs on `main` check the build without publishing. Version 1.0.2 fixes the spatial preview overlay; see [release notes](docs/release-notes/1.0.2.md) and [automatic releases](docs/releases.md#automatic-server-releases).
Requires a .NET 8 SDK. `Build.ps1` uses the workspace-local SDK if present, otherwise `dotnet` from PATH:
```powershell
./Build.ps1 -Test
./Build.ps1 -Publish
./Build.ps1 -Package
```
Standard builds on Windows or Linux:
```sh
dotnet build src/AstroFrame.Desktop -c Release
dotnet run --project tests/AstroFrame.Validation -c Release
dotnet publish src/AstroFrame.Desktop -c Release -r linux-x64 --self-contained true -o artifacts/AstroFrame-linux
```
The Windows build and rendered layout were tested here. Linux uses Avalonia's X11 backend and bundled Skia/Harfbuzz binaries; packaged Linux startup, settings rendering, installation and self-updates were also exercised under Ubuntu WSL. Debian/Arch desktop acceptance remains to be checked directly. A Linux desktop with the usual X11/font/ICU libraries is required; see [installation and releases](docs/releases.md).
Prebuilt Linux files are in `artifacts/AstroFrame-linux`. On Linux, run `chmod +x AstroFrame.Desktop` before launching if executable permissions were lost during transfer. RAM admission and physical headroom monitoring also apply on Linux; the Windows kernel job ceiling does not.
Batch analysis and review-label summaries:
```sh
dotnet run --project tests/AstroFrame.Validation -c Release -- analyze "Sample Data" "projects/Sample Survey"
dotnet run --project tests/AstroFrame.Validation -c Release -- labels "projects/Sample Survey"
```
See [desktop layout](docs/desktop-design.md), [analysis design](docs/analysis-design.md), [observed dataset findings](docs/dataset-findings.md), [NGC 7000 preview and performance findings](docs/ngc7000-findings.md), and [stack validation protocol](docs/validation-protocol.md).
Real-image regression commands (NumPy is needed only for the diagnostic experiment, not these checks):
```sh
python tools/check_real_frames.py "projects/Sample Survey/project.json"
python tools/check_visual_holdout.py "projects/Sample Survey/project.json"
```
The first check covers the five exposures explicitly identified by the owner. The second is a provisional cloud-only screen of 56 fixed time samples, selected before the new decisions. Neither establishes stack parity.