Data Structures
struct	htm_ids
	A sorted list of 64 bit integer ranges. More...
struct	htm_v3p
	A position and a payload. More...
struct	htm_tri
	A structure describing the geometry of an HTM triangle (aka a trixel). More...
Defines
#define	HTM_MAX_LEVEL 24
	Maximum HTM tree subdivision level.
#define	HTM_DEC_MAX_LEVEL 18
	Maximum level of a decimal index stored in a 64 bit signed integer.
Enumerations
enum	htm_root { HTM_S0 = 0, HTM_S1 = 1, HTM_S2 = 2, HTM_S3 = 3, HTM_N0 = 4, HTM_N1 = 5, HTM_N2 = 6, HTM_N3 = 7, HTM_NROOTS = 8 }
	Root triangle numbers. More...
Functions
struct htm_v3p	__attribute__ ((aligned(16)))
int64_t	htm_v3_id (const struct htm_v3 *point, int level)
	Computes an HTM ID for a position.
enum htm_errcode	htm_v3p_idsort (struct htm_v3p points, int64_t ids, size_t n, int level)
	Computes HTM IDs for a list of positions with payloads.
int	htm_level (int64_t id)
	Returns the HTM subdivision level of the given ID, or -1 if the ID is invalid.
enum htm_errcode	htm_tri_init (struct htm_tri *tri, int64_t id)
	Computes and stores the attributes of the HTM triangle with the given id.
struct htm_ids *	htm_s2circle_ids (struct htm_ids ids, const struct htm_v3 center, double radius, int level, size_t maxranges, enum htm_errcode *err)
	Returns a list of HTM ID ranges corresponding to the HTM triangles overlapping the given circle.
struct htm_ids *	htm_s2ellipse_ids (struct htm_ids ids, const struct htm_s2ellipse ellipse, int level, size_t maxranges, enum htm_errcode *err)
	Returns a list of HTM ID ranges corresponding to the HTM triangles overlapping the given ellipse.
struct htm_ids *	htm_s2cpoly_ids (struct htm_ids ids, const struct htm_s2cpoly poly, int level, size_t maxranges, enum htm_errcode *err)
	Returns a list of HTM ID ranges corresponding to the HTM triangles overlapping the given spherical convex polygon.
int64_t	htm_idtodec (int64_t id)
	Converts an HTM ID as returned by the various indexing functions to decimal form.
Variables
struct htm_tri	__attribute__

Define Documentation

#define HTM_DEC_MAX_LEVEL 18

Maximum level of a decimal index stored in a 64 bit signed integer.

Definition at line 32 of file htm.h.

Referenced by htm_idtodec().

Enumeration Type Documentation

enum htm_root

Root triangle numbers.

The HTM ID of a root triangle is its number plus 8.

Definition at line 36 of file htm.h.

Function Documentation

int64_t htm_idtodec ( int64_t id )

Converts an HTM ID as returned by the various indexing functions to decimal form.

Returns 0 if the input ID is invalid.

This function maps IDs produced by this library to IDs that are compatible with those currently stored in IRSA database tables.

Definition at line 1562 of file htm.c.

References HTM_DEC_MAX_LEVEL, and htm_level().

struct htm_ids* htm_s2circle_ids	(	struct htm_ids *	ids,
		const struct htm_v3 *	center,
		double	radius,
		int	level,
		size_t	maxranges,
		enum htm_errcode *	err
	)		`[read]`

Returns a list of HTM ID ranges corresponding to the HTM triangles overlapping the given circle.

A range list can be de-allocated by passing its pointer to free().

Parameters:

[in]	ids	Existing range list or NULL. If `ids` is NULL, a fresh range list is allocated and returned. If it is non-NULL, its entries are removed but its memory is reused. This can be used to avoid `malloc/realloc` costs when this function is being called inside of a loop.
[in]	center	Spherical circle center.
[in]	radius	Spherical circle radius (degrees).
[in]	level	Subdivision level, in range `[0, HTM_MAX_LEVEL]`.
[in]	maxranges	Maximum number of ranges to return. When too many ranges are generated, the effective subdivision level of HTM ids is reduced. Since two consecutive ranges that cannot be merged at level L may become mergable at level L-n, this "coarsening" cuts down on the number of ranges, but makes the range list a poorer approximation to the input geometry. Note that for arbitrary input geometry, up to 4 ranges may be generated no matter what the subdivision level is. So for maxranges < 4, the requested bound may not be achieved.
[out]	err	If an error occurs, `*err` is set to indicate the reason for the failure.

Returns:: A list of HTM ID ranges for the HTM triangles overlapping the given circle. A NULL pointer is returned in case of error, and *err is set to indicate the reason for the failure.

Note that the input range list may be reallocated (to grow its capacity), and so the input range list pointer may no longer point to valid memory. Always replace the input pointer with the return value of this function!

If a failure occurs, this function will free the memory associated with the range list (even it came from a non-NULL input pointer).

Definition at line 1147 of file htm.c.

References HTM_CONTAINS, HTM_ELEVEL, HTM_ENOMEM, HTM_ENULLPTR, HTM_INSIDE, HTM_INTERSECT, HTM_MAX_LEVEL, HTM_OK, HTM_RAD_PER_DEG, htm_ids::n, and root.

struct htm_ids* htm_s2cpoly_ids	(	struct htm_ids *	ids,
		const struct htm_s2cpoly *	poly,
		int	level,
		size_t	maxranges,
		enum htm_errcode *	err
	)		`[read]`

Returns a list of HTM ID ranges corresponding to the HTM triangles overlapping the given spherical convex polygon.

