Skip to main content

Python based tools for spherical geometry

Project description

Documentation Status Spherical Geometry's Github Actions CI Status Spherical Geometry's Coverage Status PyPI 10.5281/zenodo.10020243

The spherical_geometry library is a Python package for handling spherical polygons that represent arbitrary regions of the sky.

Installation

On PyPI:

pip install spherical-geometry

On conda:

conda install -c conda-forge spherical-geometry

Requirements

  • Python 3.9 or later

  • Numpy 1.23 or later

  • astropy 5.0.4 or later

  • qd-library 2.3.7 or later (optional: if not available, the bundled version will be used). To force using the system-installed version, build with USE_SYSTEM_QD=1 pip install ..

Bundled qd-library

Origin: https://www.davidhbailey.com/dhbsoftware/qd-2.3.24.tar.gz

  • A custom libqd/include/qd/qd_config.h is provided to circumvent the need to run any configuration scripts. This generalized configuration may not be optimized for your system.

  • The spherical_geometry test suite fail when linked to a system-optimized qd library, because the tests are written for the general case.

Coordinate representation

Coordinates in world space are traditionally represented by right ascension and declination (ra and dec), or longitude and latitude. While these representations are convenient, they have discontinuities at the poles, making operations on them trickier at arbitrary locations on the sky sphere. Therefore, all internal operations of this library are done in 3D vector space, where coordinates are represented as (x, y, z) vectors. The spherical_geometry.vector module contains functions to convert between (ra, dec) and (x, y, z) representations.

While any (x, y, z) triple represents a vector and therefore a location on the sky sphere, a distinction must be made between normalized coordinates that fall exactly on the unit sphere, and unnormalized coordinates which do not. A normalized coordinate is defined as a vector whose length is 1, i.e.:

\begin{equation*} \sqrt{x^2 + y^2 + z^2} = 1 \end{equation*}

To prevent unnecessary recomputation, many methods in this library assume that the vectors passed in are already normalized. If this is not the case, spherical_geometry.vector.normalize_vector can be used to normalize an array of vectors.

When not working in Cartesian vectors, the library allows the user to work in either degrees or radians. All methods that require or return an angular value have a degrees keyword argument. When degrees is True, these measurements are in degrees, otherwise they are in radians.

Spherical polygons

Spherical polygons are arbitrary areas on the sky sphere enclosed by great circle arcs. They are represented by the ~spherical_geometry.polygon.SphericalPolygon class.

Representation

The points defining the polygon are available from the ~polygon.SphericalPolygon.points property. It is a Nx3 array where each row is an (x, y, z) vector, normalized. The polygon points are explicitly closed, i.e., the first and last points are the same.

Where is the inside?

The edges of a polygon serve to separate the “inside” from the “outside” area. On a traditional 2D planar surface, the “inside” is defined as the finite area and the “outside” is the infinite area. However, since the surface of a sphere is cyclical, i.e., it wraps around on itself, the a spherical polygon actually defines two finite areas. To specify which should be considered the “inside” vs. the “outside”, the definition of the polygon also has an “inside point” which is just any point that should be considered inside of the polygon.

In the following image, the inside point (marked with the red dot) declares that the area of the polygon is the green region, and not the white region.

inside.png

The inside point of the the polygon can be obtained from the ~polygon.SphericalPolygon.inside property.

What is the orientation?

The correctness of several of the algorithms using polygons depends on a consistent orientation of the points defining it. That is, the points should have a clockwise order. When creating a new spherical polygon, the order of the points defining a polygon will be reversed if they are not in clockwise order. The method SphericalPolygon.is_clockwise is used to est if the points are in clockwise order. It takes two successive sides and computes the normal vector to the sides. If the normal vector points inward towards the center of the sphere, the two sides are counter clockwise. If the normal vector points outward, the two sides are clockwise. The code determines the orientation by computing the triple product of the two sides with the vertex of the the two sides. Summing the triple product over all the sides gives the predominant orientation of the points in the polygon.

Disjoint Polygons

