astro-viewer
v3.3.0
Published
Astrobrowser 3d engine.
Maintainers
fab77Readme
🌌 AstroViewer
AstroViewer is a lightweight 3D engine for HiPS (Hierarchical Progressive Surveys) visualisation and exploration, written in TypeScript and WebGL.
It powers the next generation of Astrobrowser and provides a simple API for embedding 3D HiPS viewers, catalogue overlays, footprints, and camera/navigation controls in any web project.
Licensing
AstroViewer is distributed under a dual-license model:
- a commercial license for proprietary or revenue-generating use
- a separate non-commercial, source-available license for personal, academic, research, evaluation, or other non-commercial use
The non-commercial option is not an OSI open source license. See
LICENSE.md, LICENSE-COMMERCIAL.md, and LICENSE-NONCOMMERCIAL.md for the
repository-level licensing structure.
The commercial posture of astro-viewer also depends on the licensing alignment
of its first-party dependency chain. See DEPENDENCY-LICENSING.md.
📦 Bundles
AstroViewer builds the following bundles in the dist/ directory:
| File | Description |
|------|--------------|
| astroviewer.js | UMD bundle for browser environments |
| astroviewer.min.js | Minified UMD bundle |
| astroviewer.cjs | CommonJS build for Node.js |
| *.map | Source maps for debugging |
🪐 Quick Start (Browser)
Copy the bundle into your project and link it in your HTML page:
<script src="./javascripts/astroviewer.js"></script>Then you can use the global astroviewer object directly.
Here is a minimal example that loads a HiPS survey and starts the viewer.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>AstroViewer Demo</title>
<script src="./javascripts/astroviewer.js"></script>
</head>
<body onload="run();">
<canvas id="astrocanvas"></canvas>
<script>
let window.AstroAPI = undefined;
async function run() {
const AC = new astroviewer.AstroViewer();
window.AstroAPI = AC;
const hipsUrl = "https://alasky.cds.unistra.fr/DSS/DSSColor/";
const resp = await fetch(hipsUrl + "properties");
const propsText = await resp.text();
const desc = new astroviewer.HiPSDescriptor(propsText, hipsUrl);
window.AstroAPI.activateHiPS(desc);
window.AstroAPI.run();
}
</script>
</body>
</html>🧩 Node.js / TypeScript Usage
You can also use AstroViewer as a Node module:
npm install astro-viewerThen import from your code:
// ESM
import { AstroViewer, HiPSDescriptor } from 'astro-viewer';
// or CommonJS
const { AstroViewer, HiPSDescriptor } = require('astro-viewer');🧪 Development Web Interface
AstroViewer includes a development web UI to explore features such as HiPS loading, FoV control, catalogue management, and footprints.
You need Node.js ≥ 22 installed.
Clone this repository and run:
npm run allThis command will:
- Compile the TypeScript source
- Build the bundles
- Prepare the web testing interface
- Start a local web server
You should see output similar to:
Serving HTTP on 0.0.0.0 port 8080Then open one of the links in your browser (e.g. http://127.0.0.1:8080) to start exploring AstroViewer.
🛠️ Build Scripts
| Command | Description |
|----------|--------------|
| npm run clean | Remove dist and lib-esm directories |
| npm run dev | Build in development mode and watch for changes |
| npm run prod | Production build (minified and with source maps) |
| npm run web | Copy bundles and assets into the public folder |
| npm run all | Full build + launch development web UI |
📚 API Overview
Main exported classes and utilities:
AstroViewer— main application controllerHiPSDescriptor— handles HiPS metadata and configurationFootprintSetGL— renders observation footprintsCatalogueGL— renders astronomical cataloguesFoVand related geometry/color-map utilities — camera and rendering helpers
🔧 API Reference & Usage
Below is a practical overview of the most commonly exposed methods via the UMD global astroviewer (browser) or the module exports (Node/ESM).
Note: The bundles only include what is exported from
src/index.ts. If your build exposes additional methods, follow the same patterns shown here.
Core Lifecycle
new AstroViewer(options?)
Create the viewer controller.
// Browser (UMD)
const AC = new astroviewer.AstroViewer({
canvas: document.getElementById('astrocanvas'), // optional; defaults to #astrocanvas
antialias: true // optional
});// Node/ESM
import { AstroViewer } from 'astro-viewer';
const AC = new AstroViewer();run()
Start the render loop and event handling.
AC.run();HiPS Datasets
activateHiPS(descriptor: HiPSDescriptor)
Activate a HiPS dataset for rendering.
const hipsUrl = "https://alasky.cds.unistra.fr/DSS/DSSColor/";
const props = await (await fetch(hipsUrl + "properties")).text();
const desc = new astroviewer.HiPSDescriptor(props, hipsUrl);
AC.activateHiPS(desc);toggleInsideSphere()
Toggle the point-of-view (outside vs inside the HiPS sphere).
AC.toggleInsideSphere(); // outside <-> insideCamera & Navigation
goTo(raDeg: number, decDeg: number)
Move the camera to a sky coordinate (ICRS).
AC.goTo(287.0, 12.5);Overlays & Grids
toggleHealpixGrid()
Show/hide the HEALPix grid overlay.
AC.toggleHealpixGrid();Catalogues
showCatalogue(catalogue: CatalogueGL)
Render a catalogue layer.
AC.showCatalogue(cat);hideCatalogue(catalogue: CatalogueGL, isVisible: boolean)
Toggle visibility without removing it.
AC.hideCatalogue(cat, false); // hide
AC.hideCatalogue(cat, true); // showdeleteCatalogue(catalogue: CatalogueGL)
Remove a catalogue layer completely.
AC.deleteCatalogue(cat);changeCatalogueColor(catalogue: CatalogueGL, hexColor: string)
Change the colour of rendered catalogue points/sources.
AC.changeCatalogueColor(cat, "#ff8800");Footprints (Observations)
The following methods mirror the catalogue API, but for observation footprints.
showFootprintSet(footprintSet: FootprintSetGL)
const footprints = tapRepo.obsList.find(o => o.name === "observations.some_collection");
AC.showFootprintSet(footprints);hideFootprintSet(footprintSet: FootprintSetGL, isVisible: boolean)
AC.hideFootprintSet(footprints, false); // hide
AC.hideFootprintSet(footprints, true); // showdeleteFootprintSet(footprintSet: FootprintSetGL)
AC.deleteFootprintSet(footprints);changeFootprintSetColor(footprintSet: FootprintSetGL, hexColor: string)
AC.changeFootprintSetColor(footprints, "#00ffaa");Events & Utilities (if exported)
Depending on your build, you may also have helpers like:
getCenterCoordinates()
Return the current ICRS center of the viewport.
const coords = AC.getCenterCoordinates();toggleInsideSphere()
AC.toggleInsideSphere();If a method above is not present in your build, it means it’s not exported by
src/index.ts.
To inspect what’s available in the UMD build, open your page and run:console.log(Object.keys(astroviewer)); console.log(Object.getOwnPropertyNames(astroviewer.AstroViewer.prototype));
📜 License
This repository uses a dual-license model.
Commercial use requires a separate written agreement.
Non-commercial use is available under the source-available terms in LICENSE-NONCOMMERCIAL.md.
See also LICENSE.md and LICENSE-COMMERCIAL.md.