Jump to content

Commons:Textured 3D

From Wikimedia Commons, the free media repository
Tracked in Phabricator
Task T246901

Wikimedia Commons currently only supports colorless, untextured 3D models, which only show the basic geometric shape of objects. This page tracks the progress towards adding support for 3D formats capable of full-color, textured 3D models — i.e. where images of the surface appearance are overlaid onto the 3D shapes to provide a more realistic and detailed appearance. This page also contains a list of resources and links to get involved, as well as some example 3D models that would fit on Commons once such support is in place.

3D models have been supported in Wikimedia Commons since 2018, but only the STL format can be used at the moment. STL is a format designed for 3D printing that does not support textures, color, and more nuanced digital representation.

Motivation

[edit]

The current issues surrounding Sketchfab show how important a non-commercial platform for sharing and visualising textured 3D models would be: thus there is significant urgency due to current developments. Tens of thousands of 3D models under free licences are under threat, and in a petition to Sketchfab it is said that "this is the virtual equivalent of burning the Library of Alexandria". Here is a petition with lots of background information.

Technical progress

[edit]

Discussions

[edit]

Technical realisation

[edit]

Formats

[edit]

There are several open standards for textured 3D models. Concrete wishes for integration exist for the following formats:

These formats have different purposes, summarized well in Last-mile vs. Interchange. The guide was written for an audience from the animation or game development industries, where "last-mile" means the input to an offline rendering or game build pipeline (as opposed to the input one of the many tools used to create and refine that 3D asset). For the Commons — publishing lightweight interactive illustrations on the web — it's necessary to further restrict that "last-mile" definition to formats suitable as inputs to a web page or mobile app, on a consumer laptop or mobile phone. Consider file size: does the format support compression? And parsing complexity: does the format require a large SDK?

The glTF (Graphics Library Transmission Format) file format is an open standard for textured three-dimensional scenes and models (ISO/IEC 12113:2022). The extension .glb is the binary version of this format. Work has already been carried out for this format to extend the MediaWiki Extension:3D. Among candidate formats, the glTF format is unique in supporting the types of compression and optimization that would be important for efficiently publishing 3D models on the web. However, just because a file is in a particular format does not guarantee that any optimizations have been applied, and data pre-processing (see below) must still be considered even if the source file is in a "last-mile" format.

Libraries like Sketchfab accept uploads of 3D models in many formats, automatically convert the source model to several common formats users can choose for purchase/download, and additionally convert the model to a closely-managed proprietary format, optimized for loading and rendering in Sketchfab's own infrastructure. The source model (which could be in a much less efficient format, such as OBJ) is not downloaded by users viewing the webpage; it is only downloaded if the user explicitly chooses to download the model as a file, and selects .obj as their preferred format. As of this writing, Commons uses the three.js rendering library for 3D model rendering, which recommends the glTF file format where possible.

In general, conversion between any two "standard" formats is likely to be lossy; material/appearance representations in different formats may vary widely. For geometry there may be some difference in internal structure (triangles vs. quads and n-gons) but the visual appearance would look the same to a viewer.

As a first implementation, support should be added for a single last-mile format, such as glTF. Data pre-processing should be included, to verify that the model is valid and has been optimized by the uploader within some reasonable limits. Later, support for uploading in more interchange or antique formats could be added, potentially by automatically converting to and optimizing a derived last-mile asset.

Data preprocessing

