A professional-grade Flutter application designed to help researchers, professionals, and developers in geology, gaming, and medical fields compare and analyze 3D objects with advanced Procrustes analysis. Built with clean architecture principles and supporting all major platforms.
🍎 Recommended Platform: macOS - For optimal performance and full 3D rendering support with native point cloud visualization
📋 Project Progress: See PROJECT_STATUS.md for complete TODO list, recent updates, and development roadmap.
Watch a short walkthrough of the app in action:
- Fossil Analysis: Compare fossil specimens to identify species and evolutionary relationships
- Rock Formation Studies: Analyze geological structures and mineral formations
- Paleontology Research: Compare bone structures and skeletal remains
- Geological Mapping: Overlay and compare terrain models and geological features
- Character Modeling: Compare 3D character models for consistency and quality control
- Asset Validation: Ensure 3D assets meet design specifications
- Animation Rigging: Compare skeletal structures for animation compatibility
- Level Design: Analyze and compare 3D environments and architectural elements
- Anatomical Studies: Compare anatomical structures for research and education
- Prosthetic Design: Analyze and compare prosthetic components for optimal fit
- Surgical Planning: Compare pre and post-operative 3D scans
- Medical Imaging: Analyze CT scans, MRI data, and other 3D medical images
- Dental Applications: Compare dental models and orthodontic treatments
- 3D Object Loading: Support for GLB/GLTF (full 3D rendering), OBJ/STL (data analysis)
- Interactive 3D Visualization: Real-time rendering with camera controls for GLB/GLTF files
- Procrustes Analysis: Advanced statistical alignment and comparison using proven mathematical algorithms
- Similarity Metrics: Comprehensive analysis with RMSE, standard deviation, and similarity scores
- Export Results: JSON and CSV export capabilities for integration with research workflows
- Superimposed Viewing: Overlay multiple objects with adjustable opacity for visual comparison
- Side-by-Side Comparison: View two 3D objects simultaneously with independent controls
- Alignment Score Gauge: Real-time visual feedback on how well objects are aligned (0-100%)
- Procrustes Analysis: One-click statistical alignment with progress tracking
- Auto-Align: Instantly position Object B to match Object A's transforms
- Reset Controls: Return objects to default positions
- Similarity Metrics Card: Detailed breakdown of RMSE, standard deviation, and alignment quality
- Transform History: Undo/redo capability for all transformations
- Export Analysis: Save comparison results as TXT files
- Statistical Alignment: Automatically align objects using Procrustes transformation
- Quantitative Metrics: Precise measurements of shape differences and similarities
- Visual Comparison: Side-by-side and overlaid viewing modes
- Data Export: Export analysis results for further statistical processing
The project follows clean architecture principles with clear separation of concerns:
lib/
├── core/ # Core functionality
│ ├── constants/ # App constants
│ ├── database/ # Database setup
│ ├── di/ # Dependency injection
│ ├── errors/ # Error handling
│ └── utils/ # Utility functions
├── features/ # Feature modules
│ ├── home/ # Home screen
│ ├── model_viewer/ # 3D model viewing
│ └── user_preferences/ # User settings
└── shared/ # Shared components
├── utils/ # Shared utilities
└── widgets/ # Reusable widgets
Each feature follows the clean architecture pattern:
- Presentation Layer: UI components, pages, and providers
- Domain Layer: Entities, repositories, and use cases
- Data Layer: Data sources, models, and repository implementations
Try the app online: https://aminmemariani.github.io/3d_object_compare
Note: If you see a 404 error, the deployment is in progress. Please wait 2-3 minutes for GitHub Actions to complete the build and deployment.
The web version is automatically deployed to GitHub Pages and includes all core features for 3D object comparison and analysis.
The app is automatically deployed to GitHub Pages using GitHub Actions. To deploy manually:
# Using the deployment script
./scripts/deploy_web.sh
# Or manually
flutter build web --releaseFor detailed deployment instructions, see docs/README.md.
For the best scientific analysis experience:
# 1. Clone the repository
git clone https://github.com/AminMemariani/3d_object_compare.git
cd 3d_object_compare
# 2. Install dependencies
flutter pub get
# 3. Run on macOS
flutter run -d macos
# 4. Load your 3D models (OBJ, STL, GLTF, GLB)
# 5. Run Procrustes Analysis
# 6. Export complete results with logs- Flutter SDK 3.32.6 or later
- Dart SDK 3.8.1 or later
- Clone the repository:
git clone https://github.com/AminMemariani/3d_object_compare.git
cd 3d_object_compare- Install dependencies:
flutter pub get- Generate Isar database code:
flutter packages pub run build_runner build --delete-conflicting-outputs- Run the application:
flutter run- Load 3D Objects: Click "Load Object A" and "Load Object B" to select 3D files
- Supported formats: OBJ, STL, GLB, GLTF
- On macOS 🍎: All formats render natively with interactive 3D point clouds
- On iOS/Android: Full textured rendering with ModelViewer
- On Web: Point cloud rendering (requires hosted files for textures)
- Navigate to Comparison View: Automatically opens after loading both objects
- View Scientific Metrics: Min Distance and Standard Deviation displayed after analysis
- Transform Objects: Use on-screen controls to manually adjust position/rotation/scale
- Run Analysis: Click "Run Procrustes Analysis" for statistical alignment
- View Results: Detailed metrics card with minimum distance, std deviation, RMSE, and transformation matrix
- Export Results: Save complete analysis report with logs as TXT file (includes all processing logs)
🍎 Recommended: For the best scientific analysis experience, run on macOS which provides native rendering for all formats without WebView dependencies.
💡 Format Tip: All formats (OBJ, STL, GLTF, GLB) work great on macOS with native rendering. For other platforms, GLB or GLTF provide the best visual experience.
1. Load fossil specimen A (reference)
2. Load fossil specimen B (comparison)
3. Use Procrustes analysis to determine morphological similarities
4. Export quantitative data for species classification
1. Load original 3D model A
2. Load optimized version B
3. Compare geometry to ensure visual consistency
4. Validate that optimization maintains shape integrity
1. Load pre-operative scan A
2. Load post-operative scan B
3. Analyze surgical outcomes quantitatively
4. Export data for patient records and research
- Minimum iOS version: 12.0
- ARKit support for AR features
- Permissions: Camera, Photo Library access
- Full textured rendering with ModelViewer
- Minimum SDK version: 21 (Android 5.0)
- Target SDK version: 34
- Permissions: Camera, Storage access
- Full textured rendering with ModelViewer
- Modern web browser with WebGL support
- HTTPS required for AR features
- Progressive Web App (PWA) support
- Requires hosted files (not local)
- Windows 10 or later
- Ubuntu 18.04+ or equivalent Linux distribution
- Point cloud rendering for vertex data
- Use web version for textured models
- Load Objects: Use "Load Object A" and "Load Object B" buttons to select 3D files
- Navigate: Tap "View Objects" to open the interactive 3D viewer
- Transform: Use the control panel to move, rotate, and scale Object B
- Align: Position Object B to match Object A as closely as possible
- Analyze: Tap "Compare" to run Procrustes analysis
- Review: Examine detailed similarity metrics and visualizations
- Export: Save results as JSON or CSV for further analysis
- Specimen Comparison: Load multiple fossil specimens for taxonomic analysis
- Morphological Studies: Compare rock formations and geological structures
- Evolutionary Analysis: Track changes in fossil morphology over time
- Publication Ready: Export data in formats suitable for scientific papers
- Anatomical Studies: Compare anatomical structures across populations
- Treatment Analysis: Evaluate effectiveness of medical interventions
- Prosthetic Fitting: Ensure optimal fit for prosthetic devices
- Clinical Documentation: Generate reports for patient records
- Quality Assurance: Validate 3D assets meet design specifications
- Performance Optimization: Compare original and optimized models
- Consistency Checks: Ensure character models maintain visual consistency
- Asset Pipeline: Integrate comparison results into development workflows
- Single finger drag: Orbit around the objects
- Pinch to zoom: Zoom in/out
- Two-finger drag: Pan the view
- Preset views: Use top, front, side view buttons
- Reset: Return to default camera position
- Navigate to Settings from the home screen
- Customize theme (Light/Dark/System)
- Adjust default 3D model settings
- Configure background colors and grid display
- Manage tutorial preferences
- Interactive onboarding for new users
- Step-by-step guidance through core features
- Skippable tutorial with progress tracking
- Contextual help and tips
Run the following command to generate Isar database code:
flutter packages pub run build_runner build --delete-conflicting-outputs# Run all tests
flutter test
# Run specific test files
flutter test test/features/model_viewer/domain/services/procrustes_analysis_test.dart
# Run tests with coverage
flutter test --coverage# Analyze code for issues
flutter analyze
# Fix auto-fixable issues
dart fix --apply# Unix/Linux/macOS
./scripts/build_all.sh
# Windows
scripts\build_all.bat# Web
flutter build web --release
# Android
flutter build apk --release
flutter build appbundle --release
# iOS
flutter build ios --release
# Desktop
flutter build windows --release
flutter build macos --release
flutter build linux --release# Unix/Linux/macOS
./scripts/package_release.sh
# Windows
scripts\package_release.bat- Database: Isar database configuration and initialization
- DI: Dependency injection setup using GetIt
- Errors: Custom failure and exception classes
- Constants: Application-wide constants
- Animations: Custom page transitions and UI animations
- Main navigation screen with animated transitions
- Feature cards for different app sections
- Tutorial system integration
- Quick access to 3D viewer and settings
- 3D object loading (GLB/GLTF for full rendering, OBJ/STL for analysis)
- Real-time 3D visualization with WebGL (GLB/GLTF files)
- Interactive navigation with gesture controls
- Procrustes analysis and comparison
- Superimposed viewing with opacity controls
- Export functionality (JSON, CSV)
- MVVM architecture with clean separation
- Persistent storage of user settings
- Theme management (Light/Dark/System)
- 3D model viewing preferences
- Background color customization
- Tutorial preferences
- Interactive onboarding system
- Step-by-step guidance
- Progress tracking and navigation
- Contextual help overlays
The project includes GitHub Actions workflows for automated building and deployment:
- Build and Test: Runs on every push
- Release: Creates GitHub releases with all platform builds
- Web Deployment: Automatically deploys web version
See DEPLOYMENT.md for detailed deployment instructions for each platform.
See RELEASE.md for comprehensive release preparation and distribution guide.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes following the existing architecture
- Add tests for new functionality
- Ensure all tests pass (
flutter test) - Run code analysis (
flutter analyze) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow the existing clean architecture pattern
- Write comprehensive tests for new features
- Update documentation for API changes
- Ensure cross-platform compatibility
- Follow Flutter/Dart style guidelines
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
- GitHub Issues: Report bugs and request features
- Documentation: Wiki and guides
- Discussions: Community discussions
- Flutter Team: For the excellent cross-platform framework
- Model Viewer Plus: For 3D rendering capabilities
- Isar Team: For the fast local database solution
- Provider Team: For state management
- Vector Math: For 3D mathematics and transformations
- Community: For feedback, contributions, and support
- Morphological Analysis: Study shape variations in biological specimens
- Statistical Shape Analysis: Apply Procrustes methods for research
- Comparative Studies: Analyze differences between populations or species
- Data Visualization: Present 3D comparison results in academic papers
- Quality Control: Validate manufacturing precision in 3D printed objects
- Reverse Engineering: Compare original designs with reconstructed models
- Archaeological Studies: Analyze artifacts and historical objects
- Forensic Analysis: Compare evidence in 3D crime scene reconstruction
This tool implements Generalized Procrustes Analysis (GPA), a statistical method for:
- Shape Alignment: Removing translation, rotation, and scale differences
- Quantitative Comparison: Measuring shape similarities and differences
- Statistical Validation: Providing confidence intervals and significance tests
- Reproducible Results: Ensuring consistent analysis across different users
| Format | Loading | 3D Rendering | Procrustes Analysis | Data Export |
|---|---|---|---|---|
| GLB | ✅ | ✅ Full 3D | ✅ | ✅ |
| GLTF | ✅ | ✅ Full 3D | ✅ | ✅ |
| OBJ | ✅ | ✅ | ✅ | |
| STL | ✅ | ✅ | ✅ |
Fully Supported Formats:
- .glb: GL Transmission Format Binary - Optimized for web and real-time rendering
- .gltf: GL Transmission Format JSON - Modern 3D format with full material support
Platform Support for 3D Rendering:
| Platform | Native Rendering | Textured Rendering | Recommendation |
|---|---|---|---|
| macOS Desktop 🍎 | ✅ Full Support | Point Cloud | RECOMMENDED - Best performance |
| iOS (iPhone, iPad) | ✅ Full Support | ✅ Full Support | Excellent for mobile |
| Android | ✅ Full Support | ✅ Full Support | Excellent for mobile |
| Web (Chrome, Firefox, Safari) | ✅ Full Support | ✅ Full Support | Requires hosted files |
| Windows Desktop | Use web version | ||
| Linux Desktop | Use web version |
Features:
- ✅ Full 3D visualization with textures and materials
- ✅ Interactive camera controls (orbit, zoom, pan)
- ✅ Auto-rotation and animations
- ✅ WebGL-optimized rendering
- ✅ AR support (iOS/Android)
- ✅ Cross-platform compatibility
Platform-Specific Notes:
- macOS Desktop 🍎 (RECOMMENDED): Native 3D point cloud rendering using CustomPainter for all formats (OBJ, STL, GLTF, GLB). Features interactive rotation, zoom controls, and excellent performance. No WebView dependency required. Works perfectly with local files.
- Mobile (iOS/Android): Full support with local file loading and WebView-based rendering for textured models.
- Web Platform: Requires files to be hosted on a server or use data URLs. Local file system access is restricted for security.
- Windows/Linux Desktop: Point cloud rendering available for formats with vertex data. Use web version for textured rendering.
All file formats now support 3D rendering and analysis:
- .obj: Wavefront OBJ format - ✅ Native rendering on macOS, iOS, Android
- .stl: Stereolithography format - ✅ Native rendering on macOS, iOS, Android
- .gltf: GL Transmission Format - ✅ Native rendering on all platforms
- .glb: GL Binary Format - ✅ Native rendering on all platforms
Features on macOS (Recommended Platform):
- ✅ Full 3D point cloud rendering for all formats
- ✅ Interactive rotation (mouse drag) and zoom (scroll wheel)
- ✅ Perspective-based depth visualization
- ✅ Procrustes analysis with scientific metrics
- ✅ Complete log capture and TXT export
- ✅ Local file loading (no hosting required)
- ✅ Excellent performance with large models
Features on Other Platforms:
- iOS/Android: Full textured rendering for GLB/GLTF, point cloud for OBJ/STL
- Web: Point cloud rendering for all formats, textured rendering requires hosted files
- Windows/Linux: Point cloud rendering available
Option 1: Online Converters
Option 2: Blender (Free)
# Install Blender, then:
File → Import → Wavefront (.obj)
File → Export → glTF 2.0 (.glb)Option 3: Command Line (Node.js)
npm install -g obj2gltf
obj2gltf -i model.obj -o model.glbOption 4: Python
pip install trimesh
python -c "import trimesh; trimesh.load('model.obj').export('model.glb')"Download Free GLB Models:
- Khronos glTF Sample Models
- Sketchfab (filter by "Downloadable")
- Poly Pizza (free 3D models in GLB format)
Plans to add support for:
- .ply: Polygon File Format (point cloud data)
- .dae: COLLADA format
- .fbx: Autodesk format (gaming/animation)
- .3ds: 3D Studio format
- Direct OBJ→GLB runtime conversion
3D Object Comparison Tool - Professional scientific analysis platform for geology, gaming, and medical applications with advanced Procrustes analysis. Best experienced on macOS with native 3D rendering for all file formats.