Metadata-Version: 2.1
Name: pynyhtm
Version: 0.1.0
Summary: Python wrapper for the libtinyhtm library.
Author-email: Till <till@fleisch.dev>
License: # PynyHTM license
        
        The libtinyhtm library, located under 'libtinyhtm/', and resulting binaries are published under a variant of the 3-clause BSD license, as states in [Caltech-IPAC/libtinyhtm LICENSE](https://github.com/Caltech-IPAC/libtinyhtm/blob/master/LICENSE.txt).
        All other parts of this project are licensed under the MIT license.
        
        # MIT License
        
        Copyright (c) [2024] [Till Fleisch]
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/TillFleisch/PynyHTM
Project-URL: Repository, https://github.com/TillFleisch/PynyHTM.git
Project-URL: Issues, https://github.com/TillFleisch/PynyHTM/issues
Keywords: htm,libtinyhtm,hierarchial triangular mesh,triangle subdivision,index
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: numpy
Requires-Dist: tomli ; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: black ; extra == 'dev'
Requires-Dist: isort ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'

# PynyHTM

PynyHTM is a Cython based Python wrapper for [libtinyhtm](https://github.com/Caltech-IPAC/libtinyhtm/), the minimalistic hierarchal triangular mesh library.
*libtinyhtm*, developed by *Serge Monkewitz* and *Walter Landry* is based on prior work from *Alex Szalay*, *Gyorgy Fekete* and *Jim Gray* in [Searchable Sky Coverage of Astronomical Observations: Footprints and Exposures](https://doi.org/10.48550/arXiv.1005.2606) and [Indexing the Sphere with the Hierarchical Triangular Mesh](https://doi.org/10.48550/arXiv.cs/0701164).

Hierarchal triangular meshes(HTM) use the sub-division of triangles, which are projected onto a sphere, to elegantly and efficiently partition the earth or the sky into regions with different identifiers.

## Usage sample

The code snippets below are available in [this example file](example.py).
Classes `SphericalCoordinate` and `V3` cover basic functionality for expressing points in 3D space.

```python
from pynyhtm import HTM, SphericalCoordinate, Triangle, V3

# Retrieve HTM ID for a spherical coordinate
sc_1 = SphericalCoordinate(10.1234, -20.1234)
id = sc_1.get_htm_id(level=14)
print(f"HTM-ID for sc_1: {id} at level 14")
# >>> HTM-ID for sc_1: 3278525534 at level 14

# Convert spherical coordinate to vector
v_1 = sc_1.to_v3()

# Retrieve HTM ID for a V3 vector
v_2 = V3(0.1,0.2,0.3)
id = v_2.get_htm_id(level=3)
print(f"HTM-ID for v_2: {id} at level 3")
# >>> HTM-ID for v_2: 986 at level 3

# Conversion from vector to spherical coordinate
sc_2 = v_2.to_sc()

diff = sc_1.angle_separation(sc_2)
print(f"Angle between sc_1 and sc_2 (v2): {diff}")
# >>> Angle between sc_1 and sc_2 (v2): 78.05738774142326
```

Triangles, instantiated from the `Triangle` class provide additional information about a trixel within the HTM. They contain the three vertices which make up a Trixel as well as the center and more additional information.

```python
# Retrieve additional information about a triangle within the HTM
triangle = Triangle.from_id(id)
print(f"This triangle is in level {triangle.level}")
# >>> This triangle is in level 3

sc_center = triangle.center.to_sc()
print(f"The center is located at {sc_center}")
# >>> The center is located at SphericalCoordinate({'_latitude': 57.03662706265828, '_longitude': 59.20954536171413})
```

The `HTM` class contains more helpers to manage HTM identifiers.

```python

print(f"The Triangle with id {id} is located at level {HTM.get_level(id)}")
# >>> The Triangle with id 986 is located at level 3

print(f"The ID can also be expressed in it's subdivision form: {HTM.id_to_dec(id)}")
# >>> The ID can also be expressed in it's subdivision form: 23122

# Determine the children of a given triangle
children = HTM.children(id)
print(f"Children of {id}: {children}")
# >>> Children of 986: [3944, 3945, 3946, 3947]

# Determine the parent of a given id
parent = HTM.parent(id)
print(f"Parent of {id}: {parent}")
# >>> Parent of 986: 246

# Determine neighbors of a given triangle
neighbors = HTM.neighbors(id)
print(f"The neighbors of {id} are: {neighbors}")
# >>> The neighbors of 986 are: [987, 988, 1017]

# Search IDs within a circle around a given point
ids = HTM.circle_search(center=v_1, radius=0.5, level=7)
print(f"{ids} are located near center with radius 0.5")
# >>> [200104, 200105, 200106, 200107, 200108, 200134] are located near center with radius 0.5
```