If a polygon is the result of the intersection of polygons, it may be disjoint. Disjoint polygons are represented as a list of spherical polygons. The library handles the details of this internally. However, the user must be aware that several of the properties of polygons are generators and return the value for a single polygon at a time. To access all the values of a proeprty, either use a for loop, or coerce the property to a list. The properties which are generators are:

  • SphericalPolygon.points: The points defining each polygon

  • SphericalPolygon.inside : The inside point of each polygon

If the intersection of two polygons generates disjoint polygons the code computes a new interior point for the disjoint polygons.

Creating spherical polygons

SphericalPolygon objects have 5 different constructors:

  • SphericalPolygon: Takes an array of (x, y, z) points, or a list of disjoint SphericalPolygon instances.

  • SphericalPolygon.from_radec: Takes an array of (ra, dec) points and an inside point.

  • SphericalPolygon.from_cone: Creates a polygon from a cone on the sky shere. Takes (ra, dec, radius).

  • SphericalPolygon.from_wcs: Creates a polygon from the footprint of a FITS image using its WCS header keywords. Takes a FITS filename or a astropy.io.fits.Header object.

  • SphericalPolygon.convex_hull: Creates a polygon that is the convex hull of a list of points.

Operations on Spherical Polygons

Once one has a SphericalPolygon object, there are a number of operations available:

  • ~SphericalPolygon.contains_point: Determines if the given point is inside the polygon.

  • ~SphericalPolygon.intersects_poly: Determines if one polygon intersects with another.

  • ~SphericalPolygon.area: Determine the area of a polygon.

  • ~SphericalPolygon.union and ~SphericalPolygon.multi_union: Return a new polygon that is the union of two or more polygons.

  • ~SphericalPolygon.intersection and ~SphericalPolygon.multi_intersection: Return a new polygon that is the intersection of two or more polygons.

  • ~SphericalPolygon.overlap: Determine how much a given polygon overlaps another.

  • ~SphericalPolygon.to_radec: Convert (x, y, z) points in the polygon to (ra, dec) points.

  • ~SphericalPolygon.draw: Plots the polygon using matplotlib’s Basemap toolkit. This feature is rather bare and intended primarily for debugging purposes.

Great circle arcs

As seen above, great circle arcs are used to define the edges of the polygon. The spherical_geometry.great_circle_arc module contains a number of functions that are useful for dealing with them.

  • length: Returns the angular distance between two points on the sphere.

  • intersection: Returns the intersection point between two great circle arcs.

  • intersects: Determines if two great circle arcs intersect.

  • intersects_point: Determines if a point is along the great circle arc.

  • angle: Calculate the angle between two great circle arcs.

  • midpoint: Calculate the midpoint along a great circle arc.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spherical_geometry-1.3.3.tar.gz (8.7 MB view details)

Uploaded Source

Built Distributions

spherical_geometry-1.3.3-cp313-cp313-win_amd64.whl (7.7 MB view details)

Uploaded CPython 3.13Windows x86-64

spherical_geometry-1.3.3-cp313-cp313-win32.whl (7.7 MB view details)

Uploaded CPython 3.13Windows x86

spherical_geometry-1.3.3-cp313-cp313-musllinux_1_2_x86_64.whl (9.5 MB view details)

Uploaded CPython 3.13musllinux: musl 1.2+ x86-64

spherical_geometry-1.3.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.6 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

