TiānWén (天文)

TianWen is a free, open-source astronomical imaging suite for .NET. It manages cameras, mounts, focusers, filter wheels, and guiders via ASCOM, Alpaca, ZWO, QHYCCD, Meade, Skywatcher, OnStep, and iOptron protocols, with first-class support for multi-OTA (dual rig) setups that are difficult or expensive to achieve with existing software.

It ships as a NuGet library (TianWen.Lib), a cross-platform CLI with interactive TUI (TianWen.Cli), a headless REST API server (TianWen.Server) for remote operation via Touch N Stars, a standalone FITS viewer (TianWen.UI.FitsViewer), and an integrated N.I.N.A.-style GUI (TianWen.UI.Gui).

Features

• Device Management:

  • Supports various device types such as Camera, Mount, Focuser, FilterWheel, Switch, and more.
  • Provides interfaces for device drivers and serial connections.
  • Includes a profile virtual device for managing device descriptors.

• Profile Management:

  • Create and manage profiles.
  • Serialize and deserialize profiles using JSON.
  • List existing profiles from a directory.

• Image Processing:

  • Read and write FITS files.
  • Analyze images to find stars and calculate metrics like HFD, FWHM, SNR, and flux.
  • Generate image histograms and background levels.
  • Debayer OSC images (AHD, bilinear) to color or synthetic luminance.
  • Scale-invariant star detection works on both raw ADU and normalized [0,1] images.

• FITS Viewer (TianWen.UI.FitsViewer):

  • GPU-accelerated stretch (MTF) with per-channel, linked, and luma modes.
  • GPU bilinear Bayer demosaic: raw mosaic uploaded as single texture, debayered per-pixel in the fragment shader. No CPU debayer needed.
  • HDR compression via Hermite soft-knee in the fragment shader.
  • Automatic star detection with HFD-sized overlay circles and status bar metrics.
  • Contrast boost with star-masked background estimation for clean nebula enhancement.
  • WCS coordinate grid overlay with RA/Dec labels.
  • Celestial object annotation overlay (NGC, IC, Messier, etc.) when plate-solved.
  • Per-channel histogram overlay (R/G/B colored) with log/linear scale toggle and stretch-aware bin remapping.
  • Plate solving via ASTAP or astrometry.net.
  • Multi-source: opens FITS, TIFF, and SER planetary video; a SER auto-switches to frame playback (off-thread decode-ahead, transport scrub/play/pause, timestamp readout).
  • Live planetary lucky-imaging stack: a RAW/STACK toggle runs a rolling-window stack of a SER that follows the playhead (sharpness-graded, globally aligned), with Registax-style 6-layer wavelet-sharpen sliders. All off the render thread, so slider adjustments stay instant regardless of stack time.
  • Manual per-channel white-balance sliders + gray-world Auto, shared across FITS / TIFF / SER.

• External Integration:

  • Interfaces for external operations such as logging, TimeProvider based time management, and file management.
  • Connect to external guider software using JSON-RPC over TCP.

Installation

Library

You can install the TianWen library via NuGet:

dotnet add package TianWen.Lib

Runtime prerequisites

The release archives are self-contained native AOT builds; no .NET install needed, and the SDL3 native is bundled. What they cannot bundle is the Vulkan loader, which has to come from the OS. This applies to the two GPU-rendered apps (tianwen-gui, tianwen-fits); tianwen-cli and tianwen-server render in the terminal or not at all, and need none of it.

Platform	Also needs
Windows (win-x64, win-arm64)	nothing: vulkan-1.dll ships with any modern GPU driver
Linux (linux-x64, linux-arm64)	libvulkan.so.1 + an ICD (mesa-vulkan-drivers; that package also carries the lavapipe software rasteriser for headless boxes)
macOS (osx-arm64, osx-x64)	MoltenVK (Vulkan-on-Metal)

tianwen-gui bundles its own fonts (DejaVuSans.ttf, Noto-COLRv1.ttf). tianwen-fits resolves a system font instead, via FontResolver.ResolveSystemFont, so on a minimal Linux image it also needs a font package; fonts-dejavu-core on Debian/Ubuntu, font-dejavu on Alpine. Without one it starts and renders the image but draws no text.

Server (Headless / Remote)

Pre-built native AOT binaries of tianwen-server are available from GitHub Releases:

Platform	Architecture	Artifact
Windows	x64	tianwen-server-win-x64.tar.gz
Windows	ARM64	tianwen-server-win-arm64.tar.gz
Linux	x64	tianwen-server-linux-x64.tar.gz
Linux	ARM64	tianwen-server-linux-arm64.tar.gz
macOS	x64	tianwen-server-osx-x64.tar.gz
macOS	ARM64	tianwen-server-osx-arm64.tar.gz

