Types

ShapeModel

A polyhedral shape model of an asteroid.

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

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!