Skip to content

Keep every face and material of OBJ models whose parts differ; KTX2 sizes multiple of 4 - #109

Merged
HeDo88TH merged 3 commits into
masterfrom
fix/obj-model-edge-cases
Nov 17, 2026
Merged

HeDo88TH merged 3 commits into
masterfrom
fix/obj-model-edge-cases

Conversation

@HeDo88TH

Copy link
Copy Markdown
Collaborator

This pull request fixes how Obj2Tiles reads OBJ models whose parts differ (some parts textured, some not; material names with spaces; vertex colours or texture coordinates on only some objects), and the size of KTX2 textures. Such models are common: Blender and Assimp write them. Before this change, Obj2Tiles dropped parts of them, mixed up their materials, wrote KTX2 textures that WebGL shows black, or failed.

Defects fixed

1. Faces without texture coordinates were dropped from the finest level (MeshUtils.LoadMesh)

In a textured model, the faces without texture coordinates (an untextured part with its own material) were dropped by the split stage, which makes the finest level. The coarser levels, made by the decimation, kept them. So a textured model with untextured parts showed only its textured parts up close. These faces are now kept, with their material and one shared texture coordinate, as the decimation already gives them. The texture repacking now also keeps the texture coordinates of a material without a texture (they pointed into the replaced list).

2. Material names with spaces (usemtl, newmtl, mtllib, g, o)

usemtl read only the first word of the material name in the split stage, and a usemtl with more than one word was ignored. So the faces of a material such as Paint 1 Carmine took the previous material. Names now run to the end of the line. A new helper, ObjStatement, splits a statement into keyword and argument; the OBJ reader of the split stage, the OBJ reader of the decimation and the MTL reader all use it, so they all read the same name. The MTL reader also accepts a tab after the keyword.

3. KTX2 textures whose size is not a multiple of 4 were shown black in WebGL (Ktx2Encoder)

The GPU formats that Basis Universal textures are transcoded to (BC1-7, ETC, ASTC) are made of 4x4 blocks. KHR_texture_basisu requires the width and height of a KTX2 image to be multiples of 4, and WebGL rejects a BC texture of another size (INVALID_OPERATION). three.js on desktop GPUs showed such textures black (for example a 250x250 texture was black, a 256x256 texture was correct). The encoder now stretches an image of another size to the nearest multiple of 4 (250x250 to 252x252, 249x250 to 248x252) before it encodes it. Stretching, not padding, keeps the texture coordinates correct, because they are fractions of the image. Every mip level of an aligned image is then valid too. Images that are already aligned are encoded as before.