tianwen-server                    # Listens on http://0.0.0.0:1888
tianwen-server --port 8080        # Custom port

The server exposes both a native multi-OTA REST API (/api/v1/) and a ninaAPI v2 compatibility shim (/v2/api/) that works with Touch N Stars for mobile control. WebSocket push events are available at /api/v1/events (camelCase) and /v2/socket (PascalCase).

CLI

Pre-built native AOT binaries of TianWen.Cli are available from GitHub Releases:

Platform	Architecture	Artifact
Windows	x64	tianwen-cli-win-x64.tar.gz
Windows	ARM64	tianwen-cli-win-arm64.tar.gz
Linux	x64	tianwen-cli-linux-x64.tar.gz
Linux	ARM64	tianwen-cli-linux-arm64.tar.gz
macOS	x64	tianwen-cli-osx-x64.tar.gz
macOS	ARM64	tianwen-cli-osx-arm64.tar.gz

CLI Reference

The tianwen CLI (TianWen.Cli) provides non-interactive commands and a full-screen tabbed TUI (tianwen tui).

Global Options

Option	Description
-a, --active <name>	Select active profile by name or ID
<path>	FITS file or directory to view (shorthand for view <path>)

Profile Management

tianwen profile list                           # List all profiles
tianwen profile create <name>                  # Create empty profile
tianwen profile delete <nameOrId>              # Delete a profile

Profile: Mount & Site

tianwen profile set-mount <deviceId>           # Set the mount device
tianwen profile set-site --lat 48.2 --lon 16.3 [--elevation 200]
                                               # Set observing site location
tianwen profile set-mount-port --port COM3 [--baud 9600]
                                               # Set serial port/baud on mount

Profile: Guider

tianwen profile set-guider <deviceId>          # Set the guider (PHD2 or built-in)
tianwen profile set-guider-camera <deviceId>   # Set dedicated guider camera
tianwen profile set-guider-focuser <deviceId>  # Set guider focuser
tianwen profile set-oag-ota <index>            # Set which OTA hosts the OAG
tianwen profile set-guider-options [--pulse-guide-source Auto|Camera|Mount]
                                  [--reverse-dec-after-flip true|false]

Profile: OTA (Optical Tube Assembly)

tianwen profile add-ota <name> --focal-length <mm> --camera <deviceId>
    [--focuser <id>] [--filter-wheel <id>] [--cover <id>]
    [--aperture <mm>] [--optical-design Refractor|Newtonian|SCT|...]
tianwen profile remove-ota <index>
tianwen profile update-ota <index> [--name <name>] [--focal-length <mm>]
    [--aperture <mm>] [--optical-design <design>]
    [--prefer-outward true|false] [--outward-is-positive true|false]

Profile: Camera & Filters

tianwen profile set-camera-defaults --ota <N> [--gain <N>] [--offset <N>]
tianwen profile set-filters --ota <N> --filters Luminance:0 Ha:+21 OIII:-3 SII:+25

Filter specs are Name:FocusOffset pairs. Offset is in focuser steps relative to the reference filter (typically Luminance=0).

Profile: Quick Device Add

tianwen profile add <deviceId> [--ota <N>]     # Add device by type auto-detection

Device Discovery

tianwen device list                             # List cached devices
tianwen device discover                         # Force rediscovery

FITS Viewer (Terminal)

tianwen view <path>                             # Render to terminal (Sixel or ASCII)
tianwen <path>                                  # Shorthand for view <path>

Planetary Stacking

Stack a planetary SER video into a sharpened lucky-imaging master (linear + sharpened FITS + a high-key PNG):

Every default is the measured best of the planetary restoration work (docs/plans/planetary-restoration.md, the enhanced pipeline): frames graded by their gradient, half kept for a sharpened master and a tenth for a plain one, registered by plain cross-correlation against a stack of the best 1,000, resampled by Lanczos-3, and a run of Jupiter or Saturn de-rotated once the planet's turn moves its disk's middle a pixel. Given the telescope (--telescope or --aperture-mm), the sharpened master's gains are derived from the stack itself, through the limb's edge against the telescope's diffraction, held at the sky and, outside the limb, never brighter than the stack; without it the default preset sharpens with the limb kept as stacked. --legacy stacks and sharpens as before.

