Types

AbstractShapeModel

Abstract base type for all shape models in AsteroidShapeModels.jl.

Concrete subtypes include:

• ShapeModel : Standard polyhedral shape model using triangular mesh representation
• HierarchicalShapeModel : Multi-scale shape model with localized surface roughness models

ShapeModel <: AbstractShapeModel

A polyhedral shape model of an asteroid using triangular mesh representation.

Fields

• nodes : Vector of node positions
• faces : Vector of vertex indices of faces
• face_centers : Center position of each face
• face_normals : Normal vector of each face
• face_areas : Area of each face
• face_visibility_graph : FaceVisibilityGraph for efficient visibility queries
• face_max_elevations : Maximum elevation angle of the surrounding terrain from each face [rad]
• bvh : Bounding Volume Hierarchy for accelerated ray tracing

See also: AbstractShapeModel, HierarchicalShapeModel

HierarchicalShapeModel <: AbstractShapeModel

A shape model that supports multi-scale surface representation through surface roughness models.

Fields

• global_shape : ShapeModel to represent the global shape of the asteroid
• face_roughness_indices : Mapping from face index to roughness model index (0 = no roughness)
• face_roughness_scales : Vector of scale factors for each face (1.0 = no roughness/identity)
• face_roughness_transforms : Vector of affine transformations (global to local) for each face (identity = no roughness)
• roughness_models : Vector of ShapeModel objects representing surface roughness

Description

This structure allows representing asteroid surfaces at two scales:

1. Global scale: The overall asteroid shape (global_shape)
2. Local scale: Surface roughness models attached to individual faces (roughness_models)

Each face of the global shape can have at most one roughness model attached to it. The face_roughness_indices array provides O(1) access to roughness models for any face.

Coordinate System Convention

The local coordinate system for each roughness model follows geographic conventions:

1. Origin: Face center, corresponding to (0.5, 0.5) in the roughness model's UV coordinates
2. Z-axis: Face normal (outward), representing "up" or elevation
3. Y-axis: Points towards north (projected onto the face plane)
4. X-axis: Points east (completing a right-handed coordinate system)

This convention ensures that:

• Roughness models have consistent north-aligned orientation across the surface
• UV coordinates [0,1]×[0,1] map naturally to local coordinates with (0.5, 0.5) at origin
• Height/elevation data in the roughness model corresponds to the local Z direction
• Solar azimuth angles can be computed intuitively (north = 0°, east = 90°)

Example

# Load global shape
global_shape = load_shape_obj("path/to/shape.obj", scale=1000)

# Create hierarchical model
hier_shape = HierarchicalShapeModel(global_shape)

# Add crater roughness to specific faces
crater = load_shape_obj("crater_roughness.obj", scale=10)
add_roughness_models!(hier_shape, crater, face_idx; scale=0.01)

Implementation Notes

The face_roughness_transforms field stores complete AffineMap transformations for each face, providing efficient O(1) access to coordinate transformations. Custom transformations can be provided via the transform parameter in add_roughness_models!, or they will be automatically computed to align with the face's local coordinate system

See also: AbstractShapeModel, ShapeModel

Ray

Structure representing a ray in 3D space.

Fields

• origin : Ray origin point
• direction : Ray direction vector (normalized)

Sphere

Structure representing a sphere in 3D space.

Fields

• center : Center position of the sphere
• radius : Radius of the sphere (must be non-negative)

RayTriangleIntersectionResult

Structure representing the result of ray-triangle intersection test.

Fields

• hit : true if intersection exists, false otherwise
• distance : Distance from ray origin to intersection point
• point : Coordinates of the intersection point

RayShapeIntersectionResult

Structure representing the result of ray-shape intersection test.

Fields

• hit : true if intersection exists, false otherwise
• distance : Distance from ray origin to intersection point
• point : Coordinates of the intersection point
• face_idx : Index of the intersected face

RaySphereIntersectionResult

Structure representing the result of ray-sphere intersection test.

Fields