[edit]
  • model orientation (which direction is up, forward)
    • GLB: should be Y-Up
    • STL: not defined, but most models in WikiMedia are Z-Up, that's why we should stick with it
  • file size
  • performance
  • materials, textures, lighting, and appearance
  • maybe here? https://commons.wikimedia.org/wiki/Commons:3D_models
  • Real-time Asset Creation Guidelines from the KhronosGroup https://github.com/KhronosGroup/3DC-Asset-Creation/blob/main/asset-creation-guidelines/RealtimeAssetCreationGuidelines.md
    • File Size: Ideally less than 5MB. Note that as glTF geometry and texture compression extensions, such as glTF Universal Textures using the KTX container and geometry compression using Draco, on the glTF roadmap become widely available, smaller assets or more visual fidelity at the same asset size will be possible.
    • Draw calls: should be minimized by consolidating meshes, and using fewer materials.
    • Triangle Count: 100,000 triangles or less.
    • Texture Aspect Ratio: use power of 2 resolutions, square aspect ratio is not required.
    • Texture Size: Use 1024*1024 (1K) or 2048*2048 (2K) for BaseColor, ORM and Emissive maps. 2K is recommended for Normal maps which are more sensitive to reduced resolutions than even Albedo maps. Normals Maps are also severely sensitive to JPG artifacts - a 2K JPG giving the same quality as same as 1K PNG normal map.
  • Tool for Downsampling: https://gltf-transform.dev/

Technical realisation - status quo - STL

[edit]

Only STL files are supported - no textured 3D models.

There are two main components for 3D in MediaWiki:

Both components are based on outdated versions of three.js (v88). Preliminary considerations for the update: Three.js v163 removed support for WebGL 1, but 3d2png depends on headless-gl, which only supports WebGL 1. For consistency we should stick with three.js v162.

  • The Patch of current Extension 3D on base of three.js 162, only for STL is now online (4/2025)
  • Patch for current 3D2PNG Thumbnailer on base of three.js 162, only for STL: https://gerrit.wikimedia.org/r/c/3d2png/+/1114772
    • No merge by MediaWiki yet
    • Light system does not work properly, because RoomEnvironment does not work with headless GL. We created a version that tries to simulate RoomEnvironment with a classic lighting system.

Technical realisation - GLB support - 3D Viewer - Status of the work

[edit]
  • Update Extension 3D with GLB, base on three.js 162
  • Alternative 3D Viewers
    • modelviewer.dev - https://modelviewer.dev/
      • Pros:
        • widely used
        • lightweight
        • actively supported and updated
      • Cons:
        • No STL Support
    • Babylon Viewer - https://viewer.babylonjs.com/
      • Pros:
        • supports glTF, obj, stl, splat, and spz
        • lazy loads features (model formats, animation system, audio system, etc.)
        • highly customizable
        • supports WebGPU for improved performance
        • can be used in native code (e.g. server side thumbnail generation)
        • actively supported and updated
      • Cons:
        • very new, currently much smaller usage compared to Model Viewer
        • about 50% larger download size compared to Model Viewer (~450kb gzipped vs. ~300kb gzipped)


