Add mesh inspection and native codec support

Introduce OBJ-focused mesh inspection and native image codec backends with Python bindings and example updates.

- Add MeshInspectionRequest/MeshInspectionResult types and InspectMeshFile API to report OBJ bounds, UV range, group spans, and usemtl->material ID mapping.
- Parse OBJ material IDs in mesh loader, store per-vertex materialId in TriMesh, expose material IDs to GPU as layout(location = 4) uint attribute and propagate into shared mesh resources.
- Update example RenderObjPerspectiveBaseColor.py to use rawgl.inspect_mesh_file, bind material IDs as uniforms, and select textures by material ID.
- Add nanobind bindings: MeshInspectionRequest/MeshMaterialInfo/MeshGroupInfo/MeshInspectionResult and high-level inspect_mesh_file() helper in Python.
- Implement selectable native image backends (JPEG/PNG/TIFF/OpenEXR) with compile-time detection and OpenImageIO fallback; add backend selection logging and stricter native writer error reporting (native writers now fail instead of silently falling back).
- Change output writer and runtime APIs: save_image_output now returns bool with errorMessage, IoRuntimeService::saveImageOutput signature updated accordingly.
- Update docs and README to describe native codec behavior, options, and mesh inspection usage; add tests and CMake entries for new smoke tests and scripts.

These changes add pre-flight mesh inspection utilities, improve image codec control and error handling, and wire the new features through the Python layer and examples.

Author: ssh4net

README.md

@@ -3,18 +3,19 @@ Command line image processing tool using OpenGL GLSL shaders.
 
 ## Features
 
-**Image import/export use OpenimageIO**\
-Support all image file formats that support by OpenimageIO for import:
-* Camera RAWs (oiio compiled with libraw plugin)
-* OpenEXR
-* TIFF
-* PNG
-* JPEG
-* JPEG-2000 (oiio compiled with openjpeg plugin)
-* etc.\
-Export for this moment limited to JPG, PNG, TIFF, TGA, HDR, EXR
-
-**On image import and export allow define OpenimageIO reading/writing options like:**
+**Image import/export uses native backends for common production formats, with OpenImageIO fallback for formats that are not native yet.**
+Native paths currently cover:
+* JPEG through libjpeg-turbo/libjpeg
+* PNG through libpng
+* TIFF through libtiff, including tiled TIFF and BigTIFF
+* OpenEXR through OpenEXR, including tiled EXR
+
+OpenImageIO remains available as the fallback path for formats that have not
+moved to native backends yet, such as camera RAW through OIIO's LibRaw plugin,
+JPEG-2000 through OIIO's OpenJPEG plugin, TGA, HDR, WebP, and other OIIO
+plugins available in the dependency build.
+
+**On image import and export allow define codec reading/writing options like:**
 * oiio:ColorSpace ACES
 * oiio:RawColor 1
 * oiio:UnassociatedAlpha
@@ -27,7 +28,9 @@ Export for this moment limited to JPG, PNG, TIFF, TGA, HDR, EXR
 * raw:ColorSpace ProPhoto-linear
 * raw:Demosaic AHD-Mod
 * etc.\
-More about possible OpenimageIO options read there:
+Native backends support the RawGL options listed above for their format family.
+OIIO fallback formats still use OIIO/plugin attributes. More about possible
+OpenImageIO options read there:
 https://openimageio.readthedocs.io/en/latest/builtinplugins.html
 https://openimageio.readthedocs.io/en/latest/stdmetadata.html#sec-metadata-color
 https://openimageio.readthedocs.io/en/latest/oiiotool.html
@@ -167,6 +170,11 @@ rawgl.make_host_image(array)
 rawgl.host_image_to_array(host_image)
 ```
 
+Use `rawgl.inspect_mesh_file(path)` when a script needs mesh facts before it
+builds a workflow. The current detailed path is OBJ-focused and reports source
+counts, bounds, UV range, group spans, and `usemtl` material IDs without loading
+MTL files.
+
 For more explicit control, the lower-level nanobind façade remains available under:
 
 ```python
@@ -260,6 +268,8 @@ Documentation
 | | **true (default)** - file already contains triangles |
 | | false - triangulate polygon faces during mesh load |
 | | Supported file formats: PLY and OBJ |
+| | OBJ `usemtl` material-name IDs are available in shaders as `layout(location = 4) in uint material_id;` |
+| | MTL files are ignored on this path. Bind textures explicitly from the workflow/script. |
 | | **rend:** |
 | | **tr (default)** - GL_TRIANGLES: render as polygons |
 | | ln - GL_LINES: render as lines |
