QLSC: Quadrilateralized Spherical Cube for Python

Introduction

The quadrilateralized spherical cube (QLSC) is a geospatial indexing scheme for segmenting a sphere into pixels with the aim of optimized spatial indexing and queries. QLSC is an implementation of this scheme in a Python package. Parts of it are based on code from Sergey Koposov’s Q3C, a PostgreSQL extension that implements QLSC indexing. In addition to sphere segmentation, this package provides the catalog indexing functionality of Q3C without the need to install a PostgreSQL database.

Note that while this package is designed for astronomical use (it focusses on right ascension and declination), it could be just as easily be used for latitude and longitude coordinates, as long as you’re ok with a perfectly spherical Earth (though QLSC was designed to be used with the real Earth). Future updates may better facilitate this, but contributions are welcome.

Author: Demitri Muna Copyright © 2020 Demitri Muna, except for the embedded Q3C code which is copyright Sergey Koposov.

Why Use QLSC?

• You have a large number of points or regions on a sphere that you want to subdivide into approximately equal area divisions.
• You are an astronomer with a catalog that you want to perform cone searches on, but don't want to install a full database to do so.
• You want a spherical projection scheme without all that polar singularity residue.
• You want a scheme that divides a sphere into regions that are easy to conceptualize, draw, and work with, where you can easily control the resolution down to ~0.08 µ".

Installation

Install from PyPi

pip install qlsc

Install from source

git clone https://github.com/demitri/qlsc.git
cd qlsc/source
python setup.py install

API Documentation

API documentation can be found here: https://qlsc.readthedocs.io/en/latest/

60 Second Segmentation Introduction

If you’re not familiar with the QLSC scheme it would be better to start below. There are two classes defined in this package, QLSC and QLSCIndex. The QLSC scheme projects each of the six faces of a cube onto a sphere. Segmentation is performed on the cube faces and performed in levels, where each level divides each bin into four. For example, depth=2 divides each bin into four, then of those into four again, which is 2^(2*depth) (i.e. 16) bins per cube face, or 96 total bins. ("Pixels" and "bin" are used somewhat interchangeably.)

The class can convert between (ra,dec) positions and the pixel number (ipix).

from qlsc import QLSC

q = QLSC(depth=2)
q.ang2ipix(45,45)     # ra,dec -> ipix number
q.ipix2ang_center(42) # ipix number -> ra,dec at center of pixel
q.ipix2polygon(42)    # returns the points on the sphere describing
                      # the pixel (joined by great circles)

60 Second Cone Search Introduction

Performing cone searches is as simple as creating a QLSCIndex index object and populating it with coordinates. The highest sphere segmentation resolution is selected by default, but a lower resolution can be chosen. By default, the index is stored in memory, but a file may be chosen so that the index can be reused as a script is rerun or by multiple scripts. Points are added in α,δ coordinates in degrees. Once points are added to the index you can perform a cone search.

The example below uses an included function to generate any number of points evenly distributed on a sphere (useful for testing).

from qlsc import QLSCIndex
from qlsc.generate import sunflower_points_on_sphere

index = QLSCIndex() # created in memory, defaults to highest resolution

# add ra,dec points from a NumPy array (shape (n,2))
points = sunflower_points_on_sphere(n=1e5)
index.add_points(points=points)

# or individually
index.add_point(12., 34.)

# keys can also be attached to points
index.add_point(56.59625, 78.00866, key="a catalog ID")

# cone search at center α=56, δ=-40
matches = index.radial_query(ra=56., dec=-40., radius=0.5) # float deg or astropy.units.Quantity

Further examples are provided in the directory "examples" that show how the scheme and indexing can be used.

The Quadrilateralized Spherical Cube

The quadrilateralized spherical cube was first devised in 1975 in a technical report by F.K. Chan and E.M. O'Neill (available here). It begins with a cube inscribed within a sphere:

The six cube faces are then projected onto the sphere via transforms defined in the paper. This is the lowest resolution. Higher resolutions are achieved in steps: each step divides the bin, or pixel, into four. The first step will have four bins per face, the next will have 16, etc. The code refers to the level of subdivision as "depth" (number of times the bin has been subdivided), where the diagram above is depth=0. The Q3C PostgreSQL extension uses a depth of 30, which is 1,152,921,504,606,846,976 bins per cube face (six times that over the full sphere) corresponding to ~0.08 μ" square per pixel. The QLSC package supports any depth from 0 to 30.

The diagram below shows the pixel numbering scheme over the entire sphere for depth=2. Note the path of the numbering scheme: this is called z-order which has the benefit that ipix numbers that are close to one another are also close spatially.

The diagram below shows face 1 divided at depth=2 and the projection of each pixel onto the sphere. Other faces have been hidden for clarity.

The scheme is advantageous in that there are no discontinuities at the poles, and the indexing scheme is optimized for fast database queries. While not all pixels cover the same area, they are equal to within a few percent.

For most users, working in ipix values and ra,dec coordinates will accomplish most anything needed. For those who might be performing more complex calculations, I recommend working in the native coordinates of the face plane. Each face (at any division level) has its 2D coordinate system origin at the cube face center. Both the x and y axes range from -1 to +1. Methods are provided to translate between xy coordinates, ipix value, and ra/dec coordinates. The source code for the ipix2polygon() method provides an illustrative example.

References & Links

• Original Chan, O'Neill 1975 paper
• Abridged F.K. Chan paper - A Quadrilateralized Spherical Cube Earth Data Base
• Koposov, Bartunov Q3C ADASS proceedings paper
• Stack Overflow - Is the quadrilateralized spherical cube map projection the same as Snyder's cubic equal area map projection? (with comments from Ken Chan)
• Wikipedia - Quadrilateralized spherical cube
• COBE Quadrilateralized Spherical Cube

Appendix

For quick reference, the following table lists the parameters of the QLSC scheme for every available depth.