tianwen planetary stack <ser-file>... [-o <dir>]
    --keep <0..1>                # fraction of sharpest frames to keep (default 0.5 sharpened, 0.1 with --no-sharpen)
    --quality <gradient|laplacian>
    --correlation <plain|whitened>  --interpolation <lanczos3clamped|lanczos3|bilinear>  --reference-frames <n>
    --derotate / --no-derotate   # force or forbid de-rotation; --planet <jupiter|saturn> when the file name does not say
    --legacy                     # the recipe before the enhanced pipeline: Laplacian, a quarter, phase correlation, bilinear
    --truth <file>               # score every master against a synthetic capture's truth (planetary degrade)
    --drizzle <scale>            # Bayer drizzle, e.g. 1.5 (sub-Bayer resolution); --drizzle-global for whole-disk
    --telescope <newtonian|maksutov>  --aperture-mm <mm> --obstruction <0..1>   # the pupil the derived sharpening needs
    --wavelength <nm[,nm,nm]>    # the filter's (550 mono, 610,530,460 colour by default); --limb-fix <bounded|floored|limbchannel|feathered|plain>
    --sharpen-preset <default|bandpass|combo>   # a fixed profile instead; or --sharpen-gains "g1,g2,..."; --no-sharpen to skip
    --global                     # whole-disk align only (skip alignment-point mesh)
    --png-gamma <g>              # high-key PNG midtones lift (default 0.75); --no-png to skip
    # advanced: --ap-spacing / --max-ap / --ap-patch / --mesh-spacing / --align-tile