@@ -310,7 +320,7 @@ Documentation
 | | --in UniformVec3 0.15 0.25 0.165 |
 | | --in UniformMatx 0.1 0.2 0.3  0.4 0.5 0.6  0.7 0.8 0.9 |
 | |
-| -t [ --in_attr ] arg | OpenImageIO/plugin attribute value |
+| -t [ --in_attr ] arg | Codec/plugin input attribute value |
 | | (e.g.: --in_attr oiio:colorspace sRGB). |
 | | **Some used defaults** |
 | | oiio:ColorSpace Linear |
@@ -336,10 +346,11 @@ Documentation
 | | r16, rg16, rgb16, rgba16, |
 | | r16f, rg16f, rgb16f, rgba16f, |
 | | r32f, rg32f, rgb32f, rgba32f |
-| | If format not support this bit depth OpenImageIO automatically convert to supported bit depth. |
+| | File writers convert this host format to the requested `--out_bits` when the target codec supports it. |
 | |
-| -r [ --out_attr ] arg | OpenImageIO/plugin attribute value |
-| | (e.g.: --out_attr oiio:colorspace sRGB). |
+| -r [ --out_attr ] arg | Codec/plugin output attribute value |
+| | (e.g.: --out_attr tiff:compression zip). |
+| | Native output families use native attributes directly. Invalid native JPEG, PNG, TIFF, or OpenEXR writer options fail instead of silently falling back to OpenImageIO. |
 | |
 | -n [ --out_channels ] arg | # of channels in output image |
 | |

cmake/rawgl_testing.cmake

@@ -42,6 +42,7 @@ if(BUILD_TESTING)
     endfunction()
 
     rawgl_add_cpp_smoke_test(rawgl_core_inspect_smoke tests/rawgl_core_inspect_smoke.cpp)
+    rawgl_add_cpp_smoke_test(rawgl_core_mesh_inspect_smoke tests/rawgl_core_mesh_inspect_smoke.cpp)
     rawgl_add_cpp_smoke_test(rawgl_core_graph_smoke tests/rawgl_core_graph_smoke.cpp)
     rawgl_add_cpp_smoke_test(rawgl_core_default_vertex_smoke tests/rawgl_core_default_vertex_smoke.cpp)
     rawgl_add_cpp_smoke_test(rawgl_core_system_uniform_reject_smoke tests/rawgl_core_system_uniform_reject_smoke.cpp)
@@ -55,6 +56,21 @@ if(BUILD_TESTING)
     rawgl_add_cpp_smoke_test(rawgl_core_transient_output_reuse_smoke tests/rawgl_core_transient_output_reuse_smoke.cpp)
     rawgl_add_cpp_smoke_test(rawgl_io_workflow_smoke tests/rawgl_io_workflow_smoke.cpp)
     rawgl_add_cpp_io_smoke_test(rawgl_io_host_image_smoke tests/rawgl_io_host_image_smoke.cpp)
+    if(TARGET PNG::PNG AND TARGET TIFF::TIFF AND TARGET OpenEXR::OpenEXR)
+        rawgl_add_cpp_io_smoke_test(rawgl_io_native_codec_errors_smoke tests/rawgl_io_native_codec_errors_smoke.cpp)
+        target_include_directories(rawgl_io_native_codec_errors_smoke PRIVATE
+            "${CMAKE_SOURCE_DIR}/src/io")
+    endif()
+    if(TARGET PNG::PNG AND TARGET JPEG::JPEG AND TARGET OpenEXR::OpenEXR)
+        rawgl_add_cpp_io_smoke_test(rawgl_io_native_codecs_smoke tests/rawgl_io_native_codecs_smoke.cpp)
+        target_include_directories(rawgl_io_native_codecs_smoke PRIVATE
+            "${CMAKE_SOURCE_DIR}/src/io")
+    endif()
+    if(TARGET TIFF::TIFF)
+        rawgl_add_cpp_io_smoke_test(rawgl_io_tiff_native_smoke tests/rawgl_io_tiff_native_smoke.cpp)
+        target_include_directories(rawgl_io_tiff_native_smoke PRIVATE
+            "${CMAKE_SOURCE_DIR}/src/io")
+    endif()
     if(RAWGL_HAS_OPENMETA)
         rawgl_add_cpp_io_smoke_test(rawgl_io_metadata_smoke tests/rawgl_io_metadata_smoke.cpp)
     endif()
@@ -65,6 +81,11 @@ if(BUILD_TESTING)
     set_tests_properties(rawgl_core_inspect_smoke PROPERTIES
         WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}")
 
