Surface Roughness

has_roughness_model(hier_shape::HierarchicalShapeModel, face_idx::Int) -> Bool

Check if a face has an associated roughness model.

Arguments

• hier_shape::HierarchicalShapeModel : The hierarchical shape model
• face_idx::Int : Index of the face to check

Returns

• Bool : true if the face has an associated roughness model, false otherwise

get_roughness_model(hier_shape::HierarchicalShapeModel, face_idx::Int) -> Union{Nothing, ShapeModel}

Get the roughness model associated with a specific face.

Arguments

• hier_shape::HierarchicalShapeModel : The hierarchical shape model
• face_idx::Int : Index of the face to query

Returns

• Union{Nothing, ShapeModel} : The roughness model for the specified face, or nothing if no roughness model is associated

get_roughness_model_scale(hier_shape::HierarchicalShapeModel, face_idx::Int) -> Float64

Get the scale factor for the roughness model on a specific face.

Arguments

• hier_shape::HierarchicalShapeModel : The hierarchical shape model
• face_idx::Int : Index of the face to query

Returns

• Float64 : The scale factor for the roughness model (1.0 if no roughness model)

get_roughness_model_transform(hier_shape::HierarchicalShapeModel, face_idx::Int) -> AffineMap

Get the affine transformation (global to local) for the roughness model on a specific face.

Arguments

• hier_shape::HierarchicalShapeModel : The hierarchical shape model
• face_idx::Int : Index of the face to query

Returns

• AFFINE_MAP_TYPE : The affine transformation from global to local coordinates

add_roughness_models!(
    hier_shape      ::HierarchicalShapeModel,
    roughness_model ::ShapeModel;
    scale           ::Float64 = 1.0,
)

Add the same surface roughness model to all faces of the hierarchical shape model.

Arguments

• hier_shape::HierarchicalShapeModel : The hierarchical shape model
• roughness_model::ShapeModel : The shape model representing the surface roughness

Keyword Arguments

• scale::Float64 : Scale factor for the roughness model (default: 1.0)

Notes

• This function applies the roughness model to ALL faces, overwriting any existing assignments.
• All faces will share the same ShapeModel instance, making this memory-efficient.
• Appropriate transformations are automatically computed for each face using compute_face_roughness_transform.
• Use the face-specific version add_roughness_models!(hier_shape, roughness_model, face_idx; scale, transform) to selectively apply different models to individual faces or to provide custom transformations.

add_roughness_models!(
    hier_shape      ::HierarchicalShapeModel,
    roughness_model ::ShapeModel,
    face_idx        ::Int;
    scale           ::Float64 = 1.0,
    transform       ::Union{Nothing, AFFINE_MAP_TYPE} = nothing,
)

Add a surface roughness model to a specific face of the hierarchical shape model.

Arguments

• hier_shape::HierarchicalShapeModel : The hierarchical shape model
• roughness_model::ShapeModel : The shape model representing the surface roughness
• face_idx::Int : Index of the face to attach the roughness to

Keyword Arguments

• scale::Float64 : Scale factor for the roughness model (default: 1.0)
• transform::Union{Nothing, AFFINE_MAP_TYPE} : Affine transformation from global to local coordinates (optional). If nothing (default), automatically computes an appropriate transformation using compute_face_roughness_transform

Notes

• If the face already has a roughness model, it will be replaced.
• When transform is nothing, the roughness model is automatically positioned at the face center with a north-aligned local coordinate system (x: East, y: North, z: Up).

clear_roughness_models!(hier_shape::HierarchicalShapeModel)

Remove all roughness models from all faces of the hierarchical shape model.

Arguments

• hier_shape::HierarchicalShapeModel : The hierarchical shape model

Notes

This function clears all roughness model assignments but keeps the model's structure intact. The roughness_models array is emptied to free memory.

clear_roughness_models!(hier_shape::HierarchicalShapeModel, face_idx::Int)

Remove the roughness model from a specific face.

Arguments

• hier_shape::HierarchicalShapeModel : The hierarchical shape model
• face_idx::Int : Index of the face to clear

Notes

This function clears the assignment for the specified face. If the roughness model is no longer used by any face, it will be removed from memory.

crater_curvature_radius(r, h) -> R

Calculate the curvature radius of a concave spherical segment.

Arguments

• r::Real: Crater radius (same units as h)
• h::Real: Crater depth (same units as r)

Returns

• R::Real: Curvature radius of the spherical segment

Notes

The curvature radius is calculated using the formula: R = (r² + h²) / 2h This represents the radius of the sphere from which the crater segment is cut.

Example

# Small bowl-shaped crater: 100m radius, 10m deep
R = crater_curvature_radius(100.0, 10.0)  # Returns 505.0 m

# Deeper crater (smaller curvature radius): 100m radius, 50m deep
R = crater_curvature_radius(100.0, 50.0)  # Returns 125.0 m

See also: concave_spherical_segment

concave_spherical_segment(r, h, xc, yc, x, y) -> z

Calculate the z-coordinate (depth) of a concave spherical segment at a given (x,y) position.

Arguments

• r::Real : Crater radius
• h::Real : Crater depth (maximum depth at center)
• xc::Real : x-coordinate of crater center
• yc::Real : y-coordinate of crater center
• x::Real : x-coordinate where to calculate z
• y::Real : y-coordinate where to calculate z

Returns

• z::Real: Depth below the surface (negative value inside, 0 outside crater)

Notes

• Returns 0 for points outside the crater radius
• The crater profile follows a spherical cap geometry
• All spatial parameters should use consistent units

Example

# Crater at origin with 10m radius and 2m depth
z_center = concave_spherical_segment(10.0, 2.0, 0.0, 0.0, 0.0, 0.0)   # Returns -2.0
z_edge   = concave_spherical_segment(10.0, 2.0, 0.0, 0.0, 10.0, 0.0)  # Returns 0.0
z_mid    = concave_spherical_segment(10.0, 2.0, 0.0, 0.0, 5.0, 0.0)   # Returns ~-0.6

See also: crater_curvature_radius

concave_spherical_segment(r, h; Nx=2^5, Ny=2^5, xc=0.5, yc=0.5) -> xs, ys, zs

Generate a grid representation of a concave spherical segment (crater).

Arguments

• r::Real : Crater radius (in normalized units, typically 0-1)
• h::Real : Crater depth (in same units as radius)

Keyword Arguments

• Nx::Integer=32 : Number of grid points in x-direction (default: 2^5)
• Ny::Integer=32 : Number of grid points in y-direction (default: 2^5)
• xc::Real=0.5 : x-coordinate of crater center (normalized, 0-1)
• yc::Real=0.5 : y-coordinate of crater center (normalized, 0-1)

Returns

• xs::LinRange: x-coordinates of grid points (0 to 1)
• ys::LinRange: y-coordinates of grid points (0 to 1)
• zs::Matrix : z-coordinates (depths) at each grid point

Notes

• The grid spans a unit square [0,1] × [0,1]
• z-values are negative inside the crater, 0 outside
• Suitable for use with load_shape_grid to create crater shape models

Example

# Generate a crater covering 40% of the domain, 0.1 units deep
xs, ys, zs = concave_spherical_segment(0.4, 0.1; Nx=64, Ny=64)

# Convert to shape model
shape = load_shape_grid(xs, ys, zs)

# Off-center crater
xs, ys, zs = concave_spherical_segment(0.3, 0.05; xc=0.3, yc=0.7)

See also: load_shape_grid, grid_to_faces