Technical realisation - GLB support -thumbnail generator - Status of the work

  • Update 3D2PNG thumbnail generator with GLB, base on three.js 162
    • Basic GLB Support - https://github.com/OpenDEM/3D2PNG_GLB_Support
    • Only very basis support. Many things don't work out of the box with headless gl.
    • The images of the textures were extracted here and later used as DataTexture. There are probably better ways.
    • A lot of Todos
    • At the meeting of the textured 3D group on 23.2.2025 we decided not to pursue this path further, as there is no plan to support WebGL2 with headless-gl.
  • Alternative thumbnail generators
    • General MediaWiki requirements:
      • Both program and libraries open source.
      • Libraries actively maintained or not major maintenance to be required
      • Run into a sandbox for security
      • Security review by our security team will be required
      • Totally standalone (drop it in a directory and sandbox it) or we need to be able to package it for Debian to install locally. Docker services are probably acceptable.
      • Most likely these will be running with mesa's software renderer, not via a native gpu, in the kubernetes cluster.
    • Filament https://github.com/google/filament
    • Puppeteer.js https://pptr.dev/
      • Pros:
        • Widely used headless instance of Chromium for rendering 3D snapshots (three.js, https://github.com/Shopify/screenshot-glb, https://www.flowkit.app/glb2png)
        • Prototypical example already available in a MediaWiki test environment
        • Works exactly as the browser (also in headless mode?)
        • Contact to people who can help us set up a stable system (three.js, flowkit.app)
      • Cons:
        • high memory usage
        • The consumption of resources could lead to problems, which is why a load balancer and download queues are necessary. And someone has to take care of it.
    • WGPU library https://wgpu.rs/
    • f3d-app: https://github.com/f3d-app/f3d - C++
    • Babylon Native: https://www.babylonjs.com/native/
      • Pros:
        • Babylon Native + Babylon Viewer render output will exactly match Babylon.js + Babylon Viewer in the browser (render pipeline, glTF loader, glTF extensions, camera framing, etc.)
        • Low memory usage
        • Cross platform (Windows, Linux, MacOS, iOS, Android)
        • Actively supported and updated
      • Cons:


Technical realization - Update mime.info - Status of the work

Test data GLB files for testing:

Future Requirements Viewer/Thumbnail generator

[edit]
  • Security concerns: The three.js version could be upgraded past v162 after either
    • headless-gl supports WebGL 2
    • three.js WebGPU support is stable and a stable Node.js WebGPU implementation exists.
  • It'd be good to rotate the camera around the object, instead of rotating the object itself. The current behaviour is unintuitive GitHub Issue.
  • Support of Gaussian splatting (.splat) https://en.wikipedia.org/wiki/Gaussian_splatting
  • Support of optimized 3D models for the web and download of the original models in full resolution. Large models can cause the browser to crash.

Content to better integrate in this article:

[edit]
Without textures polygons are visible and things hard to discern
How it would look like with colored textures

Featuring 3D renderings of notable objects and places offers great opportunities for improving Wikipedia articles by making them both more engaging for readers whilst also helping them better comprehend the subject.

Support for featuring 3D renderings of objects has become increasingly common and better supported on the internet generally; however this support is not currently matched on Wikimedia Commons thereby limiting Wikipedia's ability to feature 3D objects.

As stated in a blog post on the publication of the original basic 3D support in Commons (source below):

In the future, after feedback from our community of volunteer editors, we’ll consider adding support for even more complex file types that support features like textures.

The time to add support for these features is now. Most modern smartphones are able to create 3D-Scans of smaller objects or even complete buildings rights now and there is no way to upload and display them in Wikimedia projects! There are several large sources of free textured 3D models.

Possible use cases of colorful, interactive and complex 3d models in Wikipedia articles:

  • models of extinct species like dinosaur reconstructions
  • the inside of historical rooms (example)
  • all kinds of smaller interesting objects
This is great, but pretty boring. We need color! ;)

Resources:

Wikimania poster and meetup

[edit]
Poster by Discott that will be displayed at Wikimania 2023.
WMF C-Levels and other staff talking about how to best action 3D support on Wikipedia.

I have a number of photogrametric 3D models on Commons, all of which would benefit from texturing: even in simple cases, texturing gives indications of materials (is a statue made of bronze, marble, clay...?), and conveys verisimilitude through little details such as weathering or ambient occlusion.

No indication of material, and scarcety of details
  • Terracotta object renders like clay
    Terracotta object renders like clay
  • Plaster object renders like clay
    Plaster object renders like clay
  • Marble object renders like clay
    Marble object renders like clay

More importantly, some models suffer greatly from being only clay models: for instance polychrome archaeological artefacts are improperly represented by clay models.

polychrome archaeological artefact improperly represented by an untextured models
  • polychrome archaeological artefact improperly represented by an untextured model: 3D clay model gives volumes but misrepresents colours
    polychrome archaeological artefact improperly represented by an untextured model: 3D clay model gives volumes but misrepresents colours
  • polychrome archaeological artefact improperly represented by an untextured model: photograph gives colours but not volumes
    polychrome archaeological artefact improperly represented by an untextured model: photograph gives colours but not volumes
  • Model looks damaged (nose)
    Model looks damaged (nose)
  • Texture gives information that the damage is on the object rather than on the 3D model.
    Texture gives information that the damage is on the object rather than on the 3D model.

Finally, on the technical side, not having textures forces us to upload high polygon models. The possibility to embed bump maps and displacement maps would allow conveying the same amount of detail with much smaller models (one order of magnitude fewer polygons at least).

Meetings of the Textured 3D Group

[edit]

Meetings

[edit]
Retrieved from "https://commons.wikimedia.org/w/index.php?title=Commons:Textured_3D&oldid=1020117909"