docs: Add migration guide and update documentation for v0.4.2 (#49)

* docs: Add comprehensive migration guide

- Create docs/src/guides/migration.md with version-specific migration instructions
- Document v0.4.2 performance features and how to use them
- Include v0.4.1 breaking changes (apply_eclipse_shadowing! API)
- Add v0.4.0 unified illumination API migration
- List future deprecations planned for v0.5.0
- Add migration guide to documentation navigation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* docs: Update README for v0.4.2 release

- Reorganize Key Features section for better clarity
- Separate Geometric Properties into face and shape properties
- Clarify illumination analysis shadowing models
- Add What's New in v0.4.2 section highlighting performance improvements
- Move face properties access example earlier in Quick Start
- Replace API Migration Guide section with link to comprehensive guide
- General cleanup and improved organization

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* docs: Update ROADMAP with v0.4.2 status

- Mark v0.4.2 milestone as released
- Update PR references for completed tasks
- Clean up formatting and structure
- Reflect current development status

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* docs: Update release dates to YYYY-MM-DD format

- v0.4.0: July 2025 → 2025-07-08
- v0.4.1: July 2025 → 2025-07-10
- v0.4.2: July 21, 2025 → 2025-07-21

* docs: Reorganize ROADMAP.md for v0.5.0

- Move breaking changes into API Improvements section
- Reorder sections: Major Features → API Improvements → Performance
- Simplify performance enhancement items
- Remove redundant details for cleaner structure

---------

Co-authored-by: Claude <[email protected]>

Author: MasanoriKanamaru

README.md

@@ -21,17 +21,26 @@ For future development plans, see our [Development Roadmap](ROADMAP.md).
 ## Key Features
 
 - **Shape Model Loading**: Load 3D models in OBJ file format
-- **Face Geometric Properties**: Calculate face centers, normal vectors, and areas
+- **Geometric Properties**:
+  - Face properties: Calculate face centers, normal vectors, and areas
+  - Shape properties: Compute volume, equivalent radius, and maximum/minimum radii
 - **Ray Intersection Detection**: High-precision ray-triangle intersection using the Möller–Trumbore algorithm with BVH (Bounding Volume Hierarchy) acceleration for efficient computation
   - **Batch Ray Processing**: Process multiple rays efficiently in vectors or matrices while preserving input structure
 - **Visibility Analysis**: Calculate visibility and view factors between faces
   - Optimized non-BVH algorithm with candidate filtering for face-to-face visibility
   - Distance-based sorting provides ~2x speedup over naive approaches
 - **Illumination Analysis**: Determine face illumination states with flexible shadowing models
-  - **Unified API**: Single interface with configurable self-shadowing effects
-  - **Batch Updates**: Efficient illumination state updates for all faces
-  - **Binary Asteroid Support**: Mutual shadowing and eclipse detection for binary systems
-- **Shape Characteristics**: Calculate volume, equivalent radius, maximum and minimum radii
+  - Pseudo-convex model for fast computation (only face orientation check)
+  - Self-shadowing model for accurate shading (considers occlusions from other faces)
+  - Mutual shadowing (eclipse) detection for a binary asteroid
+
+## What's New in v0.4.2
+
+- **Performance Optimization**: Face maximum elevation pre-computation provides ~2.5x speedup for illumination calculations with self-shadowing
+- **Enhanced Eclipse Detection**: More accurate total eclipse detection for non-spherical shapes
+- **Ray-Sphere Utilities**: New geometric utilities for cleaner eclipse calculations
+
+For detailed migration instructions between versions, see the [Migration Guide](https://astroshaper.github.io/AsteroidShapeModels.jl/dev/guides/migration/).
 
 ## Requirements
 
@@ -70,6 +79,11 @@ shape = load_shape_obj("path/to/shape.obj"; scale=1000, with_face_visibility=tru
 # build_face_visibility_graph!(shape)
 # build_bvh!(shape)
 
+# Access to face properties
+shape.face_centers  # Center position of each face
+shape.face_normals  # Normal vector of each face
+shape.face_areas    # Area of of each face
+
 # Single ray intersection (requires BVH to be built)
 ray = Ray(SA[1000.0, 0.0, 0.0], SA[-1.0, 0.0, 0.0])
 result = intersect_ray_shape(ray, shape)
@@ -102,38 +116,6 @@ P2S = SA[1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0]  # Rotation matrix
 # Check for eclipse shadowing
 status = apply_eclipse_shadowing!(illuminated_faces, shape1, shape2, sun_pos1, secondary_pos, P2S)
 # Returns: NO_ECLIPSE, PARTIAL_ECLIPSE, or TOTAL_ECLIPSE
-
-# Access to face properties
-shape.face_centers  # Center position of each face
-shape.face_normals  # Normal vector of each face
-shape.face_areas    # Area of of each face
-```
-
-## API Migration Guide (v0.4.1)
-
-### New `apply_eclipse_shadowing!` API
-
-The new API provides more intuitive parameter ordering for SPICE integration:
-
-```julia
-# Old API (deprecated, will be removed in v0.5.0)
-apply_eclipse_shadowing!(illuminated_faces, shape1, r☉₁, R₁₂, t₁₂, shape2)
-
-# New API (recommended)
-apply_eclipse_shadowing!(illuminated_faces, shape1, shape2, r☉₁, r₁₂, R₁₂)
-# where r₁₂ is shape2's position in shape1's frame (directly from SPICE)
-```
-
-### Parameter Naming Changes
-
-All batch illumination functions now use `illuminated_faces` instead of `illuminated`:
-
-```julia
-# Old
-update_illumination!(illuminated, shape, sun_pos; with_self_shadowing=true)
-
-# New  
-update_illumination!(illuminated_faces, shape, sun_pos; with_self_shadowing=true)
 ```
 
 ## License

ROADMAP.md

@@ -2,7 +2,11 @@
 
 This document outlines the development plans and milestones for `AsteroidShapeModels.jl`. We use [Semantic Versioning](https://semver.org/) for version numbering.
 
-## Version 0.4.0 - BVH Integration and Optimization (Released: July 2025)
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get involved.
+
+Please check our [GitHub Issues](https://github.com/Astroshaper/AsteroidShapeModels.jl/issues) for current tasks and discussions.
+
+## Version 0.4.0 - BVH Integration and Optimization (Released: 2025-07-08)
 
 ### Major Changes (Breaking Changes)
 - **Full Integration of `ImplicitBVH.jl`**
@@ -26,7 +30,7 @@ This document outlines the development plans and milestones for `AsteroidShapeMo
 - [x] Add comprehensive BVH usage documentation
 - [x] Update examples for new APIs
 
-## Version 0.4.1 - API Improvements (Released: July 2025)
+## Version 0.4.1 - API Improvements (Released: 2025-07-10)
 
 ### Completed
 - **Improved `apply_eclipse_shadowing!` API**
@@ -41,7 +45,7 @@ This document outlines the development plans and milestones for `AsteroidShapeMo
     - Now correctly recovers shape2's position using `r₁₂ = -R₁₂' * t₁₂`
   - [x] Fixed sun position transformation in eclipse shadowing (include rotation + translation)
 
-## Version 0.4.2 - Performance Optimizations (Target: August 2025)
+## Version 0.4.2 - Performance Optimizations (Released: 2025-07-21)
 
 ### Performance Features
 - **Face Maximum Elevation Precomputation**
@@ -61,9 +65,6 @@ This document outlines the development plans and milestones for `AsteroidShapeMo
 ## Version 0.5.0 - Advanced Surface Modeling (Target: September 2025)
 
 ### Major Features
-- **Breaking Changes**
-  - [ ] Remove `use_elevation_optimization` parameter from illumination APIs
-  - [ ] Make face maximum elevation optimization the default implementation
 - **Hierarchical Surface Roughness Model**
   - [ ] Support nested shape models for multi-scale surface representation
   - [ ] Implement efficient traversal algorithms for nested structures
@@ -74,27 +75,25 @@ This document outlines the development plans and milestones for `AsteroidShapeMo
   - [ ] Implement Fractal surface generation
   - [ ] Add comprehensive test coverage for roughness features
 
-- **Performance Enhancements**
-  - [ ] Add basic multi-threading support using `Threads.jl`
-  - [ ] Optimize critical paths for better single-threaded performance
-  - [ ] **Optimize `apply_eclipse_shadowing!` memory allocations**
-    - Current implementation calls `intersect_ray_shape` per face, causing ~200 allocations per call
-    - Implement true batch ray tracing with pre-allocated buffers for mutual shadowing
-    - Design `EclipseShadowingBuffer` struct to hold reusable arrays
-    - Implement filtering that preserves early-out optimizations
-    - Ensure zero allocations during runtime after initial buffer creation
-  - [ ] Add multi-threading support to `apply_eclipse_shadowing!` using `@threads`
-  - [ ] Implement spatial data structures (e.g., octree) to pre-filter potentially shadowed faces
-  - [ ] Add caching for temporal coherence in simulations with small time steps
-
 ### API Improvements
 - [ ] Remove deprecated `apply_eclipse_shadowing!` signature that uses `t₁₂` parameter
   - Old signature: `apply_eclipse_shadowing!(illuminated_faces, shape1, r☉₁, R₁₂, t₁₂, shape2)`
   - Keep only the new signature with `r₁₂` parameter introduced in v0.4.1
+- [ ] Remove `use_elevation_optimization` parameter from illumination APIs
+  - Make face maximum elevation optimization the default implementation
 - [ ] Unify parameter naming conventions across the package
 - [ ] Create configuration structs for complex operations
 - [ ] Improve error messages and validation
 
+### Performance Enhancements
+- [ ] **Optimize `apply_eclipse_shadowing!` memory allocations**
+  - Current implementation calls `intersect_ray_shape` per face, causing ~200 allocations per call
+  - Implement true batch ray tracing with pre-allocated buffers for mutual shadowing
+  - Design `EclipseShadowingBuffer` struct to hold reusable arrays
+  - Implement filtering that preserves early-out optimizations
+  - Ensure zero allocations during runtime after initial buffer creation
+- [ ] Add basic multi-threading support using `Threads.jl`
+
 ## Version 0.6.0 - High-Performance Computing Support (Target: October 2025)
 
 ### Major Features
@@ -121,16 +120,3 @@ This document outlines the development plans and milestones for `AsteroidShapeMo
 
 - **Extended File Format Support**
   - PLY/STL/VTK/DSK format support
-
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get involved.
-
-## Tracking Progress
-
-Development progress is tracked through:
-- GitHub Milestones for each version
-- GitHub Issues for specific features and bugs
-- Pull Requests for implementation
-
-Please check our [GitHub Issues](https://github.com/Astroshaper/AsteroidShapeModels.jl/issues) for current tasks and discussions.

docs/make.jl

@@ -17,6 +17,7 @@ makedocs(;
         "Tutorial" => "tutorial.md",
         "Guides" => [
             "BVH Usage" => "guides/bvh_usage.md",
+            "Migration Guide" => "guides/migration.md",
         ],
         "API Reference" => [
             "Types" => "api/types.md",

docs/src/guides/migration.md

@@ -0,0 +1,103 @@
+# Migration Guide
+
+This guide helps you migrate your code when upgrading between major versions of `AsteroidShapeModels.jl`.
+
+## Migrating to v0.4.2
+
+### New Performance Features
+
+#### Face Maximum Elevation Optimization
+
+The v0.4.2 release includes automatic performance optimizations for illumination calculations. No code changes are required to benefit from these improvements.
+
+```julia
+# Your existing code works as before, but ~2.5x faster!
+illuminated = isilluminated(shape, sun_position, face_idx; with_self_shadowing=true)
+```
+
+To disable the optimization (not recommended):
+```julia
+# Explicitly disable optimization
+illuminated = isilluminated(
+   shape, sun_position, face_idx; 
+   with_self_shadowing=true, 
+   use_elevation_optimization=false,
+)
+```
+
+## Migrating to v0.4.1
+
+### Breaking Changes
+
+#### New `apply_eclipse_shadowing!` API
+
+The parameter order has been changed for better SPICE integration:
+
+```julia
+# Old API (deprecated)
+apply_eclipse_shadowing!(illuminated_faces, shape1, r☉₁, R₁₂, t₁₂, shape2)
+
+# New API (recommended)
+apply_eclipse_shadowing!(illuminated_faces, shape1, shape2, r☉₁, r₁₂, R₁₂)
+```
+
+Key differences:
+- `shape1` and `shape2` are now grouped together
+- `r₁₂` (shape2's position in shape1's frame) replaces `t₁₂`
+- More intuitive parameter ordering
+
+Migration example:
+```julia
+# If you have t₁₂, convert it to r₁₂:
+r₁₂ = -R₁₂' * t₁₂
+
+# Then use the new API:
+apply_eclipse_shadowing!(illuminated, shape1, shape2, sun_position, r₁₂, R₁₂)
+```
+
+## Migrating to v0.4.0
+
+### New Unified Illumination API
+
+The illumination functions have been unified into a single API:
+
+```julia
+# Old APIs (removed)
+isilluminated_pseudoconvex(shape, sun_position, face_idx)
+isilluminated_with_self_shadowing(shape, sun_position, face_idx)
+
+# New unified API
+isilluminated(shape, sun_position, face_idx; with_self_shadowing=false)  # pseudo-convex
+isilluminated(shape, sun_position, face_idx; with_self_shadowing=true)   # with shadowing
+```
+
+### Batch Processing
+
+New batch processing functions for better performance:
+
+```julia
+# Process all faces at once
+illuminated = Vector{Bool}(undef, length(shape.faces))
+update_illumination!(illuminated, shape, sun_position; with_self_shadowing=true)
+```
+
+## Future Deprecations (v0.5.0)
+
+### Planned Removals
+
+1. **`use_elevation_optimization` parameter**
+   - Will be removed in v0.5.0
+   - Optimization will become the default behavior
+   - Start removing explicit `use_elevation_optimization=true` from your code
+
+2. **Old `apply_eclipse_shadowing!` signature**
+   - The deprecated signature with `t₁₂` will be removed
+   - Migrate to the new API with `r₁₂` parameter
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. Check the [CHANGELOG](https://github.com/Astroshaper/AsteroidShapeModels.jl/blob/main/CHANGELOG.md) for detailed changes
+2. Review the [API documentation](https://astroshaper.github.io/AsteroidShapeModels.jl/stable)
+3. Open an [issue](https://github.com/Astroshaper/AsteroidShapeModels.jl/issues) on GitHub