# sregion
Parsing of IVOA S_REGION strings
The STS-C formalism is described at http://www.ivoa.net/Documents/latest/STC-S.html, though [it seems](https://github.com/astropy/regions/issues/21) that it was never adopted as an official standard. Nevertheless, the `s_region` strings do seem to have been adopted as a sort of pseudostandard in [IVOA-compliant](https://wiki.ivoa.net/twiki/bin/view/IVOA/DCPToolsFITS) datasets / databases.
[`astropy-regions`](https://github.com/astropy/regions) would probably be a better place to put this, but I'm not interested in all of the full astropy coordinate compatibility for now.
## Examples
```python
>>> import numpy as np
>>> from sregion import SRegion
#
# Polygon string
#
>>> sr = SRegion('POLYGON 0.0 0.0 0.0 1.0 1.0 1.0 1.0 0.0')
>>> print(sr.area)
[1.0]
>>> print(sr.centroid)
[array([0.5, 0.5])]
#
# Circle string
#
>>> for i in range(4,10):
>>> sr = SRegion('CIRCLE 10 10 1', ncircle=2**i)
>>> print(f'ncircle={2**i:>3} {sr.area[0]/np.pi:.5f} {sr.centroid[0]}')
ncircle= 16 0.97450 [10. 10.]
ncircle= 32 0.99359 [10. 10.]
ncircle= 64 0.99839 [10. 10.]
ncircle=128 0.99960 [10. 10.]
ncircle=256 0.99990 [10. 10.]
ncircle=512 0.99997 [10. 10.]
# Circle with radius in angular units
>>> import astropy.units as u
>>> sr = SRegion('CIRCLE 10 10 1"', ncircle=256)
>>> print(f'{sr.sky_area(unit=u.arcsec**2)[0]:.5f}')
3.14128 arcsec2
#
# From WCS objects
#
>>> from astropy.wcs import WCS
>>> wcs = WCS()
>>> wcs.pixel_shape = [601,601]
>>> wcs.wcs.cdelt *= 0.1/3600
>>> wcs.wcs.crpix[1] = 300
>>> wcs.wcs.crval = [0,0]
>>> print(SRegion(wcs).sky_area())
[<Quantity 1. arcmin2>]
#
# From arrays
#
>>> x = np.array([0, 0, 1, 1])
>>> y = np.array([0, 1, 1, 0])
>>> sr = SRegion(np.array([x, y]).T)
>>> print(sr.area)
[1.0]
>>> print(sr.centroid)
[array([0.5, 0.5])]
#
# To s_region string
#
>>> print(sr.s_region)
POLYGON 0.000000 0.000000 0.000000 1.000000 1.000000 1.000000 1.000000 0.000000
#
# To matplotlib path object(s)
#
>>> print(sr.path[0].contains_point([0.5, 0.5]))
True
>>> print(sr.path[0].contains_points([[0.5, 0.5], [2.0, 2.0]]))
[ True False]
#
# To matplotlib patch(es)
#
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(1,1,figsize=(2,2))
>>> for p in sr.patch(alpha=0.5, fc='r'):
>>> ax.add_patch(p)
>>> ax.set_xlim(-1, 2)
>>> ax.set_ylim(*ax.get_xlim())
>>> ax.grid()
#
# To shapely polygons
#
>>> sr.shapely
[<shapely.geometry.polygon.Polygon at 0x18055b910>]
#
# To DS9 region(s)
#
>>> for r in sr.region:
>>> print(r)
polygon(0.000000,0.000000,0.000000,1.000000,1.000000,1.000000,1.000000,0.000000)
>>> sr.ds9_properties = 'color=red width=2'
>>> sr.label = 'my_group'
>>> for r in sr.region:
>>> print(r)
polygon(0.000000,0.000000,0.000000,1.000000,1.000000,1.000000,1.000000,0.000000) # color=red width=2 text={my_group}
```
Raw data
{
"_id": null,
"home_page": "http://github.com/gbrammer/sregion",
"name": "sregion",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "G. Brammer",
"author_email": "gbrammer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8f/4f/f1102ce86ec103ab480120fbe53857d6bf375f0fce18cd97492e72cd2c46/sregion-1.5.tar.gz",
"platform": null,
"description": "\n\n# sregion\nParsing of IVOA S_REGION strings\n\nThe STS-C formalism is described at http://www.ivoa.net/Documents/latest/STC-S.html, though [it seems](https://github.com/astropy/regions/issues/21) that it was never adopted as an official standard. Nevertheless, the `s_region` strings do seem to have been adopted as a sort of pseudostandard in [IVOA-compliant](https://wiki.ivoa.net/twiki/bin/view/IVOA/DCPToolsFITS) datasets / databases.\n\n[`astropy-regions`](https://github.com/astropy/regions) would probably be a better place to put this, but I'm not interested in all of the full astropy coordinate compatibility for now.\n\n## Examples\n\n```python\n>>> import numpy as np\n>>> from sregion import SRegion\n\n#\n# Polygon string\n#\n>>> sr = SRegion('POLYGON 0.0 0.0 0.0 1.0 1.0 1.0 1.0 0.0')\n>>> print(sr.area)\n[1.0]\n>>> print(sr.centroid)\n[array([0.5, 0.5])]\n\n#\n# Circle string\n#\n>>> for i in range(4,10):\n>>> sr = SRegion('CIRCLE 10 10 1', ncircle=2**i)\n>>> print(f'ncircle={2**i:>3} {sr.area[0]/np.pi:.5f} {sr.centroid[0]}')\nncircle= 16 0.97450 [10. 10.]\nncircle= 32 0.99359 [10. 10.]\nncircle= 64 0.99839 [10. 10.]\nncircle=128 0.99960 [10. 10.]\nncircle=256 0.99990 [10. 10.]\nncircle=512 0.99997 [10. 10.]\n\n# Circle with radius in angular units\n>>> import astropy.units as u\n>>> sr = SRegion('CIRCLE 10 10 1\"', ncircle=256)\n>>> print(f'{sr.sky_area(unit=u.arcsec**2)[0]:.5f}')\n3.14128 arcsec2\n\n#\n# From WCS objects\n#\n>>> from astropy.wcs import WCS\n>>> wcs = WCS()\n>>> wcs.pixel_shape = [601,601]\n>>> wcs.wcs.cdelt *= 0.1/3600\n>>> wcs.wcs.crpix[1] = 300\n>>> wcs.wcs.crval = [0,0]\n>>> print(SRegion(wcs).sky_area())\n[<Quantity 1. arcmin2>]\n\n#\n# From arrays\n#\n>>> x = np.array([0, 0, 1, 1])\n>>> y = np.array([0, 1, 1, 0])\n>>> sr = SRegion(np.array([x, y]).T)\n>>> print(sr.area)\n[1.0]\n>>> print(sr.centroid)\n[array([0.5, 0.5])]\n\n# \n# To s_region string\n#\n>>> print(sr.s_region)\nPOLYGON 0.000000 0.000000 0.000000 1.000000 1.000000 1.000000 1.000000 0.000000\n\n#\n# To matplotlib path object(s)\n#\n>>> print(sr.path[0].contains_point([0.5, 0.5]))\nTrue\n>>> print(sr.path[0].contains_points([[0.5, 0.5], [2.0, 2.0]]))\n[ True False]\n\n#\n# To matplotlib patch(es)\n#\n>>> import matplotlib.pyplot as plt\n>>> fig, ax = plt.subplots(1,1,figsize=(2,2))\n>>> for p in sr.patch(alpha=0.5, fc='r'):\n>>> ax.add_patch(p)\n>>> ax.set_xlim(-1, 2)\n>>> ax.set_ylim(*ax.get_xlim())\n>>> ax.grid()\n\n#\n# To shapely polygons\n# \n>>> sr.shapely\n[<shapely.geometry.polygon.Polygon at 0x18055b910>]\n\n#\n# To DS9 region(s)\n#\n>>> for r in sr.region:\n>>> print(r)\npolygon(0.000000,0.000000,0.000000,1.000000,1.000000,1.000000,1.000000,0.000000)\n\n>>> sr.ds9_properties = 'color=red width=2'\n>>> sr.label = 'my_group'\n>>> for r in sr.region:\n>>> print(r)\npolygon(0.000000,0.000000,0.000000,1.000000,1.000000,1.000000,1.000000,0.000000) # color=red width=2 text={my_group}\n\n \n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parsing of IVOA S_REGION strings",
"version": "1.5",
"project_urls": {
"Homepage": "http://github.com/gbrammer/sregion",
"Source": "https://github.com/gbrammer/sregion",
"Tracker": "https://github.com/gbrammer/sregion/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8f4ff1102ce86ec103ab480120fbe53857d6bf375f0fce18cd97492e72cd2c46",
"md5": "d888a176da9a1f4ef6fbfd3be2ba999d",
"sha256": "a1e49752ec06d4a744de9fc364f889008d6cfc77f1b2ac04760400492abc7cc5"
},
"downloads": -1,
"filename": "sregion-1.5.tar.gz",
"has_sig": false,
"md5_digest": "d888a176da9a1f4ef6fbfd3be2ba999d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15700,
"upload_time": "2025-08-13T10:32:53",
"upload_time_iso_8601": "2025-08-13T10:32:53.652272Z",
"url": "https://files.pythonhosted.org/packages/8f/4f/f1102ce86ec103ab480120fbe53857d6bf375f0fce18cd97492e72cd2c46/sregion-1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 10:32:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gbrammer",
"github_project": "sregion",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "astropy",
"specs": []
},
{
"name": "shapely",
"specs": []
},
{
"name": "descartes",
"specs": []
}
],
"lcname": "sregion"
}
JSON
