PyPlanetarium
=============
Python bindings for **Planetarium** sub-pixel precision light spot rendering
library for astronomy and video tracking applications.
Sample image
------------
Example usage
-------------
```python
from pyplanetarium import Canvas, SpotShape
# Draw on a square 256x256 pixel canvas.
c = Canvas.new(256, 256)
# Define a round spot shape with diffraction radius of 2.5 pixels.
shape = SpotShape().scale(2.5)
# Add some spots at random positions with varying shape size
# and peak intensity.
spot1 = c.add_spot((100.3, 130.8), shape, 0.5)
spot2 = c.add_spot((80.6, 200.2), shape.scale(0.5), 0.9)
# Note: Out of range position coordinates and peak intensities are fine.
# The resulting spot image is clipped into the canvas rectangle.
# Peak intensity > 1.0 leads to saturation to the maximum pixel value.
spot3 = c.add_spot((256.1, 3.5), shape.scale(10.0), 1.1)
# Set the canvas background pixel value.
c.set_background(int(0.05 * Canvas.PIXEL_MAX))
# Clear the canvas and paint the light spots.
c.draw()
# Get image dimensions.
image_width, image_height = c.dimensions()
```
Light spot parameters adjustment
--------------------------------
Some of the light spot parameters like coordinates and peak intensity
can be adjusted after the spot has been added to the canvas.
The spot position coordinates can be changed by adding an offset vector
and the peak intensity can be adjusted by multiplying with a spot
illumination factor.
It is possible to define a custom world coordinates to canvas coordinates
transformation, which affects all light spots.
```python
from pyplanetarium import Canvas, SpotShape, Transform
# Draw on a square 256x256 pixel canvas.
c = Canvas.new(256, 256)
# Define an elliptic spot shape with diffraction radii of 2.5 x 1.5 pixels
# rotated by 45 degrees counter-clockwise.
shape1 = SpotShape().stretch(2.5, 1.5).rotate(45.0)
# Define an elliptic spot shape by a 2x2 linear transform matrix.
shape2 = SpotShape([[2.0, -0.5], [1.5, 3.0]])
# Add some spots at random positions with varying shape size
# and peak intensity.
spot1 = c.add_spot((100.3, 130.8), shape1, 0.5)
spot2 = c.add_spot((80.6, 200.2), shape2, 0.9)
# Shift the rendered spot positions by applying the relative offset vectors.
# The intrinsic spot position coordinates are immutable.
c.set_spot_offset(spot1, (-34.2, 12.6))
c.set_spot_offset(spot2, (114.2, -73.3))
# Adjust the rendered spot peak intensity by applying the spot illumination factors.
# The intrinsic spot intensities are immutable.
c.set_spot_illumination(spot1, 1.2)
c.set_spot_illumination(spot2, 0.7)
# Query the resulting spot coordinates on the canvas.
pos1 = c.spot_position(spot1)
pos2 = c.spot_position(spot2)
# Query the resulting peak spot intensities.
int1 = c.spot_intensity(spot1)
int2 = c.spot_intensity(spot2)
# Apply a custom world coordinates to canvas coordinates transformation.
c.set_view_transform(Transform().translate((13.7, -20.3)))
# Query the resulting spot coordinates on the canvas after
# the view coordinate transformation.
pos1x = c.spot_position(spot1)
pos2x = c.spot_position(spot2)
```
Canvas image export
-------------------
The `Canvas` object supports image export to RAW and PNG file formats.
Both 8-bit and 16-bit PNG sample formats are supported.
Export to PNG formats requires the default `png` feature to be enabled.
### Example image export code
```python
from pyplanetarium import Canvas, ImageFormat
c = Canvas.new(256, 256)
c.set_background(1000)
c.clear()
# Export to a 8-bit gamma-compressed grayscale RAW image.
raw_8bpp_bytes = c.export_image(ImageFormat.RawGamma8Bpp)
# Export to a 10-bit linear light grayscale little-endian RAW image.
raw_10bpp_bytes = c.export_image(ImageFormat.RawLinear10BppLE)
# Export to a 12-bit gamma-compressed grayscale little-endian RAW image.
raw_12bpp_bytes = c.export_image(ImageFormat.RawLinear12BppLE)
# Export to a 8-bit gamma-compressed grayscale PNG image.
png_8bpp_bytes = c.export_image(ImageFormat.PngGamma8Bpp)
# Export to a 16-bit linear light grayscale PNG image.
png_16bpp_bytes = c.export_image(ImageFormat.PngLinear16Bpp)
```
Window image export
-------------------
The `Canvas` object additionally supports windowed image export.
A single rectangular window represents a region of interest (ROI)
on the canvas image. Window rectangle coordinates are represented
by the public `Window` structure.
### Example window image export code
```python
from pyplanetarium import Canvas, ImageFormat, Window
c = Canvas.new(256, 256)
# Create a 64x32 pixels window with origin at (90, 120).
wnd = Window.new(64, 32).at(90, 120)
fmt = ImageFormat.RawGamma8Bpp
# Export to the canvas window image bytes.
raw_window_bytes = c.export_window_image(wnd, fmt)
```
Subsampled image export
-----------------------
The `Canvas` object additionally supports subsampled image export
with independent row and column subsampling factors.
Only whole canvas images can be exported with subsampling.
### Example subsampled image export code
```python
from pyplanetarium import Canvas, ImageFormat
c = Canvas.new(256, 256)
fmt = ImageFormat.RawLinear10BppLE
# Column (X) and row (Y) subsampling factors
factors = (2, 2)
# Export to the subsampled canvas image bytes.
raw_sub_bytes = c.export_subsampled_image(factors, fmt)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "pyplanetarium",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "astronomy,simulation,python",
"author": "Sergey Kvachonok <ravenexp@gmail.com>",
"author_email": "Sergey Kvachonok <ravenexp@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3d/e8/82123b4d30c793918b0bd000932c5f8b6483abdfdb7f9b42048881275e6d/pyplanetarium-0.2.1.tar.gz",
"platform": null,
"description": "PyPlanetarium\n=============\n\nPython bindings for **Planetarium** sub-pixel precision light spot rendering\nlibrary for astronomy and video tracking applications.\n\nSample image\n------------\n\n\n\nExample usage\n-------------\n\n```python\nfrom pyplanetarium import Canvas, SpotShape\n\n# Draw on a square 256x256 pixel canvas.\nc = Canvas.new(256, 256)\n\n# Define a round spot shape with diffraction radius of 2.5 pixels.\nshape = SpotShape().scale(2.5)\n\n# Add some spots at random positions with varying shape size\n# and peak intensity.\nspot1 = c.add_spot((100.3, 130.8), shape, 0.5)\nspot2 = c.add_spot((80.6, 200.2), shape.scale(0.5), 0.9)\n\n# Note: Out of range position coordinates and peak intensities are fine.\n# The resulting spot image is clipped into the canvas rectangle.\n# Peak intensity > 1.0 leads to saturation to the maximum pixel value.\nspot3 = c.add_spot((256.1, 3.5), shape.scale(10.0), 1.1)\n\n# Set the canvas background pixel value.\nc.set_background(int(0.05 * Canvas.PIXEL_MAX))\n\n# Clear the canvas and paint the light spots.\nc.draw()\n\n# Get image dimensions.\nimage_width, image_height = c.dimensions()\n```\n\nLight spot parameters adjustment\n--------------------------------\n\nSome of the light spot parameters like coordinates and peak intensity\ncan be adjusted after the spot has been added to the canvas.\n\nThe spot position coordinates can be changed by adding an offset vector\nand the peak intensity can be adjusted by multiplying with a spot\nillumination factor.\n\nIt is possible to define a custom world coordinates to canvas coordinates\ntransformation, which affects all light spots.\n\n```python\nfrom pyplanetarium import Canvas, SpotShape, Transform\n\n# Draw on a square 256x256 pixel canvas.\nc = Canvas.new(256, 256)\n\n# Define an elliptic spot shape with diffraction radii of 2.5 x 1.5 pixels\n# rotated by 45 degrees counter-clockwise.\nshape1 = SpotShape().stretch(2.5, 1.5).rotate(45.0)\n\n# Define an elliptic spot shape by a 2x2 linear transform matrix.\nshape2 = SpotShape([[2.0, -0.5], [1.5, 3.0]])\n\n# Add some spots at random positions with varying shape size\n# and peak intensity.\nspot1 = c.add_spot((100.3, 130.8), shape1, 0.5)\nspot2 = c.add_spot((80.6, 200.2), shape2, 0.9)\n\n# Shift the rendered spot positions by applying the relative offset vectors.\n# The intrinsic spot position coordinates are immutable.\nc.set_spot_offset(spot1, (-34.2, 12.6))\nc.set_spot_offset(spot2, (114.2, -73.3))\n\n# Adjust the rendered spot peak intensity by applying the spot illumination factors.\n# The intrinsic spot intensities are immutable.\nc.set_spot_illumination(spot1, 1.2)\nc.set_spot_illumination(spot2, 0.7)\n\n# Query the resulting spot coordinates on the canvas.\npos1 = c.spot_position(spot1)\npos2 = c.spot_position(spot2)\n\n# Query the resulting peak spot intensities.\nint1 = c.spot_intensity(spot1)\nint2 = c.spot_intensity(spot2)\n\n# Apply a custom world coordinates to canvas coordinates transformation.\nc.set_view_transform(Transform().translate((13.7, -20.3)))\n\n# Query the resulting spot coordinates on the canvas after\n# the view coordinate transformation.\npos1x = c.spot_position(spot1)\npos2x = c.spot_position(spot2)\n```\n\nCanvas image export\n-------------------\n\nThe `Canvas` object supports image export to RAW and PNG file formats.\nBoth 8-bit and 16-bit PNG sample formats are supported.\nExport to PNG formats requires the default `png` feature to be enabled.\n\n### Example image export code\n\n```python\nfrom pyplanetarium import Canvas, ImageFormat\n\nc = Canvas.new(256, 256)\n\nc.set_background(1000)\nc.clear()\n\n# Export to a 8-bit gamma-compressed grayscale RAW image.\nraw_8bpp_bytes = c.export_image(ImageFormat.RawGamma8Bpp)\n\n# Export to a 10-bit linear light grayscale little-endian RAW image.\nraw_10bpp_bytes = c.export_image(ImageFormat.RawLinear10BppLE)\n\n# Export to a 12-bit gamma-compressed grayscale little-endian RAW image.\nraw_12bpp_bytes = c.export_image(ImageFormat.RawLinear12BppLE)\n\n# Export to a 8-bit gamma-compressed grayscale PNG image.\npng_8bpp_bytes = c.export_image(ImageFormat.PngGamma8Bpp)\n\n# Export to a 16-bit linear light grayscale PNG image.\npng_16bpp_bytes = c.export_image(ImageFormat.PngLinear16Bpp)\n```\n\nWindow image export\n-------------------\n\nThe `Canvas` object additionally supports windowed image export.\n\nA single rectangular window represents a region of interest (ROI)\non the canvas image. Window rectangle coordinates are represented\nby the public `Window` structure.\n\n### Example window image export code\n\n```python\nfrom pyplanetarium import Canvas, ImageFormat, Window\n\nc = Canvas.new(256, 256)\n\n# Create a 64x32 pixels window with origin at (90, 120).\nwnd = Window.new(64, 32).at(90, 120)\n\nfmt = ImageFormat.RawGamma8Bpp\n\n# Export to the canvas window image bytes.\nraw_window_bytes = c.export_window_image(wnd, fmt)\n```\n\nSubsampled image export\n-----------------------\n\nThe `Canvas` object additionally supports subsampled image export\nwith independent row and column subsampling factors.\n\nOnly whole canvas images can be exported with subsampling.\n\n### Example subsampled image export code\n\n```python\nfrom pyplanetarium import Canvas, ImageFormat\n\nc = Canvas.new(256, 256)\n\nfmt = ImageFormat.RawLinear10BppLE\n\n# Column (X) and row (Y) subsampling factors\nfactors = (2, 2)\n\n# Export to the subsampled canvas image bytes.\nraw_sub_bytes = c.export_subsampled_image(factors, fmt)\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python bindings for Rust Planetarium rendering library",
"version": "0.2.1",
"split_keywords": [
"astronomy",
"simulation",
"python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c80991997f1a61c6cfb447850b99e7efb1213426312c8bc9e005eff6da34b11b",
"md5": "28efd062ff5a099c347f73c6019f3629",
"sha256": "54c6859e0affabfdd3341bb842f4a4ec2115a2fd3bf99cd1b71b6dde4f09d228"
},
"downloads": -1,
"filename": "pyplanetarium-0.2.1-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "28efd062ff5a099c347f73c6019f3629",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 300208,
"upload_time": "2023-04-03T09:15:02",
"upload_time_iso_8601": "2023-04-03T09:15:02.808518Z",
"url": "https://files.pythonhosted.org/packages/c8/09/91997f1a61c6cfb447850b99e7efb1213426312c8bc9e005eff6da34b11b/pyplanetarium-0.2.1-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "967e4362d4d9c381159f35fa736400b870714fef1a22071fc7fc8f1774577eb2",
"md5": "8cd32dc254e8cc0e9f75fba21094ad2f",
"sha256": "272bdb99b92bdec0aa1dffa26eb81b55637299c7d10aca9c7a606a209d22478b"
},
"downloads": -1,
"filename": "pyplanetarium-0.2.1-cp37-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "8cd32dc254e8cc0e9f75fba21094ad2f",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 294356,
"upload_time": "2023-04-03T09:15:04",
"upload_time_iso_8601": "2023-04-03T09:15:04.197161Z",
"url": "https://files.pythonhosted.org/packages/96/7e/4362d4d9c381159f35fa736400b870714fef1a22071fc7fc8f1774577eb2/pyplanetarium-0.2.1-cp37-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3de882123b4d30c793918b0bd000932c5f8b6483abdfdb7f9b42048881275e6d",
"md5": "ae93a848101e436aecbdb21c05a1ad3a",
"sha256": "4fd6201d28f74527dffde0135fb8544dc645be71dfe520b0db6b289fa6f66d1b"
},
"downloads": -1,
"filename": "pyplanetarium-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "ae93a848101e436aecbdb21c05a1ad3a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 28067,
"upload_time": "2023-04-03T09:15:05",
"upload_time_iso_8601": "2023-04-03T09:15:05.912032Z",
"url": "https://files.pythonhosted.org/packages/3d/e8/82123b4d30c793918b0bd000932c5f8b6483abdfdb7f9b42048881275e6d/pyplanetarium-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-03 09:15:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "pyplanetarium"
}
JSON