I/O Functions

load_shape_obj(shapepath; scale=1.0, with_face_visibility=false, with_bvh=false) -> ShapeModel

Load a shape model from a Wavefront OBJ file.

Arguments

• shapepath::String: Path to a Wavefront OBJ file

Keyword Arguments

• scale::Real=1.0 : Scale factor for node coordinates (e.g., 1000 to convert km to m)
• with_face_visibility::Bool=false : Whether to build face-to-face visibility graph for illumination and thermophysical modeling
• with_bvh::Bool=false : Whether to build BVH for ray tracing (required for intersect_ray_shape and apply_eclipse_shadowing!)

Returns

• ShapeModel: Loaded shape model with computed geometric properties

Examples

# Load a shape model
shape = load_shape_obj("asteroid.obj")

# Load with scaling and visibility computation
shape = load_shape_obj("asteroid_km.obj"; scale=1000, with_face_visibility=true)

# Load with all features for comprehensive analysis
shape = load_shape_obj("asteroid.obj"; scale=1000, with_face_visibility=true, with_bvh=true)

See also: load_shape_grid, load_obj

load_obj(shapepath::String; scale=1) -> nodes, faces

Load a 3D shape model from an OBJ file.

Arguments

• shapepath::String: Path to the OBJ file

Keyword Arguments

• scale::Real=1: Scale factor to apply to all vertex coordinates. For example, use scale=1000 to convert from kilometers to meters

Returns

• nodes::Vector{SVector{3,Float64}}: Array of vertex positions
• faces::Vector{SVector{3,Int64}}: Array of triangular face definitions (1-indexed vertex indices)

Examples

# Load shape model in meters
nodes, faces = load_obj("asteroid.obj")

# Load shape model and convert from km to m
nodes, faces = load_obj("asteroid_km.obj", scale=1000)

# Get the number of nodes and faces
println("Number of nodes: ", length(nodes))
println("Number of faces: ", length(faces))

# Access individual nodes and faces
first_node = nodes[1]  # SVector{3, Float64}
first_face = faces[1]  # SVector{3, Int} with node indices

Notes

This function uses the FileIO/MeshIO packages to load OBJ files. Only triangular faces are supported.

isobj(filepath::String) -> Bool

Check if a file has the OBJ file extension.

Arguments

• filepath::String: Path to the file to check

Returns

• Bool: true if the file has .obj extension, false otherwise

Examples

isobj("model.obj")    # Returns true
isobj("model.stl")    # Returns false
isobj("model.OBJ")    # Returns false (case-sensitive)

load_shape_grid(xs, ys, zs; scale=1.0, with_face_visibility=false, with_bvh=false) -> ShapeModel

Convert a regular grid (x, y) with z-values to a shape model.

Arguments

• xs::AbstractVector: x-coordinates of grid points
• ys::AbstractVector: y-coordinates of grid points
• zs::AbstractMatrix: z-coordinates of grid points where zs[i,j] corresponds to (xs[i], ys[j])

Keyword Arguments

• scale::Real=1.0 : Scale factor to apply to all coordinates
• with_face_visibility::Bool=false : Whether to build face-to-face visibility graph for illumination and thermophysical modeling
• with_bvh::Bool=false : Whether to build BVH for ray tracing (required for intersect_ray_shape and apply_eclipse_shadowing!)

Returns

• ShapeModel: Shape model with computed geometric properties

Examples

# Create a shape from elevation data
xs = range(-10, 10, length=50)
ys = range(-10, 10, length=50)
zs = [exp(-(x^2 + y^2)/10) for x in xs, y in ys]  # Gaussian surface
shape = load_shape_grid(xs, ys, zs)

# With scaling and visibility
shape = load_shape_grid(xs, ys, zs, scale=1000, with_face_visibility=true)

# With BVH acceleration (experimental)
shape = load_shape_grid(xs, ys, zs; with_bvh=true)

See also: load_shape_obj, grid_to_faces

grid_to_faces(xs::AbstractVector, ys::AbstractVector, zs::AbstractMatrix) -> nodes, faces

Convert a regular grid (x, y) and corresponding z-coordinates to triangular facets.

| ⧹| ⧹| ⧹|

j+1 ・–C–D–・ |⧹ |⧹ |⧹ | | ⧹| ⧹| ⧹| j ・–A–B–・ |⧹ |⧹ |⧹ | i i+1

Arguments

• xs::AbstractVector: x-coordinates of grid points (should be sorted)
• ys::AbstractVector: y-coordinates of grid points (should be sorted)
• zs::AbstractMatrix: z-coordinates of grid points where zs[i,j] corresponds to (xs[i], ys[j])

Returns

• nodes::Vector{SVector{3,Float64}}: Array of 3D vertex positions
• faces::Vector{SVector{3,Int}}: Array of triangular face definitions (1-indexed)

Notes

Each grid cell is divided into two triangles. The vertices are numbered sequentially row by row (j varies slowest).

Examples

# Create a simple 3x3 grid
xs = [0.0, 1.0, 2.0]
ys = [0.0, 1.0, 2.0]
zs = [i + j for i in 1:3, j in 1:3]  # z = x + y
nodes, faces = grid_to_faces(xs, ys, zs)

See also: load_shape_grid