tianwen planetary sharpen <master.fits> sharpens a master again the same way without restacking it (--limb-fix all and a synthetic capture's --truth compare the limb fixes). The limb options are four families with one name on every verb: the limb fit (--fit-k, --fit-channels), the edge the gains are read off (--edge-reach, --edge-rings), the gains' own fit (--gains-fit) and what a limb pixel takes (--limb-fix, --limb-floor).

For interactive planetary work (live rolling-window stack + wavelet sliders), open the SER in the FITS viewer (tianwen-fits <file.ser>) and press K. Shift+K (or the info panel's Best stack button) stacks the whole capture as planetary stack does, in the background, writes both masters beside it and opens the sharpened one; the panel's aperture and design give the derived sharpening its telescope, and are remembered. The planet (and a mono capture's filter) come from the capture's name, or the panel's choice where the name gives none, since without a planet the sharpening is only a preset. A planetary master opens in the planetary stretch, the one planetary stack's PNG preview is drawn with (also on the stretch menu for any frame). In the stacked view, Derive works out the derived sharpening's gains for the master on show (about half a minute) and seeds the six wavelet sliders with them; the GUI's planetary capture has the same button, its telescope taken from the profile.

Observation Planner

tianwen plan                                    # Tonight's best targets (requires profile)

Interactive TUI

tianwen tui                                     # Full-screen tabbed TUI (alternate screen)

The TUI provides an Equipment tab, Planner with altitude charts, Session configuration, Live Session monitor with Sixel preview, and Guider tab with guide error sparklines (RA/Dec), RMS stats, and settle progress.

Example: Building a Dual-Scope Rig

tianwen profile create "Dual Scope"
tianwen -a "Dual Scope" profile set-mount FakeMount1
tianwen -a "Dual Scope" profile set-site --lat 48.2 --lon 16.3 --elevation 200
tianwen -a "Dual Scope" profile set-guider FakeGuider1
tianwen -a "Dual Scope" profile set-guider-camera FakeCamera1

# OTA 0: widefield
tianwen -a "Dual Scope" profile add-ota "Samyang 135" \
    --focal-length 135 --camera FakeCamera1 --focuser FakeFocuser1
tianwen -a "Dual Scope" profile set-camera-defaults --ota 0 --gain 100

# OTA 1: narrowband with filter wheel
tianwen -a "Dual Scope" profile add-ota "RC8" \
    --focal-length 1625 --camera FakeCamera2 --focuser FakeFocuser2 \
    --filter-wheel FakeFilterWheel1 --aperture 203 --optical-design Astrograph
tianwen -a "Dual Scope" profile set-filters --ota 1 \
    --filters Luminance:0 Ha:+21 OIII:-3 SII:+25 R:+20 G:0 B:-15
tianwen -a "Dual Scope" profile set-camera-defaults --ota 1 --gain 120 --offset 10

# Plan tonight's observations
tianwen -a "Dual Scope" plan

FITS Viewer

Pre-built native AOT binaries of TianWen.UI.FitsViewer are available from GitHub Releases:

Platform	Architecture	Artifact
Windows	x64	tianwen-fits-win-x64.tar.gz
Windows	ARM64	tianwen-fits-win-arm64.tar.gz
Linux	x64	tianwen-fits-linux-x64.tar.gz
Linux	ARM64	tianwen-fits-linux-arm64.tar.gz
macOS	x64	tianwen-fits-osx-x64.tar.gz
macOS	ARM64	tianwen-fits-osx-arm64.tar.gz

Needs a Vulkan loader; see Runtime prerequisites.

Keyboard Shortcuts

Key	Action
T	Cycle stretch mode (none / per-channel / luma)
S	Toggle star overlay
C	Cycle channel display
D	Cycle debayer algorithm
V	Toggle histogram overlay
Shift+V	Toggle histogram log scale
F / Ctrl+0	Zoom to fit
R / Ctrl+1	Zoom 1:1
Ctrl+2..9	Zoom 1:N
Mouse wheel	Zoom in viewport

Interactive TUI (tianwen tui)

The interactive TUI provides a tabbed interface for the full imaging workflow:

Tab	Key	Description
Equipment	1 / F1	Profile management, device discovery, OTA/filter configuration
Planner	2 / F2	Tonight's best targets with altitude chart, handoff sliders, scheduling
Session	3 / F3	Session configuration (cooling, guiding, horizon, focus), per-OTA camera settings
Live	4 / F4	Live session monitor: exposure progress, cooler sparklines, mount status, Sixel image preview
Guider	5 / F5	Guide error sparklines (RA/Dec), RMS stats, settle progress

The live session tab includes a real-time Sixel image preview with viewer controls:

Key	Action
T	Cycle stretch mode (None / Unlinked / Linked / Luma)
B	Cycle curves boost
+/-	Cycle stretch parameter presets
F	Zoom to fit
R	Zoom 1:1
Escape	Abort session (with confirmation)

GUI (TianWen.UI.Gui)

The integrated GUI provides a N.I.N.A.-style interface with GPU-accelerated Vulkan rendering, including all the same tabs as the TUI plus a full FITS image viewer with real-time stretch, star overlay, WCS grid, and histogram.

Pre-built native AOT binaries are available from GitHub Releases:

Platform	Architecture	Artifact
Windows	x64	tianwen-gui-win-x64.tar.gz
Windows	ARM64	tianwen-gui-win-arm64.tar.gz
Linux	x64	tianwen-gui-linux-x64.tar.gz
Linux	ARM64	tianwen-gui-linux-arm64.tar.gz
macOS	x64	tianwen-gui-osx-x64.tar.gz
macOS	ARM64	tianwen-gui-osx-arm64.tar.gz

Needs a Vulkan loader; see Runtime prerequisites.

Architecture

Design deep-dives live under docs/architecture/:

• Device architecture: URI-addressed devices, the driver-factory hierarchy, and the combined device manager.
• Image pipeline & buffer lifecycle: camera → ChannelBuffer → Image ownership, the live-session data flow, and the GPU debayer/stretch path.
• Driver resilience on the hot path: ResilientCall, fault counters, proactive reconnect.
• FOV obstruction detection: scout frames, altitude-nudge disambiguation, trajectory-aware waits.
• Fake disturbance model: the believed/true pointing split used by the fake drivers for unattended end-to-end testing.

Per-feature implementation plans + status are in docs/plans/ (e.g. the planetary lucky-imaging stack in planetary-stacking.md); CLAUDE.md is the contributor architecture guide.

License

GNU Affero General Public License v3.0 or later (LICENSE), plus one additional permission under section 7 (LICENSE.EXCEPTION).

What that means in practice:

• Build on it freely, including commercially. You may use, modify, sell and deploy TianWen. The one condition is reciprocity: if you convey it, or offer a modified version to users over a network, those users get the corresponding source under these same terms. TianWen.Lib is published on NuGet to be consumed; it is not available for closed-source products.
• The section 7 permission exists so TianWen can talk to hardware. Cameras and mounts are only reachable through proprietary vendor SDKs (QHYCCD, ZWO, Canon EDSDK, ASCOM drivers, vendor ONNX execution providers), which nobody but their vendors can relicense. The permission covers linking those and nothing else; it does not waive the source obligation.
• Section 13 is the reason for Affero rather than plain GPL. TianWen ships a headless server, a REST/WebSocket API and multi-rig remote mirroring, so running it as a hosted service is a likely way it gets used. Plain GPL treats network use as neither conveying nor distribution and would ask nothing of a hosted deployment.
• A runtime service keeps its own terms, which this licence cannot change. The default weather provider is Open-Meteo's keyless free API. Its data is CC BY 4.0, and the free tier is for non-commercial use only; Open-Meteo counts subscriptions, advertising and integration into a commercial product as commercial. TianWen itself qualifies: it is free, with no ads. A product built on TianWen that charges or shows ads needs Open-Meteo's paid API plan, which the driver does not support yet (it sends no API key), or the OpenWeatherMap provider with its own key. The viewer's Store listing (Astro Photo Viewer) makes no weather call at all.

Third-party methods, data and programs TianWen builds on are credited in NOTICE. Releases before 2026-08-11 were made under LGPL-2.1 and remain available under those terms.