Astroshaper · MasanoriKanamaru · Jul 23, 2025 · Jul 24, 2025 · Jul 24, 2025 · Jul 24, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,8 +5,28 @@ All notable changes to `AsteroidShapeModels.jl` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+---
+
 ## [Unreleased]
 
+### Added
+- **Hierarchical shape models for multi-scale surface representation** (PR TBD)
+  - New `HierarchicalShapeModel` type that supports adding surface roughness to a base shape model
+  - Roughness model management functions:
+    - `has_roughness_model` - Check if a face has associated roughness
+    - `get_roughness_model` - Retrieve roughness model for a face
+    - `get_roughness_model_scale` - Get scale factor for roughness model
+    - `get_roughness_model_transform` - Get affine transformation for roughness model
+    - `add_roughness_models!` - Add roughness models to faces (supports both all-faces and specific-face variants)
+    - `clear_roughness_models!` - Remove roughness models from faces (supports both all-faces and specific-face variants)
+  - Coordinate transformation functions:
+    - `transform_point_global_to_local` / `transform_point_local_to_global` - Transform points between coordinate systems (full affine transformation)
+    - `transform_geometric_vector_global_to_local` / `transform_geometric_vector_local_to_global` - Transform geometric vectors (with scaling)
+    - `transform_physical_vector_global_to_local` / `transform_physical_vector_local_to_global` - Transform physical vectors (rotation only)
+  - Memory-efficient design allowing multiple faces to share the same roughness model
+  - Automatic north-aligned local coordinate system for each face
+  - Support for custom affine transformations per face
+
 ### Breaking Changes
 - **Removed deprecated `apply_eclipse_shadowing!` signature** (#51)
   - Removed the old function signature that used `t₁₂` parameter: `apply_eclipse_shadowing!(illuminated_faces, shape1, r☉₁, R₁₂, t₁₂, shape2)`
@@ -19,7 +39,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Affected functions: `isilluminated`, `update_illumination!`
   - This simplifies the API and ensures users always get the best performance
 
-## [0.4.2] - 2025-01-21
+---
+
+## [0.4.2] - 2025-07-21
 
 ### Added
 - **Face maximum elevation optimization for faster illumination calculations** (#46)
@@ -48,6 +70,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Better separation of concerns between geometric calculations and eclipse logic
   - Performance is identical but code is more maintainable
 
+---
+
 ## [0.4.1] - 2025-07-10
 
 ### Added
@@ -75,7 +99,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Previously only applied rotation, which could lead to incorrect shadow calculations
   - Ensures accurate eclipse detection in binary asteroid systems
 
-## [0.4.0] - 2025-07-07
+---
+
+## [0.4.0] - 2025-07-08
 
 ### Breaking Changes
 - **BVH must be pre-built for ray intersection** (04d2937, 5355dbc)
@@ -152,6 +178,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated file-level documentation in `visibility.jl` with new exported functions
 - Updated package structure documentation to reflect new file organization
 
+---
+
 ## [0.3.1] - 2025-07-02
 
 ### Added
@@ -181,6 +209,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - BVH support is opt-in and does not affect existing code
 - Current BVH visibility implementation has room for future optimization
 
+---
+
 ## [0.3.0] - 2025-06-20
 
 ### Breaking Changes
@@ -261,6 +291,8 @@ The new CSR-based implementation provides:
 - ~50% memory reduction across all model sizes
 - Better cache locality for sequential access patterns
 
+---
+
 ## [0.2.1] - 2025-06-17
 
 ### Added
@@ -278,6 +310,8 @@ The new CSR-based implementation provides:
 - Legacy adjacency list implementation will be removed in v0.3.0
 - `shape.visiblefacets` field will be removed in v0.3.0 (use `shape.visibility_graph`)
 
+---
+
 ## [0.2.0] - 2025-06-14
 
 ### Breaking Changes
@@ -313,6 +347,8 @@ The new CSR-based implementation provides:
 - Updated installation instructions for Julia General registry
 - Added Julia REPL package mode installation method
 
+---
+
 ## [0.1.0] - Initial Release
 
 ### Added

diff --git a/Project.toml b/Project.toml
@@ -4,6 +4,7 @@ authors = ["Masanori Kanamaru <kanamaru-masanori@hotmail.co.jp>"]
 version = "0.4.2"
 
 [deps]
+CoordinateTransformations = "150eb455-5306-5404-9cee-2592286d6298"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
 GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
 ImplicitBVH = "932a18dc-bb55-4cd5-bdd6-1368ec9cea29"
@@ -13,6 +14,7 @@ StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 
 [compat]
 BenchmarkTools = "1.6.0"
+CoordinateTransformations = "0.6"
 FileIO = "1"
 GeometryBasics = "0.5"
 ImplicitBVH = "0.6.0"

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -6,6 +6,8 @@ We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.
 
 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)
@@ -30,6 +32,8 @@ Please check our [GitHub Issues](https://github.com/Astroshaper/AsteroidShapeMod
 - [x] Add comprehensive BVH usage documentation
 - [x] Update examples for new APIs
 
+---
+
 ## Version 0.4.1 - API Improvements (Released: 2025-07-10)
 
 ### Completed
@@ -45,6 +49,8 @@ Please check our [GitHub Issues](https://github.com/Astroshaper/AsteroidShapeMod
     - 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 (Released: 2025-07-21)
 
 ### Performance Features
@@ -62,12 +68,13 @@ Please check our [GitHub Issues](https://github.com/Astroshaper/AsteroidShapeMod
   - [x] Extract ray-sphere intersection tests into dedicated reusable functions (#45)
   - [x] Ensure consistency in results with previous implementation (#45)
 
-## Version 0.5.0 - Advanced Surface Modeling (Target: September 2025)
+---
+
+## Version 0.5.0 - Surface Roughness Modeling (Target: September 2025)
 
 ### Major Features
-- **Hierarchical Surface Roughness Model**
-  - [ ] Support nested shape models for multi-scale surface representation
-  - [ ] Implement efficient traversal algorithms for nested structures
+- **Hierarchical Shape Model**
+  - [ ] Support nested shape models for surface roughness representation
 
 - **Complete Roughness Module**
   - [ ] Implement parallel sinusoidal trench generation
@@ -94,6 +101,8 @@ Please check our [GitHub Issues](https://github.com/Astroshaper/AsteroidShapeMod
   - 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
@@ -113,6 +122,8 @@ Please check our [GitHub Issues](https://github.com/Astroshaper/AsteroidShapeMod
 - [ ] Memory-efficient algorithms for resource-constrained environments
 - [ ] Streaming processing for models that don't fit in memory
 
+---
+
 ## Future Considerations (Beyond v0.6.0)
 
 - **Machine Learning Integration**

diff --git a/docs/src/api/roughness.md b/docs/src/api/roughness.md
@@ -4,6 +4,30 @@
 CurrentModule = AsteroidShapeModels
 ```
 
+## Hierarchical Shape Models
+
+### Roughness Model Management
+
+```@docs
+has_roughness_model
+get_roughness_model
+get_roughness_model_scale
+get_roughness_model_transform
+add_roughness_models!
+clear_roughness_models!
+```
+
+### Coordinate Transformations
+
+```@docs
+transform_point_global_to_local
+transform_point_local_to_global
+transform_geometric_vector_global_to_local
+transform_geometric_vector_local_to_global
+transform_physical_vector_global_to_local
+transform_physical_vector_local_to_global
+```
+
 ## Crater Modeling
 
 ```@docs

diff --git a/docs/src/api/types.md b/docs/src/api/types.md
@@ -7,7 +7,9 @@ CurrentModule = AsteroidShapeModels
 ## Core Types
 
 ```@docs
+AbstractShapeModel
 ShapeModel
+HierarchicalShapeModel
 Ray
 Sphere
 ```

diff --git a/docs/src/guides/migration.md b/docs/src/guides/migration.md
@@ -16,6 +16,32 @@ No planned deprecations at this time.
 
 ## Migrating to v0.5.0 (Unreleased)
 
+### New Features
+
+#### Hierarchical Shape Models
+
+v0.5.0 introduces `HierarchicalShapeModel` for multi-scale surface representation:
+
+```julia
+# Create hierarchical model from global shape
+hier_shape = HierarchicalShapeModel(global_shape)
+
+# Add roughness models to specific faces
+roughness = load_shape_obj("roughness.obj", scale=10)
+add_roughness_models!(hier_shape, roughness, face_idx; scale=0.01)
+
+# Transform between global and local coordinates
+p_local = transform_point_global_to_local(hier_shape, face_idx, p_global)
+v_local = transform_geometric_vector_global_to_local(hier_shape, face_idx, v_global)
+f_local = transform_physical_vector_global_to_local(hier_shape, face_idx, f_global)
+```
+
+Key features:
+- Add surface roughness models to individual faces
+- Automatic coordinate transformations between global and local frames
+- Separate handling of geometric vectors (with scaling) and physical vectors (rotation only)
+- Memory-efficient sharing of roughness models across multiple faces
+
 ### Breaking Changes
 
 #### Removed `apply_eclipse_shadowing!` deprecated signature

diff --git a/src/AsteroidShapeModels.jl b/src/AsteroidShapeModels.jl
@@ -8,7 +8,9 @@ including loading from OBJ files, computing geometric properties, ray-shape inte
 visibility analysis, and surface roughness modeling.
 
 # Main Types
+- `AbstractShapeModel`: Abstract base type for all shape models
 - `ShapeModel`: Core data structure for polyhedral shapes
+- `HierarchicalShapeModel`: Multi-scale shape model with surface roughness
 - `Ray`: Ray for ray casting operations
 - `FaceVisibilityGraph`: CSR-style data structure for face-to-face visibility
 
@@ -36,6 +38,7 @@ See the documentation for detailed usage examples and API reference.
 """
 module AsteroidShapeModels
 
+using CoordinateTransformations
 using FileIO
 using LinearAlgebra
 using StaticArrays
@@ -52,7 +55,15 @@ export Ray, Sphere
 export RayTriangleIntersectionResult, RayShapeIntersectionResult, RaySphereIntersectionResult
 
 include("shape_model.jl")
-export ShapeModel, build_bvh!
+export AbstractShapeModel, ShapeModel, build_bvh!
+
+include("hierarchical_shape_model.jl")
+export HierarchicalShapeModel
+export has_roughness_model, get_roughness_model, get_roughness_model_scale, get_roughness_model_transform
+export clear_roughness_models!, add_roughness_models!
+export transform_point_global_to_local, transform_point_local_to_global
+export transform_geometric_vector_global_to_local, transform_geometric_vector_local_to_global
+export transform_physical_vector_global_to_local, transform_physical_vector_local_to_global
 
 include("face_visibility_graph.jl")
 export FaceVisibilityGraph, build_face_visibility_graph!, view_factor