+    add_test(NAME rawgl_core_mesh_inspect_smoke
+        COMMAND rawgl_core_mesh_inspect_smoke)
+    set_tests_properties(rawgl_core_mesh_inspect_smoke PROPERTIES
+        WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}")
+
     add_test(NAME rawgl_core_graph_smoke
         COMMAND rawgl_core_graph_smoke)
     set_tests_properties(rawgl_core_graph_smoke PROPERTIES
@@ -125,6 +146,27 @@ if(BUILD_TESTING)
     set_tests_properties(rawgl_io_host_image_smoke PROPERTIES
         WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}")
 
+    if(TARGET PNG::PNG AND TARGET TIFF::TIFF AND TARGET OpenEXR::OpenEXR)
+        add_test(NAME rawgl_io_native_codec_errors_smoke
+            COMMAND rawgl_io_native_codec_errors_smoke)
+        set_tests_properties(rawgl_io_native_codec_errors_smoke PROPERTIES
+            WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}")
+    endif()
+
+    if(TARGET PNG::PNG AND TARGET JPEG::JPEG AND TARGET OpenEXR::OpenEXR)
+        add_test(NAME rawgl_io_native_codecs_smoke
+            COMMAND rawgl_io_native_codecs_smoke)
+        set_tests_properties(rawgl_io_native_codecs_smoke PROPERTIES
+            WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}")
+    endif()
+
+    if(TARGET TIFF::TIFF)
+        add_test(NAME rawgl_io_tiff_native_smoke
+            COMMAND rawgl_io_tiff_native_smoke)
+        set_tests_properties(rawgl_io_tiff_native_smoke PROPERTIES
+            WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}")
+    endif()
+
     add_test(NAME rawgl_io_workflow_smoke
         COMMAND rawgl_io_workflow_smoke)
     set_tests_properties(rawgl_io_workflow_smoke PROPERTIES
@@ -180,6 +222,7 @@ if(BUILD_TESTING)
         rawgl_add_script_test(rawgl_invalid_vertfrag_arity test_invalid_vertfrag_arity)
         rawgl_add_script_test(rawgl_mesh_ao_sponge test_mesh_ao_sponge)
         rawgl_add_script_test(rawgl_mesh_cli_order test_mesh_cli_order)
+        rawgl_add_script_test(rawgl_mesh_obj_material_smoke test_mesh_obj_material_smoke)
         rawgl_add_script_test(rawgl_mesh_obj_smoke test_mesh_obj_smoke)
         rawgl_add_script_test(rawgl_mesh_ply_smoke test_mesh_ply_smoke)
         rawgl_add_script_test(rawgl_missing_input_uniform test_missing_input_uniform)

docs/sphinx/examples.rst

@@ -225,8 +225,13 @@ For a larger OBJ import, run
 ``examples/Mesh/OBJ/RenderObjPerspectiveBaseColor.py``. The file in that
 directory uses quads, mesh normals, named groups, and two U-coordinate tiles.
 The example sets ``tris`` to ``false`` so RawGL triangulates the faces while
-loading the mesh. It uses the first U tile for the bunny base-color texture and
-the second U tile for the skateboard texture.
+loading the mesh. It reads OBJ material IDs into vertex attribute location 4,
+then chooses the bunny or skateboard base-color texture from that material ID.
+RawGL derives these IDs from ``usemtl`` names in the OBJ file and does not load
+the MTL file for this path.
+
+The script calls ``rawgl.inspect_mesh_file(...)`` before building the workflow
+to read bounds, group spans, UV range, and the material-name to ID mapping.
 
 .. image:: _static/examples/obj_perspective_basecolor_640.jpg
    :alt: Perspective OBJ render using two base-color texture tiles

docs/sphinx/io.rst

@@ -23,6 +23,101 @@ Current split:
 - ``rawgl_core`` executes workflows
 - ``rawgl_io`` owns file decode/encode and file-oriented workflow translation
 
+Codec backends
+--------------
+
+``rawgl_io`` uses native backends for the common formats that need predictable
+settings control:
+
+- JPEG through libjpeg-turbo/libjpeg
+- PNG through libpng
+- TIFF through libtiff, including tiled TIFF and BigTIFF
+- OpenEXR through OpenEXR, including tiled EXR
+
+OpenImageIO remains the fallback path for formats that have not moved to native
+backends yet, such as camera RAW, JPEG-2000, TGA, HDR, WebP, and other plugins
+available in the dependency build.
+
+Native writers are strict for native output families. If a native JPEG, PNG,
+TIFF, or OpenEXR writer rejects an option, RawGL returns that error instead of
+silently retrying the write through OpenImageIO. The read path may still fall
+back to OpenImageIO when a native reader cannot decode a supported format
+variant.
+
+Native codec options
+--------------------
+
+JPEG output accepts:
+
+- ``jpeg:quality`` or ``jpg:quality``: integer quality from ``1`` to ``100``
+- ``jpeg:progressive`` or ``jpg:progressive``: ``true``/``false``
+- ``oiio:Compression`` with ``jpeg:N`` or ``jpg:N``: legacy quality spelling
+
+JPEG writes grayscale or RGB data. Alpha channels are omitted.
+
+PNG output accepts:
+
+- ``png:compressionLevel``: integer from ``0`` to ``9``
+- ``png:interlace`` or ``png:interlaced``: ``true`` enables Adam7 interlace
+
+PNG writes 8-bit and 16-bit integer images.
+
+TIFF output accepts:
+
+- ``tiff:compression``: ``none``, ``lzw``, ``packbits``, ``zip``, ``deflate``,
+  or ``adobe_deflate``
+- ``compression`` or ``oiio:Compression``: legacy compression spelling
+- ``tiff:predictor``: ``none``/``1``, ``horizontal``/``2``, or ``float``/``3``
+- ``tiff:tiled``: ``true``/``false``
+- ``tiff:tileWidth`` and ``tiff:tileLength`` or ``tiff:tileHeight``
+- ``tiff:rowsPerStrip`` for striped output
+- ``tiff:bigTiff`` or ``tiff:bigtiff``: force BigTIFF output
+- ``oiio:UnassociatedAlpha``: mark the extra alpha sample as unassociated
+
+TIFF writes 8-bit, 16-bit, and 32-bit float output. ``tiff:rowsPerStrip`` is
+not valid when tiled output is enabled. TIFF predictors require LZW or Deflate
+compression; the floating-point predictor is valid only for 32-bit float
+output.
+
+OpenEXR output accepts:
+
+- ``openexr:compression``: any compression name accepted by OpenEXR, such as
+  ``zip``, ``zips``, ``piz``, ``rle``, ``dwaa``, or ``dwab``
+- ``compression`` or ``oiio:Compression``: legacy compression spelling
+- ``openexr:tiled``: ``true``/``false``
+- ``openexr:tileWidth`` and ``openexr:tileHeight`` or ``openexr:tileLength``
+- ``openexr:dwaCompressionLevel`` for DWAA/DWAB
+- ``openexr:lineOrder``: ``increasing_y``, ``decreasing_y``, or ``random_y``
+- ``openexr:attribute:string:<name>``: write one string header attribute
+
+OpenEXR writes half and 32-bit float output.
+
+Example output attributes:
+
+.. code-block:: bat
+
+   RawGL.exe ^
+     --out OutColor output.tif ^
+     --out_bits 16 ^
+     --out_attr tiff:compression zip ^
+     --out_attr tiff:tiled true ^
+     --out_attr tiff:tileWidth 256 ^
+     --out_attr tiff:tileLength 256
+
+.. code-block:: python
+
+   rawgl.io.save_image(
+       image,
+       "output.exr",
+       bits=16,
+       attributes={
+           "openexr:compression": "zip",
+           "openexr:tiled": "true",
+           "openexr:tileWidth": "64",
+           "openexr:tileHeight": "64",
+       },
+   )
+
 Typical file-backed C++ path
 ----------------------------
 

docs/sphinx/python.rst

@@ -21,6 +21,7 @@ The normal path is the high-level helper layer:
 - ``rawgl.prepare_image(...)``
 - ``rawgl.prepare_render(...)``
 - ``rawgl.prepare_compute(...)``
+- ``rawgl.inspect_mesh_file(...)``
 
 Use the explicit ``rawgl.io`` helper surface when the workflow starts or ends
 with files:
@@ -155,6 +156,24 @@ Typical inspection shape:
        name_policy=rawgl.MetadataNamePolicy.exif_tool_alias,
    )
 
+Mesh inspection
+---------------
+
+Use ``rawgl.inspect_mesh_file(...)`` when a script needs mesh facts before it
+builds a workflow. The current detailed path is OBJ-focused and reports source
+counts, bounds, UV range, group spans, and ``usemtl`` material IDs without
+loading any MTL files.
+
+.. code-block:: python
+
+   import rawgl
+
+   mesh_info = rawgl.inspect_mesh_file("model.obj")
+   if not mesh_info.success:
+       raise RuntimeError(mesh_info.error_message)
+
+   material_ids = {material.name: material.id for material in mesh_info.materials}
+
 Prepared workflows
 ------------------