Home

Project Overview

MapGen is a map augmentation tool for unity that allows users to import, modify, and export 3D map files with custom objects and preferences through YAML configuration files.

Functional Requirements

Map Import & File Format Support

• Input Support: .fbx , .obj

Model Editing & Augmentation Capabilities

Users can modify imported meshes through YAML configuration:

• Terrain Modification: Raise/lower ground or terrain parts
• Primitive Addition: Insert cubes, spheres, cylinders, prisms
• Custom Model Insertion: Place user-provided 3D models
• Automated Processing: Apply augmentations automatically based on configuration

Custom Model Integration

• Model Import: Support for user's custom 3D models in multiple formats
• Placement System: Intelligent positioning on base map geometry
• Library Management: Organize and reuse custom models across projects

Export & Output Management

• Multi-format Export: .obj, .stl, .glb output formats
• Batch Export: Process multiple configurations in single operation
• Organized Output: Structured file organization in output directories
• Metadata Preservation: Maintain material and texture information

Configuration Management

• YAML-based Control: All modifications defined through YAML files
• Validation System: Comprehensive configuration validation before processing
• Template System: Reusable configuration templates
• Manual Override: Option for hand-crafted configurations

Non-Functional Requirements

Performance & Scalability

• Batch Processing: Efficient handling of multiple map configurations
• Memory Management: Optimized for large mesh files and datasets
• Progress Tracking: Real-time feedback during long operations

Usability & User Experience

• YAML-driven Workflow: Primary interaction through configuration files
• Clear Error Messages: Descriptive feedback for configuration issues
• Validation Feedback: Pre-processing configuration validation

Cross-Platform Compatibility

• Operating Systems: Windows, macOS, Linux support
• Python Compatibility: Python 3.8+ requirement
• File System: Handle different path conventions and file permissions
• Dependencies: Platform-independent library selection

Reliability & Error Handling

• Configuration Validation: Robust YAML/JSON schema validation
• File Format Validation: Verify mesh integrity before processing
• Graceful Degradation: Continue processing valid configs if others fail

Security & Safety

• File System Security: Restrict access to designated input/output directories
• Input Sanitization: Validate all file paths and configuration parameters
• Memory Safety: Prevent buffer overflows with large mesh files
• No Code Execution: Configuration files cannot execute arbitrary code
• Path Traversal Protection: Prevent unauthorized file system access

Modularity & Extensibility

• Component Architecture: Separate validation, processing, and I/O logic
• Factory Patterns: Easy addition of new file formats and augmentation types
• API Design: Clean interfaces for future feature integration
• Configuration Schema: Extensible YAML schema for new augmentation types

Offline Functionality

• Complete Offline Operation: No internet connectivity required after installation
• Local Processing: All mesh operations performed locally
• Embedded Resources: All required assets included in installation

Maintainability & Quality

• Code Quality: Type hints, comprehensive docstrings, linting compliance
• Version Control: Git-based development with semantic versioning
• Dependency Management: Pinned versions for reproducible builds