Support multiple texture images per mesh (closes #2)

[csparker247]

Summary

This PR adds support for meshes textured by multiple images, closing #2. Each UV chart in a multi-chart mesh (e.g., multi-material OBJ) is now independently textured. The reorder pipeline normalizes all inputs to 8-bit/3-channel internally and samples each face from its UV chart's image, skipping uncolored regions and warning for missing textures.

Changes

Core Library (core/)

• ReorderUnorganizedTexture: Changed setTextureMat() → setTextureMats(std::vector<cv::Mat>) to accept multiple textures indexed by UV chart; removed getTextureMat()
• Input normalization: each image quantized to 8-bit and color-converted to 3-channel (BGR) on input
• Implement chart-aware sampling: new resolve_chart_image_() method resolves a face's texture from its UV chart; returns nullptr if chart is out of range or image is empty
• New report_missing_charts_() aggregates and warns once for all charts with no usable image
• Update ComputeUVDensity() to scale UV regions by their chart's image dimensions, supporting varying sizes in multi-chart meshes
• MeshIO: Change MeshReadResult to use std::vector<cv::Mat> textures and std::vector<std::filesystem::path> texturePaths (replacing scalar texture and texturePath)
• ReadMesh() now loads every referenced texture into the vectors, preserving alignment so chart i ↔ textures[i]; materials with no map_Kd (empty path) and missing images are stored as empty cv::Mat/path to maintain indexing

Graph Layer (graph/)

• MeshReadNode: Add images port exposing the full texture vector (canonical plural output); keep image port as a documented stopgap scalar convenience for single-image consumers (backed by a getter lambda returning images[0])—remove imagePath port
• ReorderTextureNode: Rename imageIn input port → imagesIn (type: std::vector<cv::Mat>)
• Wire the node's setter from setTextureMat → setTextureMats

Applications (apps/)

• ReorderTexture: Remove the now-unneeded ColorConvertNode; connect reorder->imagesIn directly to reader->images
• SeamFlattening, TextureDewarp: Update calls from setTextureMat() → setTextureMats()

Tests (tests/)

• Add a TwoChartMesh fixture and ReorderMultiTexture test cases (the first compute-level coverage for this class) covering:
  • SamplesEachChartFromItsImage: every colored pixel is exactly one of the two chart colors, and both charts contribute
  • SkipsFacesWhoseChartHasNoImage: a chart with no supplied image is left as background and triggers the aggregated warning
  • Tests use camera-path sampling (avoids the vtkOBBTree degenerate-mesh issue on small flat meshes; see ReorderUnorganizedTexture: orthographic path produces invalid output size for degenerate/tiny meshes (vtkOBBTree) #20)

Design Notes

• Chart-to-image mapping: Face colors come from UV chart indices embedded in the mesh's UVMap coordinates. The mapping is inherent to the mesh file format and read transparently by ReadMesh.
• Skip-and-warn: Faces whose chart has no image (out-of-range index or empty cv::Mat) remain uncolored in the output. A single aggregated warning names all affected chart indices; duplicates are deduplicated and sorted for clarity.
• Input normalization: All textures are quantized and color-converted on input to ensure consistent downstream behavior. Higher bit depths and non-3-channel layouts are not yet preserved (see ReorderUnorganizedTexture: support non-8bpc / non-3-channel input textures #19).
• Stopgap scalar convenience: The image output port on MeshReadNode is kept as a convenience for legacy single-texture consumers—it returns images[0] via a getter lambda. The plural images port is the canonical output and will become the only path once downstream code migrates.

Follow-ups

• ReorderUnorganizedTexture: support non-8bpc / non-3-channel input textures #19: Native support for non-8bpc and non-3-channel texture inputs without automatic conversion
• ReorderUnorganizedTexture: orthographic path produces invalid output size for degenerate/tiny meshes (vtkOBBTree) #20: Fix vtkOBBTree output-size calculation for degenerate meshes (current workaround: camera-path sampling)

Testing

• Full clean build succeeds (core, graph, all apps, all tests)
• ctest: 6/6 suites pass, including the new ReorderMultiTexture.* cases
• End-to-end run against a real multi-material mesh not yet performed — recommended before merge

Closes #2

🤖 Generated with Claude Code