• hit : true if intersection exists, false otherwise
• distance1 : Distance from ray origin to first intersection point (entry)
• distance2 : Distance from ray origin to second intersection point (exit)
• point1 : Coordinates of the first intersection point (entry)
• point2 : Coordinates of the second intersection point (exit)

Notes

• If hit is false, all other fields contain NaN values
• distance1 ≤ distance2 (entry point comes before exit point)
• For tangent rays, distance1 == distance2 and point1 == point2

FaceVisibilityGraph

Efficient visible face graph structure using CSR (Compressed Sparse Row) format. Stores face-to-face visibility relationships with associated view factors and geometric data.

Fields

• row_ptr: Start index of visible face data for each face (length: nfaces + 1)
• col_idx: Indices of visible faces (column indices in CSR format)
• view_factors: View factors for each visible face pair
• distances: Distances between each visible face pair
• directions: Unit direction vectors between each visible face pair
• nfaces: Total number of faces
• nnz: Number of non-zero elements (total number of visible face pairs)

CSR Format

The CSR (Compressed Sparse Row) format provides:

• Memory efficiency: ~50% reduction compared to adjacency lists
• Cache locality: Sequential access pattern for better performance
• Fast iteration: Direct access to all visible faces from a given face

Data Access

For face i, its visible faces are stored at indices row_ptr[i] to row_ptr[i+1]-1:

• Visible face indices : col_idx[row_ptr[i]:row_ptr[i+1]-1]
• View factors : view_factors[row_ptr[i]:row_ptr[i+1]-1]
• Distances : distances[row_ptr[i]:row_ptr[i+1]-1]
• Directions : directions[row_ptr[i]:row_ptr[i+1]-1]

Use the provided API functions instead of direct field access:

• get_visible_face_indices(graph, face_idx) - Get indices of visible faces
• get_view_factors(graph, face_idx) - Get view factors to visible faces
• get_visible_face_distances(graph, face_idx) - Get distances to visible faces
• get_visible_face_directions(graph, face_idx) - Get direction vectors to visible faces
• get_visible_face_data(graph, face_idx, idx) - Get all data for a specific visible face
• num_visible_faces(graph, face_idx) - Get number of visible faces

Example

If face 1 sees faces [2,3] and face 2 sees faces [1,3,4]:

row_ptr = [1, 3, 6, 7]          # Face 1 data at [1:2], Face 2 at [3:5], Face 3 at [6:6]
col_idx = [2, 3, 1, 3, 4, ...]  # Visible face indices

See also: build_face_visibility_graph!, get_visible_face_indices

build_bvh!(shape::ShapeModel)

Build a Bounding Volume Hierarchy (BVH) for the shape model for ray tracing. The BVH is stored in the shape.bvh field.

Arguments

• shape: The shape model to build the BVH for

Returns

• Nothing (modifies shape in-place)

Performance

• Building time: O(n log n) where n is the number of faces
• Ray intersection speedup: ~50x compared to previous implementations

When to use

• Required before calling intersect_ray_shape (as of v0.4.0)
• Required for shape2 argument in apply_eclipse_shadowing! (as of v0.4.0)
• When loading a shape without with_bvh=true
• Alternative to with_bvh=true in load_shape_obj for existing shapes

Example

# Load shape without BVH
shape = load_shape_obj("path/to/shape.obj"; scale=1000)

# Build BVH before ray intersection (required in v0.4.0)
build_bvh!(shape)

# Now ray intersection can be performed
ray = Ray(SA[1000.0, 0.0, 0.0], SA[-1.0, 0.0, 0.0])
result = intersect_ray_shape(ray, shape)

# Or load with BVH directly
shape = load_shape_obj("path/to/shape.obj"; scale=1000, with_bvh=true)

Notes

This function creates bounding boxes for each triangular face and constructs an implicit BVH tree structure for efficient ray-shape intersection queries. The BVH uses the ImplicitBVH.jl package which provides cache-efficient traversal.

See also: load_shape_obj with with_bvh=true, intersect_ray_shape, apply_eclipse_shadowing!