spherical_geometry-1.3.3-cp313-cp313-macosx_11_0_arm64.whl (7.7 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

spherical_geometry-1.3.3-cp313-cp313-macosx_10_13_x86_64.whl (7.7 MB view details)

Uploaded CPython 3.13macOS 10.13+ x86-64

spherical_geometry-1.3.3-cp312-cp312-win_amd64.whl (7.7 MB view details)

Uploaded CPython 3.12Windows x86-64

spherical_geometry-1.3.3-cp312-cp312-win32.whl (7.7 MB view details)

Uploaded CPython 3.12Windows x86

spherical_geometry-1.3.3-cp312-cp312-musllinux_1_2_x86_64.whl (9.5 MB view details)

Uploaded CPython 3.12musllinux: musl 1.2+ x86-64

spherical_geometry-1.3.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.6 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

spherical_geometry-1.3.3-cp312-cp312-macosx_11_0_arm64.whl (7.7 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

spherical_geometry-1.3.3-cp312-cp312-macosx_10_13_x86_64.whl (7.7 MB view details)

Uploaded CPython 3.12macOS 10.13+ x86-64

spherical_geometry-1.3.3-cp311-cp311-win_amd64.whl (7.7 MB view details)

Uploaded CPython 3.11Windows x86-64

spherical_geometry-1.3.3-cp311-cp311-win32.whl (7.7 MB view details)

Uploaded CPython 3.11Windows x86

spherical_geometry-1.3.3-cp311-cp311-musllinux_1_2_x86_64.whl (9.5 MB view details)

Uploaded CPython 3.11musllinux: musl 1.2+ x86-64

spherical_geometry-1.3.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.6 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

spherical_geometry-1.3.3-cp311-cp311-macosx_11_0_arm64.whl (7.7 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

spherical_geometry-1.3.3-cp311-cp311-macosx_10_9_x86_64.whl (7.7 MB view details)

Uploaded CPython 3.11macOS 10.9+ x86-64

File details

Details for the file spherical_geometry-1.3.3.tar.gz.

File metadata

  • Download URL: spherical_geometry-1.3.3.tar.gz
  • Upload date:
  • Size: 8.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for spherical_geometry-1.3.3.tar.gz
Algorithm Hash digest
SHA256 e0b90c6ca5a22b270c151e856e15dcb0a3d715ff13f13d2bbd492daae644540a
MD5 61d6418507c3dde2534fd3d71180d276
BLAKE2b-256 0247c34e40c3ce50a96134d14c298a4a5cc4dc9141c220a2c64aa242595f8c1f

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 a9bd710f90a71ea8d944763ddf47d231cee791daca423503557fe917e5f6ca9a
MD5 1653197a5dddca180566f236a83ff4b9
BLAKE2b-256 1a63cd53e72f91bf0a1ae49965dd0e47dca71fe8f593108297c6cdaefea63811

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp313-cp313-win32.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp313-cp313-win32.whl
Algorithm Hash digest
SHA256 d83c852002c969d129c2c0bedf57b367804d16e909fb091e62900d7eb1c9f3d4
MD5 e84198c1ffc8f29f8771c0062a3bbb61
BLAKE2b-256 851519284903d9064fcc6733137fbcfaa699067a8babd1dea17f323f5cb5a71d

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp313-cp313-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp313-cp313-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 e4a0e8e1a5b682be9a533c0f3b7961477a5a08ec652df65c7ecdd1e75c38e50b
MD5 9e942430d87294216ed155d9ab577bd8
BLAKE2b-256 8cd6c2e277d69dab54438ba7e6bf929f7ba5bb09f6b848247d8029148a530ca2

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ac746b11447c21faa575bb2db8707be3e1c8917657ed975dad2582ecae1da019
MD5 3937ef97b2c00adb8d6a7b4c1cbe1421
BLAKE2b-256 1940cf00513e63b42de878a793ed1d89fc9f5e15e9d0d66dec34b6e4890914e2

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c0ef5dfc96f89fc2d7ecf5537aa450a72c743f9417cd445b092736641a4a5cea
MD5 4f27f17ee0562994db039bb619c8cbab
BLAKE2b-256 60c7f6f5a874b1822c2bfa298c7a3c12b3f63fa855320e944361ca0fb1cc57de

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp313-cp313-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp313-cp313-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 60f5ddafb24c8e56374b2d47207c9aa7c1a9d2e7e5abcb9ac6056bfd968790b6
MD5 f0214b4b90d5d620ac08a0331b06f2aa
BLAKE2b-256 0f323cd8cb430d7ab070b079d395f0f0aec9e7da488d4ef39f3bbcb2531884f8

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 9846eaf1efe761b7abbc3b477a08fc0b5e0440c2751777e31d7dff98deb82d46
MD5 68a78fcf312d623a58b10a683aec7c5a
BLAKE2b-256 5c623617510cb02ef1b807ef58c88e6b078fb59eb8a9d7d4cfe2aabb08b92180

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp312-cp312-win32.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp312-cp312-win32.whl
Algorithm Hash digest
SHA256 0b15bec5add03a34d00fea443f5c6595525a98507cc5cd2e88d18aba79d25d3a
MD5 965e9f0671d21c2cebd6fbe59abcf7a5
BLAKE2b-256 f56781f8d6ab1a450df952d17b0d295a76d7a58b5e66653f1920916a375858ef

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp312-cp312-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp312-cp312-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 0ab8382b87f461e26de828e96f44e03589d591b3ec524f6dfe1fdb71b2f4521a
MD5 56edd50f9e41b9e6943305558ca7b2e9
BLAKE2b-256 9d69e61dce23af5f445a9c7e574001f1df08f3255c7cb32c9bb55871769bb657

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fa4debfbef86de2afb54a7a1e484e3b649fdb707a95edd2cfdeffca78853e216
MD5 49535bf0bee3471a3e3b4416c62835a4
BLAKE2b-256 dfa126be91772893d7cfdac1f2190667435e888bd6204bc88553394a35943608

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 604e2cbbb569ad415bf4e07fa93f30e59c64214f127d6d93c9b9237381d816b2
MD5 3740157a3121c31f6ab5552ac8510393
BLAKE2b-256 e2d56e7ca1b12b621095c098f76830717b7b77ec41f4913360d782a46f59d58e

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp312-cp312-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp312-cp312-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 88eb8272d733c7881d7f9fd0e24b309446a2f2e9a558a79aa92c0fabf5d54050
MD5 40e4dade003d3fc602a86e542ad32e09
BLAKE2b-256 60ca78f4e4c71024814d177e3521a9349eb3df0d58e2a45f9046dd7cfad6fb06

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 1cf4218d38c2eda964135cebb36018a92321271e653c5e97d0fd117576617c58
MD5 d1b64f81e82a589cc6d4ad320a7d0c54
BLAKE2b-256 5a2c384a842a7d6f98cc60a0ad34eba7469d60286cb78aa093cebcb62068021b

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp311-cp311-win32.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp311-cp311-win32.whl
Algorithm Hash digest
SHA256 90560760d8defd250bce556fa57ab5c4c1c45c96ac62d6e2dac36694214bf1d7
MD5 7dff99fc2e2b5e362c58264cdc63e0cb
BLAKE2b-256 cd522ffad628a89b4fcdc8732f38ed768755a68bdffb139274a0c0d9bc3346e1

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp311-cp311-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp311-cp311-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 8cb2a8b2d61a1b0566483335a6cf11fc1eb23d6ce0a0cf791fcd2794da4168e0
MD5 493db0bc94b082509dbed0938e135175
BLAKE2b-256 f8de5cd8f5c401e1bed9909f797a95625982d5c1aaae7d32821b66d974ac7573

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6e46bb532ab1e49e32fb05437063664d0b2df494a83f2271c72c4a4e0f478541
MD5 2f5b9bbe9ee471cf69f9ae200c565e75
BLAKE2b-256 060d6f29bfc916cd5c1132ae07fc111ab94a0baf742946fb82d63347a8bea0a3

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 632db5b17d09173832185fdcc41a9ecece5b13b819f67ff84ef00f71498a1b1b
MD5 c2b016f94df114a49ee681d2607877a7
BLAKE2b-256 edda0770270dbeb1a54e6353435e6d4e8ee1ef95f040d9610e3b3ac90be4b4d2

See more details on using hashes here.

File details

Details for the file spherical_geometry-1.3.3-cp311-cp311-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for spherical_geometry-1.3.3-cp311-cp311-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 cf73f04cedb325ae16a78b522c1cf0ec3b6d829718f82945e97d932cb75b7ff1
MD5 a8648df09fc62422e2c1538883569fd8
BLAKE2b-256 996488c5fa9ed11314e31d1f062399ae752974d56f4487a143617339447b6cee

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page