File size: 4,605 Bytes
7a87926 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 |
# File Organization
## Directory Structure
The YLFF package follows a clear organizational structure:
```
ylff/
├── __init__.py # Package initialization with backward compatibility
├── __main__.py # Entry point for `python -m ylff`
├── app.py # Unified CLI/API entry point
├── cli.py # CLI command definitions (Typer)
├── api.py # Backward compatibility wrapper
├── config.py # Configuration management (Pydantic Settings)
│
├── models/ # Pydantic API models
│ ├── __init__.py
│ └── api_models.py
│
├── routers/ # FastAPI route handlers
│ ├── __init__.py
│ ├── health.py
│ ├── jobs.py
│ ├── models.py
│ ├── profiling.py
│ ├── training.py
│ ├── validation.py
│ └── visualization.py
│
├── services/ # Business logic
│ ├── __init__.py
│ ├── arkit_processor.py
│ ├── ba_validator.py
│ ├── data_pipeline.py
│ ├── evaluate.py
│ ├── fine_tune.py
│ └── pretrain.py
│
└── utils/ # Utilities and helpers
├── __init__.py
├── api_middleware.py
├── coordinate_utils.py
├── exceptions.py # Custom exception classes
├── job_manager.py
├── losses.py # Loss functions for training
├── model_loader.py # ML model loading utilities
├── profiler.py
├── visualization_gui.py
└── wandb_utils.py
```
## Organization Principles
### Root Level (`ylff/`)
Only core application files:
- **`app.py`**: Unified entry point (CLI/API)
- **`cli.py`**: CLI command definitions
- **`config.py`**: Configuration management
- **`api.py`**: Backward compatibility wrapper
- **`__init__.py`**: Package initialization
### `models/` - Pydantic API Models
- Request/response models for the API
- Data validation and serialization
- Example: `JobResponse`, `ValidateSequenceRequest`
### `routers/` - API Route Handlers
- FastAPI route definitions
- One router per domain (health, jobs, validation, etc.)
- Thin layer that delegates to services
### `services/` - Business Logic
- Core application logic
- Domain-specific functionality
- Examples: `BAValidator`, `ARKitProcessor`, `fine_tune_da3`
### `utils/` - Utilities and Helpers
- Reusable utilities across the codebase
- **`exceptions.py`**: Custom exception classes
- **`losses.py`**: Loss functions for training
- **`model_loader.py`**: ML model loading utilities
- **`profiler.py`**: Performance profiling
- **`coordinate_utils.py`**: Coordinate system conversions
- **`job_manager.py`**: Background job management
- **`visualization_gui.py`**: GUI utilities
- **`wandb_utils.py`**: Weights & Biases integration
## Import Patterns
### From Utils
```python
# Exceptions
from ylff.utils.exceptions import DataError, ModelLoadError
# Loss functions
from ylff.utils.losses import pose_loss, geodesic_rotation_loss
# Model loading
from ylff.utils.model_loader import load_da3_model, get_recommended_model
# Other utilities
from ylff.utils.profiler import Profiler
from ylff.utils.coordinate_utils import convert_arkit_to_opencv
```
### From Services
```python
from ylff.services.ba_validator import BAValidator
from ylff.services.arkit_processor import ARKitProcessor
from ylff.services.fine_tune import fine_tune_da3
```
### From Models
```python
from ylff.models import JobResponse, ValidateSequenceRequest
```
### From Routers
```python
from ylff.routers import health_router, validation_router
```
## Migration History
### Moved to `utils/`
- **`exceptions.py`** → `utils/exceptions.py` (was at root)
- **`losses.py`** → `utils/losses.py` (was at root)
- **`model_loader.py`** → `utils/model_loader.py` (was at root, renamed from `models.py`)
### Rationale
- All three files are utilities used across multiple modules
- Keeps the root `ylff/` directory clean and focused
- Makes it clear these are reusable utilities, not core application logic
- Follows the principle: "If it's used by multiple services, it's a utility"
## Backward Compatibility
The `ylff/__init__.py` provides backward compatibility imports:
```python
# Still works (via __getattr__)
from ylff import BAValidator, Profiler, load_da3_model
```
But preferred imports are:
```python
from ylff.utils.model_loader import load_da3_model
from ylff.utils.losses import pose_loss
from ylff.utils.exceptions import DataError
```
|