Heritage GIS

Texture Mapping & UV Alignment Automation

Within the broader Photogrammetry & 3D Site Mapping Pipelines framework, automated texture mapping and UV alignment serve as a mandatory compliance checkpoint for archaeological documentation. Manual unwrapping introduces unacceptable variability in spatial fidelity, ground sample distance (GSD) preservation, and archival reproducibility. This cluster delivers a field-ready, script-driven workflow that enforces geospatial integrity, automates projection alignment, and embeds explicit validation rules directly into the photogrammetric pipeline for heritage managers, academic research teams, and Python GIS developers.

Geospatial Preconditioning & CRS Validation

Texture projection in heritage contexts must remain strictly bound to real-world coordinate systems. Following Automated Drone Image Processing Workflows, orthorectified imagery and dense point clouds must undergo rigorous coordinate verification before UV generation. Misaligned CRS definitions cause texture shear, scale drift, and irreversible georeferencing loss.

The automation pattern begins with a mandatory CRS transformation check:

  1. Extract the native CRS from the orthomosaic metadata (GeoTIFF tags or sidecar .prj/.aux.xml).
  2. Validate against the project’s mandated spatial reference (e.g., UTM zone such as EPSG:32633, national grid like EPSG:27700, or a local archaeological datum).
  3. If mismatched, apply a lossless coordinate transformation using pyproj with explicit datum shift grids (e.g., NTv2 or NADCON) to prevent sub-meter distortion.
  4. Log the transformation matrix, source EPSG, target EPSG, and residual error (RMSE) for compliance auditing.

Skipping this step propagates projection artifacts into the final 3D asset, compromising both analytical measurement and long-term digital preservation standards. Coordinate transformations must adhere to ISO 19111 spatial referencing principles to guarantee metric consistency across temporal survey campaigns.

Automated UV Projection Pipeline

Once topology is stabilized via Mesh Generation & Optimization for Ruins, UV alignment executes through a deterministic routing sequence. The workflow relies on planar or cylindrical projection mapped directly from georeferenced orthoimagery, bypassing subjective manual seam placement.

Pipeline Routing & Execution Steps

Stage Input Process Output
Mesh Normalization .obj / .ply Translate centroid to (0,0,0), scale to real-world meters, preserve vertex indices Normalized mesh, scale matrix
EOP Integration Camera poses (.xml / .json) Align UV space with exterior orientation parameters via bundle adjustment residuals Pose-aligned projection matrix
Ortho-to-UV Mapping Georeferenced raster (.tif) Ray-cast or apply planar projection matrices to map pixel coordinates to mesh faces Raw UV coordinate array
Seam Optimization Raw UV array + mesh topology Edge-weighted unwrapping along architectural breaks (wall joints, stratigraphic boundaries) Optimized UV layout (.uv)
Texture Baking & Export Optimized UV + raster data High-resolution texture baking, spatial metadata attachment, format conversion Georeferenced .gltf / .obj + .png/.tif

The projection engine utilizes rasterio for coordinate-to-pixel mapping and trimesh for face-level UV assignment. All operations are executed in-memory where possible to prevent I/O bottlenecks during high-polygon heritage mesh processing.

Version-Pinned Dependencies & Environment Isolation

Reproducibility in archaeological GIS requires strict dependency control. The following stack is validated for production deployment and must be installed in an isolated virtual environment:

# requirements.txt
numpy==1.26.4
pyproj==3.6.1
rasterio==1.3.9
trimesh==4.2.0
scipy==1.12.0
Pillow==10.2.0

Python 3.11+ is mandated for performance optimizations in array slicing and memory management. Environment isolation should be managed via venv or conda to prevent system-level package conflicts. All spatial operations must reference the official EPSG Registry for authoritative code validation and datum transformation parameters.

Validation & Compliance Checkpoints

Automated UV alignment must pass quantitative validation before archival submission:

  • GSD Preservation: Texture resolution must match the source orthomosaic GSD within ±2%. Deviations indicate scaling drift during projection.
  • UV Distortion Metrics: Compute area-weighted UV stretch using the Jacobian determinant of the mapping function. Threshold: <5% distortion across primary architectural surfaces.
  • Seam Continuity: Verify that UV seams align with non-critical topological edges. Cross-seam color variance must remain below ΔE 2.0 in CIELAB space.
  • Metadata Embedding: Attach OGC-compliant spatial metadata (CRS, acquisition date, sensor model) to the exported asset header.

Failed validations trigger automatic pipeline rollback, logging the exact failure stage and metric deviation for operator review. This ensures that only spatially compliant assets enter digital heritage repositories.

Integration & Operational Notes

Deploy this cluster as a modular Python package within your broader site mapping infrastructure. Route inputs from the preceding photogrammetric stages via standardized directory structures:

/project_root/
├── inputs/
│   ├── orthomosaic.tif
│   ├── mesh_normalized.obj
│   └── camera_poses.xml
├── scripts/
│   └── uv_align_pipeline.py
└── outputs/
    ├── uv_layout.obj
    ├── texture_georef.tif
    └── validation_report.json

Execution should be wrapped in a CI/CD or batch scheduler (e.g., cron, Airflow, or Snakemake) to enforce sequential dependency resolution. All logs must be serialized to JSON for downstream auditability and integration with heritage management databases.