# twirl
<p align="center">
<img src="https://github.com/lgrcia/twirl/blob/main/docs/_static/twirl.png" height="270">
</p>
<p align="center">
Python package for astrometric plate solving
<br>
<p align="center">
<a href="https://github.com/lgrcia/twirl">
<img src="https://img.shields.io/badge/github-lgrcia/twirl-blue.svg?style=flat" alt="github"/>
</a>
<a href="">
<img src="https://img.shields.io/badge/license-MIT-lightgray.svg?style=flat" alt="license"/>
</a>
<a href="https://ui.adsabs.harvard.edu/abs/2022MNRAS.509.4817G">
<img src="https://img.shields.io/badge/paper-gray.svg?style=flat" alt="paper"/>
</a>
<a href="https://twirl.readthedocs.io">
<img src="https://img.shields.io/badge/documentation-black.svg?style=flat" alt="documentation"/>
</a>
</p>
</p>
twirl is an astrometric plate solving package for Python. It is suited for cases where the Right Ascension and Declination (RA, dec) coordinates of the image center and the field of view is known, computing a World Coordinate System (WCS) based on GAIA reference stars.
twirl compute a WCS following these steps:
1. detection of stars in the image if not provided
2. catalog query using image known center
3. asterisms building and matching
4. image recombination and wcs fit using astropy.wcs
Astersisms are made of 3 or 4 points. 4 points asterisms are built following Lang et al. 2009 while 3 points asterims are based on an original algorithm.
## Installation
twirl can be installed using pip:
```shell
pip install twirl
```
or using poetry:
```shell
poetry add twirl
```
## Example Usage
*twirl* is designed to be complementary to the *astropy* package. It is used to compute a WCS by matching an image detected stars with catalog stars. To query the catalog stars, the center coordinates of the image must be known, as well as the size of the field of view. If not available, the latter can be computed using the known pixel scale of the detector.
Hence, the process starts by extracting the image RA-DEC center equatorial coordinate and compute the instrument field of view
```python
import numpy as np
from astropy.io import fits
from astropy import units as u
from astropy.coordinates import SkyCoord
# Open some FITS image
hdu = fits.open("...")[0]
# get the center of the image
ra, dec = hdu.header["RA"], hdu.header["DEC"]
center = SkyCoord(ra, dec, unit=["deg", "deg"])
# and the size of its field of view
pixel = 0.66 * u.arcsec # known pixel scale
shape = hdu.data.shape
fov = np.max(shape) * pixel.to(u.deg)
```
We can then query the gaia stars in the field using this information
```python
import twirl
sky_coords = twirl.gaia_radecs(center, 1.2 * fov)[0:12]
```
and match the queried stars to stars detected in the image
```python
# detect stars in the image
pixel_coords = twirl.find_peaks(hdu.data)[0:12]
# compute the World Coordinate System
wcs = twirl.compute_wcs(pixel_coords, sky_coords)
```
leading to a World Coordinate System object.
A more complete example is provided in [docs/ipynb/wcs.ipynb](https://twirl.readthedocs.io/en/latest/ipynb/wcs.html)
## Development
### Project Requirements
- [Python](https://www.python.org/) 3.11.*
- [Poetry](https://python-poetry.org/) for Python package and environment management.
### Installing Dependencies
The twirl project manages Python package dependencies using [Poetry](https://python-poetry.org/). You'll need to follow the instructions for installation there.
Then you can start a shell session with the new environment with:
```console
$ poetry shell
```
**N.B.** For development with vscode you will need to run the following command:
```console
$ poetry config virtualenvs.in-project true
```
This will installed the poetry `.venv` in the root of the project and allow vscode to setup the environment correctly for development.
To start development, install all of the dependencies as:
```console
$ poetry install
```
**N.B.** _Ensure that any dependency changes are committed to source control, so everyone has a consistenct package dependecy list._
## Acknowledgements
This package has made use of the algorithm from
Lang, D. et al. (2010). _Astrometry.net: Blind Astrometric Calibration of Arbitrary Astronomical Images_. The Astronomical Journal, 139(5), pp.1782–1800. [doi:10.1088/0004-6256/139/5/1782](https://iopscience.iop.org/article/10.1088/0004-6256/139/5/1782).
implemented in
Garcia, L. J. et al. (2022). prose: a Python framework for modular astronomical images processing. MNRAS, vol. 509, no. 4, pp. 4817–4828, 2022. [doi:10.1093/mnras/stab3113](https://academic.oup.com/mnras/article-abstract/509/4/4817/6414007).
See this [documentation page](https://twirl.readthedocs.io/en/latest/md/acknowledgement.html) for the BibTeX entries.
Raw data
{
"_id": null,
"home_page": "https://twirl.readthedocs.io",
"name": "twirl",
"maintainer": "Lionel J. Garcia",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "lionel_garcia@live.fr",
"keywords": "astronomy,astrometry,plate-solving",
"author": "Lionel J. Garcia",
"author_email": "lionel_garcia@live.fr",
"download_url": "https://files.pythonhosted.org/packages/a9/c7/f537b0906814253657f41f9dc2b59d88ba3b1a1b419f2e8bfd650634e68b/twirl-0.4.2.tar.gz",
"platform": null,
"description": "# twirl\n\n<p align=\"center\">\n <img src=\"https://github.com/lgrcia/twirl/blob/main/docs/_static/twirl.png\" height=\"270\">\n</p>\n\n<p align=\"center\">\n Python package for astrometric plate solving\n <br>\n <p align=\"center\">\n <a href=\"https://github.com/lgrcia/twirl\">\n <img src=\"https://img.shields.io/badge/github-lgrcia/twirl-blue.svg?style=flat\" alt=\"github\"/>\n </a>\n <a href=\"\">\n <img src=\"https://img.shields.io/badge/license-MIT-lightgray.svg?style=flat\" alt=\"license\"/>\n </a>\n <a href=\"https://ui.adsabs.harvard.edu/abs/2022MNRAS.509.4817G\">\n <img src=\"https://img.shields.io/badge/paper-gray.svg?style=flat\" alt=\"paper\"/>\n </a>\n <a href=\"https://twirl.readthedocs.io\">\n <img src=\"https://img.shields.io/badge/documentation-black.svg?style=flat\" alt=\"documentation\"/>\n </a>\n </p>\n</p>\n\ntwirl is an astrometric plate solving package for Python. It is suited for cases where the Right Ascension and Declination (RA, dec) coordinates of the image center and the field of view is known, computing a World Coordinate System (WCS) based on GAIA reference stars.\n\ntwirl compute a WCS following these steps:\n\n1. detection of stars in the image if not provided\n2. catalog query using image known center\n3. asterisms building and matching\n4. image recombination and wcs fit using astropy.wcs\n\nAstersisms are made of 3 or 4 points. 4 points asterisms are built following Lang et al. 2009 while 3 points asterims are based on an original algorithm.\n\n## Installation\n\ntwirl can be installed using pip:\n\n```shell\npip install twirl\n```\n\nor using poetry:\n\n```shell\npoetry add twirl\n```\n\n## Example Usage\n\n*twirl* is designed to be complementary to the *astropy* package. It is used to compute a WCS by matching an image detected stars with catalog stars. To query the catalog stars, the center coordinates of the image must be known, as well as the size of the field of view. If not available, the latter can be computed using the known pixel scale of the detector.\n\nHence, the process starts by extracting the image RA-DEC center equatorial coordinate and compute the instrument field of view\n\n```python\nimport numpy as np\n\nfrom astropy.io import fits\nfrom astropy import units as u\nfrom astropy.coordinates import SkyCoord\n\n# Open some FITS image\nhdu = fits.open(\"...\")[0]\n\n# get the center of the image\nra, dec = hdu.header[\"RA\"], hdu.header[\"DEC\"]\ncenter = SkyCoord(ra, dec, unit=[\"deg\", \"deg\"])\n\n# and the size of its field of view\npixel = 0.66 * u.arcsec # known pixel scale\nshape = hdu.data.shape\nfov = np.max(shape) * pixel.to(u.deg)\n```\n\nWe can then query the gaia stars in the field using this information\n\n```python\nimport twirl\n\nsky_coords = twirl.gaia_radecs(center, 1.2 * fov)[0:12]\n```\n\nand match the queried stars to stars detected in the image\n\n```python\n# detect stars in the image\npixel_coords = twirl.find_peaks(hdu.data)[0:12]\n\n# compute the World Coordinate System\nwcs = twirl.compute_wcs(pixel_coords, sky_coords)\n```\nleading to a World Coordinate System object.\n\nA more complete example is provided in [docs/ipynb/wcs.ipynb](https://twirl.readthedocs.io/en/latest/ipynb/wcs.html)\n\n\n## Development\n\n### Project Requirements\n\n- [Python](https://www.python.org/) 3.11.*\n- [Poetry](https://python-poetry.org/) for Python package and environment management.\n\n### Installing Dependencies\n\nThe twirl project manages Python package dependencies using [Poetry](https://python-poetry.org/). You'll need to follow the instructions for installation there.\n\nThen you can start a shell session with the new environment with:\n\n```console\n$ poetry shell\n```\n\n**N.B.** For development with vscode you will need to run the following command:\n\n```console\n$ poetry config virtualenvs.in-project true\n```\n\nThis will installed the poetry `.venv` in the root of the project and allow vscode to setup the environment correctly for development.\n\nTo start development, install all of the dependencies as:\n\n```console\n$ poetry install\n```\n\n**N.B.** _Ensure that any dependency changes are committed to source control, so everyone has a consistenct package dependecy list._\n\n\n## Acknowledgements\n\nThis package has made use of the algorithm from\n\nLang, D. et al. (2010). _Astrometry.net: Blind Astrometric Calibration of Arbitrary Astronomical Images_. The Astronomical Journal, 139(5), pp.1782\u20131800. [doi:10.1088/0004-6256/139/5/1782](https://iopscience.iop.org/article/10.1088/0004-6256/139/5/1782).\n\nimplemented in\n\nGarcia, L. J. et al. (2022). prose: a Python framework for modular astronomical images processing. MNRAS, vol. 509, no. 4, pp. 4817\u20134828, 2022. [doi:10.1093/mnras/stab3113](https://academic.oup.com/mnras/article-abstract/509/4/4817/6414007).\n\nSee this [documentation page](https://twirl.readthedocs.io/en/latest/md/acknowledgement.html) for the BibTeX entries.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Astrometric plate solving in Python",
"version": "0.4.2",
"project_urls": {
"Homepage": "https://twirl.readthedocs.io",
"Repository": "https://github.com/lgrcia/twirl"
},
"split_keywords": [
"astronomy",
"astrometry",
"plate-solving"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b5c2e4ac9ddd00a2428e2f0e5a1f4b60d7499155757461e38aa72e666561703c",
"md5": "0c7c97dd48d0923b6584615a5adbc604",
"sha256": "80ab55f21c206fdb66e4ca335cf417498515b6c6451d7c016671ccbb1ca58ac4"
},
"downloads": -1,
"filename": "twirl-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c7c97dd48d0923b6584615a5adbc604",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 11339,
"upload_time": "2023-11-30T00:12:25",
"upload_time_iso_8601": "2023-11-30T00:12:25.494916Z",
"url": "https://files.pythonhosted.org/packages/b5/c2/e4ac9ddd00a2428e2f0e5a1f4b60d7499155757461e38aa72e666561703c/twirl-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a9c7f537b0906814253657f41f9dc2b59d88ba3b1a1b419f2e8bfd650634e68b",
"md5": "1a7f08f510b3df79b5728ce7d36bbaad",
"sha256": "0d1dbabc73c5d4e07934afee0f5bbbd5a7a5e0300d9841adc207d39570a75ea3"
},
"downloads": -1,
"filename": "twirl-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "1a7f08f510b3df79b5728ce7d36bbaad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 12216,
"upload_time": "2023-11-30T00:12:27",
"upload_time_iso_8601": "2023-11-30T00:12:27.258576Z",
"url": "https://files.pythonhosted.org/packages/a9/c7/f537b0906814253657f41f9dc2b59d88ba3b1a1b419f2e8bfd650634e68b/twirl-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-30 00:12:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lgrcia",
"github_project": "twirl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "twirl"
}
JSON
