The AAS WorldWide Telescope WebGL engine
The “WebGL engine” of the AAS WorldWide Telescope (WWT) is a JavaScript/TypeScript framework that powers the Web-based versions of the WWT visualization software, as exemplified by the WWT web client.
Learn more about WWT here.
Developers’ quick start
- Check out this repository to a machine with Node.js and npm.
git submodule update --init
npx lerna bootstrap
- Either build or obtain the file
engine/wwtlib/bin/wwtlib.js
as described below. npm run lint
(uses ESLint)npm run build
creates:npm run test
(mainly uses mocha and chai)npm run doc
(uses TypeDoc)
Repository structure
This repository is a monorepo containing the source for several interlocking TypeScript packages that together comprise the core of the WWT web framework. The most important subdirectories are:
@wwtelescope/engine
inengine/
, the core engine code transpiled from C# and wrapped in TypeScript annotations@wwtelescope/engine-vuex
inengine-vuex/
, a higher-level package that turns the engine into a reusable Vue/Vuex component@wwtelescope/embed
inembed/
, a web application that turns WWT into a configurable, embeddable iframe- The narrative documentation in
docs/
README files inside the individual subdirectories give more information about their contents and development workflows.
engine/wwtlib/bin/wwtlib.js
file
The There’s one big wrinkle to the build process: the bulk of the engine code is
actually C# code in the directory engine/wwtlib/
. It’s forked from
wwt-windows-client and is transpiled into JavaScript using an unreleased
version of ScriptSharp, an unmaintained tool. Fortunately, that build process
results in a single file, engine/wwtlib/bin/wwtlib.js
, that you can download
from our CI systems if you’re not able to perform a Visual Stdio build.
To build the engine library starting from C#:
- You need a Windows machine with Visual Studio 2017. Other versions of Visual Studio might also work.
- Open the
engine/WebGLEngine.sln
solution and build the project it contains. This should create the fileengine/wwtlib/bin/wwtlib.js
.
Otherwise, check out the latest continuous integration build of this repository,
download the scriptsharp
artifact, and copy the wwtlib.js
file to the
location given above. If you want to change the C# code, you can file a pull
request and access the artifacts associated with your pull request builds.
Building the rest of the code
Besides the creation of the file engine/wwtlib/bin/wwtlib.js
, virtually
everything in this repository is built using standard Node.js/npm tooling.
These tools must be installed before you can do anything else.
The multi-package structure of this repository is dealt with using Lerna. This means that once you’ve checked out the code and install npm, the setup sequence is:
- Run
git submodule update --init
to pull in needed Git submodules, namely the documentation theme indocs/themes/wwtguide
. - Run
npx lerna bootstrap
to install all of the project dependencies and set up the necessary cross-links between individual packages in this repository.
Once setup is complete, the following commands will be useful:
npm run build
to build the subpackagesnpm run lint
to lint the subpackages (using eslint with TypeScript extensions)npm run test
to run the tests (mainly using mocha and chai)npm run doc
to build most of the documentation (using TypeDoc) — but see below
Running these commands from inside package subdirectories unfortunately will
not work due to the centralized node_modules
directory we use with Lerna. To
run the lint
command only for the engine-types
submodule, run:
npx lerna run --scope @wwtelescope/engine-types lint
(The --scope
argument can be a glob expression if you want to run on a subset
of packages.)
Building the full documentation
Documentation is maintained in the docs/
subdirectory. The documentation is a
Frankenstein combination of the autogenerated API documentation and narrative
material written in CommonMark Markdown. The final HTML is assembled with the
static site generator Zola,
- Zola is fast and self-contained and ridiculously easy to install.
- The
npm run doc
command will install the autogenerated documentation intodocs/static/
- Running
zola build
in thedocs
subdirectory will assembled the final HTML intodocs/public/
. - The command
zola check
will check the narrative docs for broken links. - The command
zola serve
will serve the documentation using a local server with autoreload.
Continuous Integration and Deployment
This repository uses semantic-release with the semantic-release-monorepo extension to automate release workflows. This automation is essential to the smooth and reproducible deployment of the WWT web services.
The basic paradigm is that merges to the beta
or master
branches will
automatically trigger processing by semantic-release that will determine if
any changes have been made that require a new release in any of the subpackages.
If so, semantic-release will create a new Git commit that updates the package
version and changelog, publish an NPM package, create a Git tag, publish
everything to GitHub, and create a GitHub release record.
New releases are triggered by looking at Git commit messages, which should
follow the Angular guidelines. The first line of each
commit should have the format {type}({scope}): {subject}
, with one of the
following types:
build
chore
ci
docs
feat
fix
perf
refactor
style
test
Breaking changes are indicated by a line starting with BREAKING CHANGE:
in
the commit message body.
Versioning on the master
branch follows semantic versioning
strictly:
fix
changes force a bump in the micro version numberfeat
changes force a bump in the minor version number (and reset of the micro)- Breaking changes force a bump in the major version number.
On the beta
branch, versions are given sequence numbers of the form
1.0.0-beta.3
. This allows series of candidate changes to be deployed
individually without causing the version numbers to increase ridiculously
quickly.
In addition to core automation provided by semantic-release, the following steps happen automatically:
- If a new release of
engine
occurs on thebeta
branch, the browser-importable engine module at https://web.wwtassets.org/engine/latest/wwtsdk.js is updated. - If one occurs on the
master
branch, the corresponding module athttps://web.wwtassets.org/engine/X.Y/wwtsdk.js
is updated, whereX.Y
is the first two components of the current engine version. - On every merge to the
beta
branch, the documentation at https://docs.worldwidetelescope.org/webgl-reference/latest/ is updated. - On every merge to the
master
branch, the documentation athttps://docs.worldwidetelescope.org/webgl-reference/X.Y/
is updated, whereX.Y
is the first two components of the current engine version.
Getting involved
We love it when people get involved in the WWT community! You can get started by participating in our user forum or by signing up for our low-traffic newsletter. If you would like to help make WWT better, our Contributor Hub aims to be your one-stop shop for information about how to contribute to the project, with the Contributors’ Guide being the first thing you should read. Here on GitHub we operate with a standard fork-and-pull model.
All participation in WWT communities is conditioned on your adherence to the WWT Code of Conduct, which basically says that you should not be a jerk.
Acknowledgments
The AAS WorldWide Telescope system is a .NET Foundation project. Work on WWT has been supported by the American Astronomical Society (AAS), the US National Science Foundation (grants 1550701 and 1642446), the Gordon and Betty Moore Foundation, and Microsoft.
Legalities
The WWT code is licensed under the MIT License. The copyright to the code is owned by the .NET Foundation.