A range list can be de-allocated by passing its pointer to free().

Parameters:

[in]	ids	Existing range list or NULL. If `ids` is NULL, a fresh range list is allocated and returned. If it is non-NULL, its entries are removed but its memory is reused. This can be used to avoid `malloc/realloc` costs when this function is being called inside of a loop.
[in]	poly	Spherical convex polygon.
[in]	level	Subdivision level, in range `[0, HTM_MAX_LEVEL]`.
[in]	maxranges	Maximum number of ranges to return. When too many ranges are generated, the effective subdivision level of HTM ids is reduced. Since two consecutive ranges that cannot be merged at level L may become mergable at level L-n, this "coarsening" cuts down on the number of ranges, but makes the range list a poorer approximation to the input geometry. Note that for arbitrary input geometry, up to 4 ranges may be generated no matter what the subdivision level is. So for maxranges < 4, the requested bound may not be achieved.
[out]	err	If an error occurs, `*err` is set to indicate the reason for the failure.

Returns:: A list of HTM ID ranges for the HTM triangles overlapping the given polygon. A NULL pointer is returned in case of error, and *err is set to indicate the reason for the failure.

Note that the input range list may be reallocated (to grow its capacity), and so the input range list pointer may no longer point to valid memory. Always replace the input pointer with the return value of this function!

If a failure occurs, this function will free the memory associated with the range list (even it came from a non-NULL input pointer).

Definition at line 1417 of file htm.c.

References HTM_CONTAINS, HTM_ELEVEL, HTM_ENOMEM, HTM_ENULLPTR, HTM_INSIDE, HTM_INTERSECT, HTM_MAX_LEVEL, HTM_OK, htm_ids::n, htm_s2cpoly::n, and root.

struct htm_ids* htm_s2ellipse_ids	(	struct htm_ids *	ids,
		const struct htm_s2ellipse *	ellipse,
		int	level,
		size_t	maxranges,
		enum htm_errcode *	err
	)		`[read]`

Returns a list of HTM ID ranges corresponding to the HTM triangles overlapping the given ellipse.

A range list can be de-allocated by passing its pointer to free().

Parameters:

[in]	ids	Existing range list or NULL. If `ids` is NULL, a fresh range list is allocated and returned. If it is non-NULL, its entries are removed but its memory is reused. This can be used to avoid `malloc/realloc` costs when this function is being called inside of a loop.
[in]	ellipse	Spherical ellipse.
[in]	level	Subdivision level, in range `[0, HTM_MAX_LEVEL]`.
[in]	maxranges	Maximum number of ranges to return. When too many ranges are generated, the effective subdivision level of HTM ids is reduced. Since two consecutive ranges that cannot be merged at level L may become mergable at level L-n, this "coarsening" cuts down on the number of ranges, but makes the range list a poorer approximation to the input geometry. Note that for arbitrary input geometry, up to 4 ranges may be generated no matter what the subdivision level is. So for maxranges < 4, the requested bound may not be achieved.
[out]	err	If an error occurs, `*err` is set to indicate the reason for the failure.

Returns:: A list of HTM ID ranges for the HTM triangles overlapping the given ellipse. A NULL pointer is returned in case of error, and *err is set to indicate the reason for the failure.

Note that the input range list may be reallocated (to grow its capacity), and so the input range list pointer may no longer point to valid memory. Always replace the input pointer with the return value of this function!

If a failure occurs, this function will free the memory associated with the range list (even it came from a non-NULL input pointer).

Definition at line 1295 of file htm.c.

References HTM_CONTAINS, HTM_ELEVEL, HTM_ENOMEM, HTM_ENULLPTR, HTM_INSIDE, HTM_INTERSECT, HTM_MAX_LEVEL, HTM_OK, htm_ids::n, and root.

enum htm_errcode htm_tri_init	(	struct htm_tri *	tri,
		int64_t	id
	)

Computes and stores the attributes of the HTM triangle with the given id.

Returns:

HTM_ENULLPTR if tri is NULL.
HTM_EID if id is invalid.
HTM_OK on success.

Definition at line 1087 of file htm.c.

References htm_tri::center, HTM_EID, HTM_ENULLPTR, htm_level(), HTM_OK, htm_v3_add(), htm_v3_angsep(), htm_v3_normalize(), htm_tri::id, htm_tri::level, htm_tri::radius, and htm_tri::verts.

int64_t htm_v3_id	(	const struct htm_v3 *	point,
		int	level
	)

Computes an HTM ID for a position.

Returns:: The HTM ID for point, or 0 if point is NULL or level is not in the range [0, HTM_MAX_LEVEL].

Definition at line 980 of file htm.c.

References HTM_MAX_LEVEL, htm_v3_dot(), and htm_v3_rcross().

enum htm_errcode htm_v3p_idsort	(	struct htm_v3p *	points,
		int64_t *	ids,
		size_t	n,
		int	level
	)

Computes HTM IDs for a list of positions with payloads.

Positions and payloads are sorted by HTM ID during the id generation process.

Returns:

HTM_ENULLPTR if points or ids is NULL.
HTM_ELEN if n is 0.
HTM_ELEVEL if level is not in [0, HTM_MAX_LEVEL].
HTM_OK on success.

Definition at line 1036 of file htm.c.

References HTM_ELEN, HTM_ELEVEL, HTM_ENULLPTR, HTM_MAX_LEVEL, and HTM_OK.

Data Structures

Defines

Enumerations

Functions

Variables

Define Documentation

Enumeration Type Documentation

Function Documentation