v0.4.2

Illumination Performance Optimizations

What's Changed

Performance Features

• Face Maximum Elevation Optimization: ~2.5-2.7x speedup for illumination calculations with self-shadowing (#46)
  • Automatically computed when with_face_visibility=true
  • Skips ray tracing for faces that cannot cast shadows based on pre-computed elevation angles
  • Results match exactly with the original implementation

Enhancements

• Improved Eclipse Detection: More accurate total eclipse detection for non-spherical shapes (#45)
• New Ray-Sphere Utilities: Added intersect_ray_sphere function and related types for cleaner geometric calculations (#45)

Documentation

• Added comprehensive Migration Guide
• New benchmark results documenting performance improvements
• Updated README with "What's New" section

Benchmark Results

For Ryugu 49k model with 72 sun positions (5° rotation steps):

• Pseudo-convex: 7.2 ms
• Self-shadowing (without optimization): 1.08 s
• Self-shadowing (with optimization): 399.1 ms (~2.7x faster)

Optimization effectiveness: 10.7% of ray tracing computations skipped

Migration

No breaking changes. Your existing code will automatically benefit from the performance improvements. See the Migration Guide for details.

Full Changelog: v0.4.1...v0.4.2

v0.4.1

Bug-fix and API Improvements in Eclipse Shadowing

This release includes important bug fixes and API improvements for eclipse shadowing in binary asteroid systems.

🚀 Features

New apply_eclipse_shadowing! API (#43)

• New signature with improved parameter ordering: apply_eclipse_shadowing!(illuminated_faces, shape1, shape2, r☉₁, r₁₂, R₁₂)
• Directly accepts r₁₂ (shape2's position in shape1's frame) for better SPICE integration
• More intuitive parameter ordering with shapes grouped together
• The old signature using t₁₂ is deprecated and will be removed in v0.5.0

🐛 Bug Fixes

Critical coordinate transformation bug (#42)

• Fixed incorrect interpretation of translation vector t₁₂ as position vector
• This caused false TOTAL_ECLIPSE detections when shape2 was actually behind shape1
• Now correctly recovers shape2's position using r₁₂ = -R₁₂' * t₁₂

Sun position transformation

• Fixed sun position transformation in eclipse shadowing to include both rotation and translation
• Previously only applied rotation, leading to incorrect shadow calculations

🔧 Improvements

Parameter naming consistency

• Renamed illuminated parameter to illuminated_faces across all batch processing functions
• Improves API consistency and clarity

📋 Migration Guide

# Old API (deprecated)
apply_eclipse_shadowing!(illuminated, shape1, r☉₁, R₁₂, t₁₂, shape2)

# New API (recommended)
apply_eclipse_shadowing!(illuminated_faces, shape1, shape2, r☉₁, r₁₂, R₁₂)
# where r₁₂ = -R₁₂' * t₁₂

---

Full Changelog: v0.4.0...v0.4.1

v0.4.0

AsteroidShapeModels.jl v0.4.0

Major release with significant performance improvements and API changes.

🎯 Highlights

• BVH Integration: ~50x faster ray-shape intersection using Bounding Volume Hierarchy
• Improved Illumination API: Explicit control over shadowing models with keyword arguments
• Enhanced Documentation: Comprehensive docstrings with examples for all major functions

🚨 Breaking Changes

BVH Requirement for Ray Intersection

BVH is now required for intersect_ray_shape functions. Build it explicitly:

shape = load_shape_obj("shape.obj"; with_bvh=true)
# or
build_bvh!(shape)

New Illumination API

Illumination functions now use keyword arguments:

# Old (removed)
isilluminated_pseudo_convex(shape, sun_pos, face_idx)
isilluminated_with_self_shadowing(shape, sun_pos, face_idx)

# New
isilluminated(shape, sun_pos, face_idx; with_self_shadowing=false)
isilluminated(shape, sun_pos, face_idx; with_self_shadowing=true)

Other Changes

• Removed automatic BVH building from ray intersection methods
• Type system improvements for better performance

✨ New Features

• Unified illumination API with isilluminated and update_illumination!
• Enhanced data access API for FaceVisibilityGraph

📚 Documentation

• Added detailed examples in README and main documentation
• Improved docstrings with performance notes and cross-references
• Added !!! note sections for BVH requirements

🔧 Internal Improvements

• Split visibility.jl into focused modules (PR #37)
• Better code organization and maintainability
• Enhanced test coverage

📦 Installation

using Pkg
Pkg.add("AsteroidShapeModels")

For full details, see the CHANGELOG.

v0.3.1 - BVH Acceleration Support

New Features

• BVH (Bounding Volume Hierarchy) acceleration for ray tracing (~50x speedup)
• BVH support in intersect_ray_shape, isilluminated, and build_face_visibility_graph!
• Optional BVH loading via with_bvh parameter
• New build_bvh! function to add BVH to existing shapes

Improvements

• Optimized non-BVH visibility calculations (~2x speedup)
  • Distance-based candidate sorting
  • Pre-computed distance reuse
  • Optimized object creation

Documentation

• Updated README with BVH usage examples
• Added BVH feature descriptions to documentation
• Updated CHANGELOG with v0.3.1 release notes

Installation

using Pkg
Pkg.add("AsteroidShapeModels")

Quick Start with BVH

using AsteroidShapeModels

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

# Or build BVH for existing shape
build_bvh!(shape)

Notes

• ✅ Backward compatible - no breaking changes
• 📦 BVH support is optional via ImplicitBVH.jl
• 🚀 Current BVH visibility implementation has room for future optimization

Full Changelog: v0.3.0...v0.3.1

v0.3.0

AsteroidShapeModels.jl v0.3.0

This release includes significant API improvements and breaking changes designed to make the library more intuitive and maintainable.

🚨 Breaking Changes

Removed Legacy Visibility API (#15)

• Removed visiblefacets field from ShapeModel
• Removed use_visibility_graph parameter (CSR format is now the only implementation)
• Removed from_adjacency_list and to_adjacency_list conversion functions

API Renaming for Clarity (#15, #17)

• find_visiblefacets! → build_face_visibility_graph!
• ShapeModel.visibility_graph → ShapeModel.face_visibility_graph
• find_visible_facets parameter → with_face_visibility
• Visibility graph accessor functions:
  • get_visible_faces → get_visible_face_indices
  • get_distances → get_visible_face_distances
  • get_directions → get_visible_face_directions
  • get_visible_facet_data → get_visible_face_data
• VisibleFacet → VisibleFace (internal type, removed from exports)

Function Naming Convention Updates (#18)

• loadobj → load_obj (follows Julia snake_case convention)
• Removed message parameter from load_obj function

📋 Migration Guide

Please see the detailed migration guide in CHANGELOG.md for code examples.

🚀 Performance Improvements

The CSR-based implementation provides:

• ~4x faster computation for small models (< 10k faces)
• ~50% memory reduction across all model sizes
• Better cache locality for sequential access patterns

📚 Documentation Improvements (#16)

• Added comprehensive file-level documentation
• Added section separators for better code organization
• Improved consistency in terminology

🔧 Other Changes

• Fixed face orientations in test shapes for correct visibility calculations
• Removed redundant inner constructor from ShapeModel
• Used keyword argument shorthand syntax where applicable

📦 Installation

] add AsteroidShapeModels@0.3

v0.2.1

AsteroidShapeModels.jl v0.2.1 Release Notes

🚀 Performance Improvements

This release introduces FaceVisibilityGraph, a new CSR (Compressed Sparse Row) data structure that significantly improves performance and memory efficiency for face-to-face visibility calculations.

Key Performance Metrics

• Small Models (< 10k faces):

  • 🏃 ~4x faster visibility computation (391ms → 98ms for 5,932 face model)
  • 💾 50% memory reduction (11.7MB → 5.9MB)

• Large Models (49k faces):

  • 💾 50% memory reduction (562MB → 281MB)
  • 🎯 Better cache locality for sequential access patterns
  • ⚡ Consistent performance for high-resolution thermal physics simulations

✨ New Features

• FaceVisibilityGraph: New efficient data structure using CSR format
  • Provides O(1) access to visible faces, view factors, distances, and directions
  • Optimized for both small asteroid models and high-resolution shape data
  • Full backward compatibility with existing code
• Enhanced find_visiblefacets! function:

# Use new implementation (default)
find_visiblefacets!(shape, use_visibility_graph=true)

# Use legacy implementation if needed
find_visiblefacets!(shape, use_visibility_graph=false)

• Comprehensive benchmarking suite:
  • Performance comparison tools for visibility algorithms
  • Support for high-resolution models (49k faces) used in thermal modeling
  • Memory usage analysis with Base.summarysize

📦 Other Improvements

• Added Manifest.toml files for reproducible builds (#11)
• Improved documentation for visibility analysis
• Enhanced test coverage for new data structures

⚠️ Deprecation Notice

The following features are deprecated and will be removed in v0.3.0:

• Legacy adjacency list implementation
• Direct access to shape.visiblefacets field (use shape.visibility_graph instead)

🔄 Migration Guide

No code changes required! The new implementation is fully backward compatible. To prepare for v0.3.0:

1. Test with new implementation: Set use_visibility_graph=true (already default)
2. Update direct field access: Replace shape.visiblefacets with appropriate accessor functions
3. Report any issues: Please open an issue if you encounter any problems

📊 Benchmark Results

Detailed benchmarks available in the repository show consistent improvements across all model sizes, with particularly impressive gains for smaller models commonly used in mission planning and larger models used in thermal physics simulations.

---

Full Changelog:
v0.2.0...v0.2.1

v0.2.0

Breaking Changes

• Removed raycast function - Use intersect_ray_triangle instead (#4)
  • The raycast function that returned only a boolean hit/miss result has been removed
  • All ray-triangle intersection operations now use intersect_ray_triangle which provides detailed intersection information
  • See CHANGELOG.md for migration guide

New Features

• ShapeModel constructor that automatically computes face properties (#2)
  • Reduces code duplication when creating shape models
  • Optionally computes face-to-face visibility with find_visible_facets=true

Improvements

• Improved performance and readability across the codebase (#3)
  • Optimized face property calculations
  • Enhanced code clarity and maintainability

Documentation

• Fixed CI badge URL in README (#7)
• Added comprehensive CHANGELOG.md (#8)
• Added PkgEval badge to README (#6)
• Updated installation instructions for Julia General registry (#6)
• Added Julia REPL package mode installation method (#6)

Migration Guide

For users upgrading from v0.1.0:

# Old code using raycast
if raycast(A, B, C, ray_direction, ray_origin)
    # handle intersection
end

# New code using intersect_ray_triangle
ray = Ray(ray_origin, ray_direction)
if intersect_ray_triangle(ray, A, B, C).hit
    # handle intersection
end

Installation

The package is now registered in the Julia General registry:

using Pkg
Pkg.add("AsteroidShapeModels")

Full Changelog

See CHANGELOG.md for complete details.

v0.1.0

Initial release of AsteroidShapeModels.jl.

Features:

• Shape model loading from OBJ files
• Geometric computations (face properties, volume)
• Ray-shape intersection
• Face-to-face visibility analysis
• Surface roughness modeling