DAMIT Asteroid Models¶

Stream-download the DAMIT complete export to filepath.

Creates parent directories if they do not exist. The file is first written to a .tmp sibling and atomically renamed on successful completion, preventing partial downloads from corrupting the cache.

Parameters:

Returns:

Raises:

Extract the DAMIT tar.gz archive to extract_dir.

Uses tarfile.extractall with the data filter on Python 3.12+ for safety, falling back to manual member filtering on older versions. A .extracted marker file is written on success so callers can detect whether the extraction is up-to-date relative to the archive.

Parameters:

Returns:

Raises:

Build a mapping from model ID to relative shape file path.

Walks the files/ directory tree looking for directories matching model_<N> that contain a shape.txt file.

Parameters:

Returns:

Load the shape mesh for a specific DAMIT model.

When extracted_dir is provided, looks for the shape file directly on disk (fast O(1) read). Otherwise falls back to scanning the tar.gz archive.

Parameters:

Returns:

Raises:

Parse the asteroids.csv table from a DAMIT tar.gz archive.

Reads tables/asteroids.csv from the compressed archive and returns a Polars DataFrame with asteroid identity information. The created and modified timestamp columns are dropped.

When extracted_dir is provided and contains the expected CSV file, it is read directly from disk (fast path) instead of decompressing the tar.gz archive.

Parameters:

Returns:

Raises:

Parse the asteroid_models.csv table from a DAMIT tar.gz archive.

This table is the canonical source for spin parameters (lambda, beta, period, yorp, jd0, phi0) as well as physical properties (diameter, albedo, thermal inertia) and model quality flags.

When extracted_dir is provided and contains the expected CSV file, it is read directly from disk (fast path) instead of decompressing the tar.gz archive.

Parameters:

Returns:

Raises:

Parse a DAMIT shape.txt file into vertices and facets.

The file format is:

• Line 1: N_vertices N_facets
• Next N_vertices lines: x y z whitespace-separated coordinates
• Next N_facets lines: v1 v2 v3 whitespace-separated 1-indexed vertex indices

Facet indices are converted from 1-indexed to 0-indexed.

Parameters:

Returns:

Raises:

Build and persist the shape index JSON file.

Locates the files/ directory inside extracted_dir, builds the model-ID-to-path mapping, and writes it as extracted_dir/shape_index.json.

Parameters:

Returns:

Load the shape mesh for a specific DAMIT model.

Downloads the DAMIT archive if needed, extracts it, then reads model_{model_id}/shape.txt directly from disk.

Parameters:

Returns:

Raises:

Examples:

from astrojax.datasets import get_damit_shape
vertices, facets = get_damit_shape(model_id=42)
print(vertices.shape, facets.shape)

Look up spin parameters for an asteroid from a pre-loaded models DataFrame.

Filters the models table by asteroid_id and returns the row at model_index as a dictionary. Multiple models may exist for a single asteroid; use model_index to select among them.

Parameters:

Returns:

Raises:

Examples:

from astrojax.datasets import load_damit_models, get_damit_spin
models = load_damit_models()
spin = get_damit_spin(models, asteroid_id=1)
print(spin["lambda"], spin["beta"], spin["period"])

Load the DAMIT asteroids table from a local cache, downloading when stale.

Checks whether the cached tar.gz at filepath exists and is younger than max_age_days. If the file is missing or stale, a fresh copy is downloaded from the DAMIT server.

Parameters:

Returns:

Raises:

Examples:

from astrojax.datasets import load_damit_asteroids
df = load_damit_asteroids()
print(df.shape)

Load the DAMIT asteroid models table from a local cache, downloading when stale.

The models table contains spin parameters (lambda, beta, period, yorp, jd0, phi0) and physical properties (diameter, albedo, thermal inertia) for all principal-axis rotator models in DAMIT.

Parameters:

Returns:

Raises:

Examples:

from astrojax.datasets import load_damit_models
df = load_damit_models()
print(df.columns)

Compute the body-to-ecliptic rotation matrix from DAMIT spin parameters.

Implements the principal-axis rotation model used by DAMIT:

R = Rz(lambda) @ Ry(90 - beta) @ Rz(phi0 + 360/P * (t-t0) * 24 + 0.5 * yorp * (t-t0)^2)

where time differences are in days, period P is in hours, and YORP acceleration is in deg/day^2.

Parameters:

Returns:

Examples:

import jax.numpy as jnp
from astrojax.datasets import damit_spin_to_rotation

spin = jnp.array([30.0, 60.0, 5.0, 2460000.5, 0.0, 0.0])
R = damit_spin_to_rotation(spin, 2460001.5)
print(R.shape)  # (3, 3)

Rotate shape vertices from body-fixed to ecliptic frame.

Computes the rotation matrix via :func:damit_spin_to_rotation and applies it to all vertex positions: (R @ vertices.T).T.

Parameters:

Returns:

Examples:

import jax.numpy as jnp
from astrojax.datasets import rotate_shape_points

spin = jnp.array([30.0, 60.0, 5.0, 2460000.5, 0.0, 0.0])
verts = jnp.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
rotated = rotate_shape_points(spin, 2460001.5, verts)

Rescale shape vertices so the furthest vertex is at a given distance.

Normalizes the vertex cloud by its current maximum extent (distance from origin to furthest vertex), then scales to max_extent_m.

Parameters:

Returns:

Examples:

import jax.numpy as jnp
from astrojax.datasets import scale_shape_vertices

verts = jnp.array([[1.0, 0.0, 0.0], [0.0, 2.0, 0.0]])
scaled = scale_shape_vertices(verts, 100.0)
# Furthest vertex is now at distance 100.0

Compute spherical-projection UV coordinates for mesh vertices.

Projects each vertex onto a unit sphere centred at the mesh centroid and maps the resulting spherical coordinates to the [0, 1] UV range.

Parameters:

Returns:

Examples:

from astrojax.datasets import get_damit_shape, compute_spherical_uvs
verts, faces = get_damit_shape(model_id=42)
uvs = compute_spherical_uvs(verts)
print(uvs.shape)  # (N, 2)

Export DAMIT shape data to a GLB (binary glTF) file.

Parameters:

Returns:

Raises:

Examples:

from astrojax.datasets import get_damit_shape, export_shape_glb
verts, faces = get_damit_shape(model_id=42)
export_shape_glb(verts, faces, "asteroid.glb")

Export DAMIT shape data to a textured GLB (binary glTF) file.

Applies a texture to the mesh using spherical UV projection. The texture is embedded as a PBR base-color map in the exported GLB.

Parameters:

Returns:

Raises:

Examples:

from PIL import Image
from astrojax.datasets import get_damit_shape, export_shape_glb_textured
verts, faces = get_damit_shape(model_id=42)
tex = Image.open("texture.tif")
export_shape_glb_textured(verts, faces, "asteroid.glb", tex)

Export DAMIT shape data to an STL file.

Parameters:

Returns:

Raises:

Examples:

from astrojax.datasets import get_damit_shape, export_shape_stl
verts, faces = get_damit_shape(model_id=42)
export_shape_stl(verts, faces, "asteroid.stl")

Convert DAMIT shape arrays to a trimesh Trimesh object.

Parameters:

Returns:

Raises:

Examples:

from astrojax.datasets import get_damit_shape, shape_to_trimesh
verts, faces = get_damit_shape(model_id=42)
mesh = shape_to_trimesh(verts, faces)
print(mesh.is_watertight)