[](https://badge.fury.io/py/pywwt)
[](https://doi.org/10.5281/zenodo.7164147)
[](https://dev.azure.com/aasworldwidetelescope/WWT/_build/latest?definitionId=2&branchName=master)
# pywwt: WorldWide Telescope from Python/Jupyter
🚀🚀 [Click here to try out pywwt in the cloud!][go-cloud] 🚀🚀
[go-cloud]: https://mybinder.org/v2/gh/WorldWideTelescope/pywwt-notebooks/master?urlpath=lab/tree/Start%20Here.ipynb
*Note: the cloud servers usually start up quickly, but if they were recently
updated you may have to wait a few minutes for the backing software images to be
rebuilt.*
## About
The [pywwt] package is the official toolkit for visualizing astronomical data in
Python using [WorldWide Telescope][wwt] (WWT), a free, open-source astronomy
visualization system. WWT includes a sophisticated 4D WebGL rendering engine and
a cloud-based web service for sharing and visualizing terabytes of astronomical
data.
[pywwt]: https://pywwt.readthedocs.io/
[wwt]: https://worldwidetelescope.org/home
[dnf]: https://dotnetfoundation.org/
With [pywwt] you can:
* Visualize and explore astronomical data interactively in the [Jupyter and
JupyterLab][jupyter] environments through an HTML widget
* Do the same in standalone applications with a [Qt][qt] widget
* Load data from common astronomical data formats (e.g. [AstroPy
tables][tables]) into WWT
* Control a running instance of the WWT Windows application
[jupyter]: https://jupyter.org/
[qt]: https://www.qt.io/
[tables]: https://docs.astropy.org/en/stable/table/
[//]: # (numfocus-fiscal-sponsor-attribution)
The WorldWide Telescope project uses an [open governance
model](https://worldwidetelescope.org/about/governance/) and is fiscally
sponsored by [NumFOCUS](https://numfocus.org/). Consider making a
[tax-deductible donation](https://numfocus.org/donate-for-worldwide-telescope)
to help the project pay for developer time, professional services, travel,
workshops, and a variety of other needs.
<div align="center">
<a href="https://numfocus.org/donate-for-worldwide-telescope">
<img height="60px"
src="https://raw.githubusercontent.com/numfocus/templates/master/images/numfocus-logo.png">
</a>
</div>
## Installation
The full pywwt documentation, including installation instructions, can be found
at <https://pywwt.readthedocs.io/>.
## Reporting issues
If you run into any issues, please open an issue [here](https://github.com/WorldWideTelescope/pywwt/issues).
## For Developers: Testing
To test your pywwt checkout, use the `pytest` command.
The pywwt test suite includes a set of image tests that generate imagery using
the WWT Qt widget and compare the results to a set of reference images. This
component of the test suite can be finicky, even when everything is working
properly, because the details of the rendering are dependent upon your operating
system and OpenGL implementation. If your setup is yielding visually correct
results, but the test suite is not passing for you, you can fix that as
described below.
For a bit more context, each “image test” generates a WWT visual and compares it
to multiple reference images. If *any* of those images is sufficiently close to
the WWT result, the test passes. So if you’re running the test suite and the
comparisons are failing, you need add appropriate new images to the corpus.
For a test like `image_layer_equ`, the reference images are stored in the
subdirectory `pywwt/tests/data/refimg_image_layer_equ`. The filenames of the
reference images within that directory don't matter, and are intentionally
uninformative since the same reference image might match a wide variety of
rendering platforms.
If you run the test suite with the environment variable `$PYWWT_TEST_IMAGE_DIR`
set to a non-empty value, the WWT visuals generated during the test run will be
saved in the named directory. For any images that fail tests, difference images
with names resembling `image_layer_equ_vs_a.png` will also be saved. So to
update the image corpus so that the test suite passes for you, run the test
suite in this mode, then copy the failing images to the appropriate reference
image data directories. Don't forget to `git add` the new files! And you should
also verify that your new images do in fact look “reasonable” compared to what’s
expected for the test.
You can also run `python -m pywwt.tests $imgdir1 $imgdir2 ...`, where `$imgdirN`
are paths to directories or Zip files containing images generated during one or
more test runs. This will compare those images to the current corpus of
reference images, and indicate whether there are images in the reference corpus
that could potentially be removed. **Note**, however, that this is only safe if
your collection of `$imgdirN` spans *all* pywwt rendering platforms of interest.
If there’s a developer that runs the test suite on MacOS 10.10 and your
collection doesn't include those samples, you run the risk of breaking the test
suite for that person if you remove the reference files that they need. That
being said, it is quite possible for reference images to get out-of-date as the
rendering code and test suite evolve. On the third hand, deleting files from
the Git repository doesn't actually make it smaller, so removing old reference
images only helps a bit with housekeeping.
## Continuous Integration and Deployment
This repository uses [Cranko] to automate release workflows. This automation is
essential to the smooth and reproducible deployment of the WWT web services.
[Cranko]: https://pkgw.github.io/cranko/
## 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.
[participating in our user forum]: https://wwt-forum.org/
[signing up for our low-traffic newsletter]: https://bit.ly/wwt-signup
[Contributor Hub]: https://worldwidetelescope.github.io/
[Contributors’ Guide]: https://worldwidetelescope.github.io/contributing/
[fork-and-pull]: https://help.github.com/en/articles/about-collaborative-development-models
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.
[WWT Code of Conduct]: https://worldwidetelescope.github.io/code-of-conduct/
## Acknowledgments
Work on the WorldWide Telescope system has been supported by the [American
Astronomical Society] (AAS), the [.NET Foundation], and other partners. See [the
WWT user website][acks] for details.
[American Astronomical Society]: https://aas.org/
[.NET Foundation]: https://dotnetfoundation.org/
[acks]: https://worldwidetelescope.org/about/acknowledgments/
## Legalities
The WWT code is licensed under the [MIT License]. The copyright to the code is
owned by the [.NET Foundation].
[MIT License]: https://opensource.org/licenses/MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/WorldWideTelescope/pywwt",
"name": "pywwt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Jupyter,Widgets,IPython",
"author": "WorldWide Telescope team",
"author_email": "hello@worldwidetelescope.org",
"download_url": "https://files.pythonhosted.org/packages/d0/48/3083c3b959ba0dce3350b89b8e3409c5efa3fbdda5d9feb79178c6b5e42d/pywwt-0.23.0.tar.gz",
"platform": "Linux",
"description": "[](https://badge.fury.io/py/pywwt)\n[](https://doi.org/10.5281/zenodo.7164147)\n[](https://dev.azure.com/aasworldwidetelescope/WWT/_build/latest?definitionId=2&branchName=master)\n\n# pywwt: WorldWide Telescope from Python/Jupyter\n\n\ud83d\ude80\ud83d\ude80 [Click here to try out pywwt in the cloud!][go-cloud] \ud83d\ude80\ud83d\ude80\n\n[go-cloud]: https://mybinder.org/v2/gh/WorldWideTelescope/pywwt-notebooks/master?urlpath=lab/tree/Start%20Here.ipynb\n\n*Note: the cloud servers usually start up quickly, but if they were recently\nupdated you may have to wait a few minutes for the backing software images to be\nrebuilt.*\n\n\n## About\n\nThe [pywwt] package is the official toolkit for visualizing astronomical data in\nPython using [WorldWide Telescope][wwt] (WWT), a free, open-source astronomy\nvisualization system. WWT includes a sophisticated 4D WebGL rendering engine and\na cloud-based web service for sharing and visualizing terabytes of astronomical\ndata.\n\n[pywwt]: https://pywwt.readthedocs.io/\n[wwt]: https://worldwidetelescope.org/home\n[dnf]: https://dotnetfoundation.org/\n\n![A WWT screenshot showing exoplanets in the Kepler field overlaid on a background sky map.](docs/images/data_layers_kepler.png \"Kepler exoplanets in pywwt\")\n\nWith [pywwt] you can:\n\n* Visualize and explore astronomical data interactively in the [Jupyter and\n JupyterLab][jupyter] environments through an HTML widget\n* Do the same in standalone applications with a [Qt][qt] widget\n* Load data from common astronomical data formats (e.g. [AstroPy\n tables][tables]) into WWT\n* Control a running instance of the WWT Windows application\n\n[jupyter]: https://jupyter.org/\n[qt]: https://www.qt.io/\n[tables]: https://docs.astropy.org/en/stable/table/\n\n[//]: # (numfocus-fiscal-sponsor-attribution)\n\nThe WorldWide Telescope project uses an [open governance\nmodel](https://worldwidetelescope.org/about/governance/) and is fiscally\nsponsored by [NumFOCUS](https://numfocus.org/). Consider making a\n[tax-deductible donation](https://numfocus.org/donate-for-worldwide-telescope)\nto help the project pay for developer time, professional services, travel,\nworkshops, and a variety of other needs.\n\n<div align=\"center\">\n <a href=\"https://numfocus.org/donate-for-worldwide-telescope\">\n <img height=\"60px\"\n src=\"https://raw.githubusercontent.com/numfocus/templates/master/images/numfocus-logo.png\">\n </a>\n</div>\n\n\n## Installation\n\nThe full pywwt documentation, including installation instructions, can be found\nat <https://pywwt.readthedocs.io/>.\n\n\n## Reporting issues\n\nIf you run into any issues, please open an issue [here](https://github.com/WorldWideTelescope/pywwt/issues).\n\n\n## For Developers: Testing\n\nTo test your pywwt checkout, use the `pytest` command.\n\nThe pywwt test suite includes a set of image tests that generate imagery using\nthe WWT Qt widget and compare the results to a set of reference images. This\ncomponent of the test suite can be finicky, even when everything is working\nproperly, because the details of the rendering are dependent upon your operating\nsystem and OpenGL implementation. If your setup is yielding visually correct\nresults, but the test suite is not passing for you, you can fix that as\ndescribed below.\n\nFor a bit more context, each \u201cimage test\u201d generates a WWT visual and compares it\nto multiple reference images. If *any* of those images is sufficiently close to\nthe WWT result, the test passes. So if you\u2019re running the test suite and the\ncomparisons are failing, you need add appropriate new images to the corpus.\n\nFor a test like `image_layer_equ`, the reference images are stored in the\nsubdirectory `pywwt/tests/data/refimg_image_layer_equ`. The filenames of the\nreference images within that directory don't matter, and are intentionally\nuninformative since the same reference image might match a wide variety of\nrendering platforms.\n\nIf you run the test suite with the environment variable `$PYWWT_TEST_IMAGE_DIR`\nset to a non-empty value, the WWT visuals generated during the test run will be\nsaved in the named directory. For any images that fail tests, difference images\nwith names resembling `image_layer_equ_vs_a.png` will also be saved. So to\nupdate the image corpus so that the test suite passes for you, run the test\nsuite in this mode, then copy the failing images to the appropriate reference\nimage data directories. Don't forget to `git add` the new files! And you should\nalso verify that your new images do in fact look \u201creasonable\u201d compared to what\u2019s\nexpected for the test.\n\nYou can also run `python -m pywwt.tests $imgdir1 $imgdir2 ...`, where `$imgdirN`\nare paths to directories or Zip files containing images generated during one or\nmore test runs. This will compare those images to the current corpus of\nreference images, and indicate whether there are images in the reference corpus\nthat could potentially be removed. **Note**, however, that this is only safe if\nyour collection of `$imgdirN` spans *all* pywwt rendering platforms of interest.\nIf there\u2019s a developer that runs the test suite on MacOS 10.10 and your\ncollection doesn't include those samples, you run the risk of breaking the test\nsuite for that person if you remove the reference files that they need. That\nbeing said, it is quite possible for reference images to get out-of-date as the\nrendering code and test suite evolve. On the third hand, deleting files from\nthe Git repository doesn't actually make it smaller, so removing old reference\nimages only helps a bit with housekeeping.\n\n\n## Continuous Integration and Deployment\n\nThis repository uses [Cranko] to automate release workflows. This automation is\nessential to the smooth and reproducible deployment of the WWT web services.\n\n[Cranko]: https://pkgw.github.io/cranko/\n\n\n## Getting involved\n\nWe love it when people get involved in the WWT community! You can get started\nby [participating in our user forum] or by\n[signing up for our low-traffic newsletter]. If you would like to help make\nWWT better, our [Contributor Hub] aims to be your one-stop shop for\ninformation about how to contribute to the project, with the\n[Contributors\u2019 Guide] being the first thing you should read. Here on GitHub we\noperate with a standard [fork-and-pull] model.\n\n[participating in our user forum]: https://wwt-forum.org/\n[signing up for our low-traffic newsletter]: https://bit.ly/wwt-signup\n[Contributor Hub]: https://worldwidetelescope.github.io/\n[Contributors\u2019 Guide]: https://worldwidetelescope.github.io/contributing/\n[fork-and-pull]: https://help.github.com/en/articles/about-collaborative-development-models\n\nAll participation in WWT communities is conditioned on your adherence to the\n[WWT Code of Conduct], which basically says that you should not be a jerk.\n\n[WWT Code of Conduct]: https://worldwidetelescope.github.io/code-of-conduct/\n\n\n## Acknowledgments\n\nWork on the WorldWide Telescope system has been supported by the [American\nAstronomical Society] (AAS), the [.NET Foundation], and other partners. See [the\nWWT user website][acks] for details.\n\n[American Astronomical Society]: https://aas.org/\n[.NET Foundation]: https://dotnetfoundation.org/\n[acks]: https://worldwidetelescope.org/about/acknowledgments/\n\n\n## Legalities\n\nThe WWT code is licensed under the [MIT License]. The copyright to the code is\nowned by the [.NET Foundation].\n\n[MIT License]: https://opensource.org/licenses/MIT\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Interactively visualize astronomy data in WorldWide Telescope",
"version": "0.23.0",
"project_urls": {
"Homepage": "https://github.com/WorldWideTelescope/pywwt"
},
"split_keywords": [
"jupyter",
"widgets",
"ipython"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d0483083c3b959ba0dce3350b89b8e3409c5efa3fbdda5d9feb79178c6b5e42d",
"md5": "df421ad465a797a4a1d563d560351338",
"sha256": "68fea208e1ef26cf3adcd7c708e513be51573a2fd6555611a5a41ea213671ba1"
},
"downloads": -1,
"filename": "pywwt-0.23.0.tar.gz",
"has_sig": false,
"md5_digest": "df421ad465a797a4a1d563d560351338",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 9810061,
"upload_time": "2023-11-28T20:29:28",
"upload_time_iso_8601": "2023-11-28T20:29:28.218138Z",
"url": "https://files.pythonhosted.org/packages/d0/48/3083c3b959ba0dce3350b89b8e3409c5efa3fbdda5d9feb79178c6b5e42d/pywwt-0.23.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-28 20:29:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WorldWideTelescope",
"github_project": "pywwt",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"lcname": "pywwt"
}
JSON