4. Crashes and wrong materials on mixed models

  • Vertex colours on only some vertices failed the split stage (All vertices must have colors or none). The other vertices are now white, as the decimation already did.
  • Texture coordinates (or normals) first given after some faces, as Blender writes when only the last object is unwrapped, failed the decimation with Index was out of range. Every per-vertex attribute is now kept at the index of its vertex; the earlier vertices get the default value.
  • Faces before the first usemtl moved the material names of the decimation onto the wrong sub-meshes, and failed it with The number of sub-mesh material names does not match. A usemtl without faces did the same. The decimation now records a sub-mesh and its material together (this also replaces the earlier fix for Exception: The number of sub-mesh material names does not match the count of sub-mesh index arrays.  #54).
  • Texture coordinates without any material made a textured mesh without materials, whose tiles referenced texture coordinates that were not written. Such a model is now untextured.

Behaviour change

Faces before the first usemtl now get a material named default at every level (it is added, without colour or texture, if the MTL file has no material with that name). This is the same material that the glTF conversion already gives them. Before, the split stage gave them the first material of the MTL file, which is usually the texture of another part.

Tests

  • Obj2Tiles.Library.Test/ModelPartsLoadingTests.cs: the split-stage reader keeps faces without texture coordinates with their material, reads names with spaces, gives faces before the first usemtl the default material, makes an untextured mesh from texture coordinates without materials, and makes missing vertex colours white; writing the finest level keeps every face with valid texture coordinates.
  • Obj2Tiles.Library.Test/ObjStatementTests.cs: keyword and argument splitting, and MTL names with spaces or after a tab.
  • Obj2Tiles.Test/ObjMeshParsingTests.cs: the decimation reader keeps texture coordinates and normals given after some faces at their vertices, and keeps sub-meshes and material names aligned (faces before the first usemtl, usemtl without faces, names with spaces).
  • Quality gate, Obj2Tiles.Test/Quality/ModelEdgeCaseQualityTests.cs: runs the CLI with --texture-format Ktx2 --ktx2-quality 192 --split-strategy VertexMedian (one tile, and an octree of three levels) on generated models, then checks the output with the inspector and the official 3D Tiles validator: a textured part next to an untextured part, both with material names with spaces (every level has both materials, the finest level has all their triangles); textures of 250x250, 249x250 and 30x2 (KTX2 sizes are multiples of 4); objects with and without vertex colours, texture coordinates and usemtl; texture coordinates without any material.
  • The quality-gate inspector now reports a KTX2 image whose size is not a multiple of 4 (TilesetInspectorTests).

Local results: Obj2Tiles.Library.Test 215 passed, Obj2Tiles.Test 173 passed, quality gate 107 passed (4 skipped: the large datasets, not enabled locally).

Performance and output

Release build of master (v1.10.2) against this branch, default options, on three ODM textured models (odm_textured_model_geo.obj, 27 MB to 63 MB, 49 b3dm each), runs alternated:

  • Every b3dm is byte-identical to the v1.10.2 output. The changes only affect models with the parts described above.

  • tileset.json references the same b3dm files. Its tree (which tile is placed under which parent) can differ from the v1.10.2 output, but it already differs in the same way between two runs of v1.10.2 on the same model, so this is not caused by this change.

  • Peak memory (maximum resident set) is within 2% of v1.10.2, in both directions.

  • No slowdown. The machine was shared with other work, so wall times varied widely between runs of the same binary; CPU time (user + system, median of 3 runs, on the two models measured this way) is the steadier measure:

    Model v1.10.2 CPU time This branch CPU time Wall time, v1.10.2 (3 runs) Wall time, this branch (3 runs)
    38 MB model, 49 b3dm 412 s 402 s 40.5 / 29.8 / 52.4 s 37.3 / 38.2 / 37.1 s
    27 MB model, 49 b3dm 240 s 243 s 20.3 / 23.2 / 30.7 s 22.6 / 25.9 / 19.5 s

The reader of the split stage (MeshUtils.LoadMesh), which makes the finest level, and the reader of the decimation (ObjMesh) lost or broke parts of valid models that Blender and Assimp write:

- Faces without texture coordinates in a textured model were dropped from the finest level (the coarser levels kept them): a textured model with untextured parts showed only its textured parts up close. They are kept now, with their material and one shared texture coordinate, as the decimation already gives them; the texture repacking keeps the coordinates of a material without texture (they pointed into the replaced list).
- usemtl read only the first word of a material name, and usemtl with more words was ignored, so the faces of a material such as "Paint 1 Carmine" took the previous material. Names now run to the end of the line in usemtl, newmtl, mtllib, g and o (ObjStatement, shared by the OBJ and MTL readers); the MTL reader also accepts a tab after the keyword.
- Vertex colours on some vertices only failed the split ("All vertices must have colors or none"): the others are white, as in the decimation.
- Texture coordinates (or normals) first given after some faces, as by Blender when only the last object is unwrapped, failed the decimation with "Index was out of range": every per-vertex attribute is now kept at the index of its vertex, the earlier vertices getting the default.
- Faces before the first usemtl shifted the material names of the decimation onto the wrong sub-meshes (and failed it with "The number of sub-mesh material names does not match"), as did a usemtl without faces: a sub-mesh and its material are now recorded together. Such faces get the default material at every level instead of the first material of the MTL.
- Texture coordinates without any material made a textured mesh without materials, whose tiles referenced texture coordinates they did not write: the model is untextured.
The GPU formats that Basis Universal textures are transcoded to (BC1-7, ETC, ASTC) are made of 4x4 blocks: KHR_texture_basisu requires the width and height of a KTX2 image to be multiples of 4, and WebGL refuses a BC texture of another size (INVALID_OPERATION), so three.js on desktop GPUs showed such textures black (a 250x250 texture black, 256x256 fine). The encoder now stretches an image of another size to the nearest multiple of 4 (250x250 to 252x252, 249x250 to 248x252) before encoding it. Stretching, not padding, keeps the texture coordinates right, since they are fractions of the image; every mip level of an aligned image is then valid too, as WebGL checks the size of a level shifted back to level 0. Images already aligned are encoded as before.

The quality gate inspector reports a KTX2 image whose size is not a multiple of 4.
…ptions

ModelEdgeCaseQualityTests runs the CLI with --texture-format Ktx2 --ktx2-quality 192 --split-strategy VertexMedian (one tile, and an octree of three levels) on generated models, through the inspector and the official validator: a textured part next to a part without texture coordinates, both with material names with spaces (every level has both materials, the finest with all their triangles); textures of 250x250, 249x250 and 30x2 (KTX2 sizes multiple of 4); objects with and without vertex colours, texture coordinates and usemtl (tiled, with the default material for the faces before the first usemtl at every level); texture coordinates without any material.

QualityDataset.Generated writes such a model (OBJ, MTL, PNG textures of a given size), TilesetInspector.TrianglesByMaterial counts the triangles of each material in a level, and RunValidateAndAssert returns the output path.
@HeDo88TH
HeDo88TH merged commit ec66974 into master Nov 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant