Vibecoded fork of https://www.mediawiki.org/wiki/Extension:3D with a bunch of bullshit stapled on top to get it working for Bitlair
  • PHP 61.4%
  • JavaScript 36.5%
  • Less 2.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Polyfloyd 6fa5cc0373 Read the unit of 3MF files
assimp ignores the unit of 3MF files, so models in centimetres or inches
were shown with the wrong size. Read it from the model part with the zip
extension, and scale the measured size by it. Without the extension, the
size is that in millimetres, the default unit of 3MF, as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 16:57:28 +02:00
.phan build: Remove unneeded suppression of PhanParamSignatureMismatch 2024-02-23 22:40:02 +01:00
i18n Show a message when the viewer can not load a model 2026-10-16 15:52:48 +02:00
modules Show a message when the viewer can not load a model 2026-10-16 15:52:48 +02:00
src Read the unit of 3MF files 2026-10-16 16:57:28 +02:00
.eslintignore Add foreign-resources.cdx.json 2025-09-26 16:48:13 +08:00
.eslintrc.json build: Update linters, fix and improve configs 2023-12-04 17:43:59 +00:00
.gitignore build: Updating mediawiki/mediawiki-phan-config to 0.15.1 2025-01-12 00:34:25 +00:00
.gitreview .gitreview: Swap to track=1 2023-09-08 20:42:35 +01:00
.mailmap Update name and address for bvibber 2026-05-27 16:41:46 -07:00
.phpcs.xml build: Updating mediawiki/mediawiki-codesniffer to 32.0.0 2020-10-28 19:23:37 +00:00
.stylelintrc.json build: Update linters, fix and improve configs 2023-12-04 17:43:59 +00:00
AGENTS.md Read the unit of 3MF files 2026-10-16 16:57:28 +02:00
CODE_OF_CONDUCT.md build: Updating mediawiki/phan-taint-check-plugin to 1.4.0 2018-09-01 05:29:39 +00:00
composer.json build: Updating nanoid to 3.3.18 2026-08-08 12:13:37 +00:00
CONTRIBUTING.md 3D: Add README.md 2026-09-18 01:12:36 +00:00
COPYING Consolidate licenses, add COPYING 2017-05-31 14:36:25 -05:00
extension.json Show a message when the viewer can not load a model 2026-10-16 15:52:48 +02:00
Gruntfile.js update three.js r162 2025-04-10 09:33:20 -07:00
package-lock.json build: Updating source-map-js to 1.2.2 2026-10-06 12:32:20 +00:00
package.json build: Updating stylelint-config-wikimedia to 0.19.4 2026-09-15 07:12:43 +00:00
README.md Read the unit of 3MF files 2026-10-16 16:57:28 +02:00

3D (f3d fork)

Warning

This is a fork of the 3D extension, made for Bitlair's wiki. It is fully slopcoded: the changes were written by an AI agent. Do not expect any kind of support whatsoever. Use it at your own risk, and do not report problems with it to the upstream project.

Compared to upstream, this fork:

  • renders thumbnails with f3d instead of the Node.js program 3d2png, with a transparent background;
  • caps the resolution at which thumbnails are rendered, so that large thumbnails no longer take gigabytes of memory and get the web server killed by the OOM killer;
  • makes the color of models configurable, in thumbnails and in the interactive viewer;
  • supports OBJ, 3MF, OpenSCAD and SolveSpace files next to STL, in thumbnails and in the interactive viewer;
  • shows the size of models in millimetres on file pages, instead of a meaningless size in pixels.

The main branch follows upstream master (MediaWiki 1.47 and later), and the REL1_43 branch follows upstream REL1_43.

The 3D extension enables MediaWiki to upload, generate thumbnails for, and interactively view 3D models.

It supports the STL (application/sla), OBJ (model/obj), 3MF (model/3mf), OpenSCAD (application/x-openscad) and SolveSpace (application/x-solvespace) file formats, which are common in 3D printing. Thumbnails are rendered with f3d. Interactive viewing (pan, zoom, rotate) is available when Extension:MultimediaViewer is installed.

Documentation

Installation

Refer to the Extension:3D page for installation instructions, including enabling STL uploads and associating STL files with MultimediaViewer. OBJ, 3MF, OpenSCAD and SolveSpace files are set up the same way:

$wgFileExtensions[] = 'obj';
$wgFileExtensions[] = '3mf';
$wgFileExtensions[] = 'scad';
$wgFileExtensions[] = 'slvs';
$wgMediaViewerExtensions['obj'] = 'mmv.3d';
$wgMediaViewerExtensions['3mf'] = 'mmv.3d';
$wgMediaViewerExtensions['scad'] = 'mmv.3d';
$wgMediaViewerExtensions['slvs'] = 'mmv.3d';

Thumbnails are rendered with f3d instead of the 3d2png program described there. On Debian, install the renderer with:

apt install f3d xvfb xauth assimp-utils openscad solvespace firejail php-zip

firejail is not needed to render models, but do install it: see Sandboxing. PHP's zip extension (php-zip) reads the unit of 3MF files; restart PHP after installing it.

assimp converts OBJ and 3MF files to STL before they are rendered. OpenSCAD and solvespace-cli convert OpenSCAD and SolveSpace files to STL, both for thumbnails and for the interactive viewer, which loads the converted model as the stl-<name>.stl thumbnail of the file. The API returns its URL for iiurlparam=stl. For SolveSpace files, the solids of the group that was active when the file was saved are shown. Linked files are not looked up between the uploaded files, so SolveSpace files that link other files fail to render.

Models are measured when they are uploaded, which also converts formats other than STL. After upgrading from a version that did not measure them, measure the existing files with:

for mime in application/sla model/obj model/3mf application/x-openscad application/x-solvespace; do
	php maintenance/run.php refreshImageMetadata --force --mime=$mime
done

Sizes are shown in millimetres, the convention in 3D printing. STL, OBJ and OpenSCAD files have no unit, so their coordinates are taken to be millimetres. 3MF files do have a unit, which is read with PHP's zip extension. Without the extension, 3MF files are taken to be in millimetres as well, their default unit. After installing the extension or upgrading from a version that did not read the unit, measure the existing 3MF files again with:

php maintenance/run.php refreshImageMetadata --force --mime=model/3mf

Sandboxing

OpenSCAD files are programs. Anyone who can upload them can make the server spend CPU time and memory up to the limits of $wgMaxShellTime, $wgMaxShellWallClockTime and $wg3dRenderMemory, and can make OpenSCAD read files on the server with include, import() and surface(). SolveSpace files can likewise link to models on the server by their absolute path. Only the resulting model ends up in the thumbnail, but that is enough to copy another model, such as a deleted upload. Without a sandbox, the renderers can even read LocalSettings.php.

So run the renderers in firejail, on any wiki where people can upload files:

  1. Install firejail, e.g. with apt install firejail on Debian.

  2. Make MediaWiki use it. It does by default on Linux when it finds firejail ($wgShellRestrictionMethod = 'autodetect'), but setting it explicitly in LocalSettings.php makes MediaWiki fail instead of running commands without a sandbox when firejail is missing:

    $wgShellRestrictionMethod = 'firejail';
    
  3. Hide the files on the server that should stay private but are readable by the web server's user, such as backups, in /etc/firejail/mediawiki.local, which MediaWiki's firejail profile includes:

    blacklist /var/backups
    
  4. Purge a 3D file and check that its thumbnail is rendered.

The renderers then run with MediaWiki's default restrictions and without network access, and can not see MediaWiki's directory, the uploads, or the rest of the temporary directory, such as /tmp. Other files stay readable to them, hence step 3.

firejail does not sandbox anything when it finds itself in a container, such as Docker. It then runs commands without any restrictions, and MediaWiki does not notice, as it hides firejail's warnings.

Configuration

Configuration is documented on the Extension:3D page, with the following differences:

Setting Default Description
$wg3dF3dCommand ['xvfb-run', '--auto-servernum', '--server-args=-screen 0 1920x1080x24', 'f3d'] Command used to run f3d. Replaces $wg3dProcessor.
$wg3dAssimpCommand 'assimp' Command used to convert OBJ and 3MF files to STL before rendering. Set to false to let f3d render them directly, which uses the colors stored in the model.
$wg3dOpenScadCommand 'openscad' Command used to convert OpenSCAD files to STL.
$wg3dSolveSpaceCommand 'solvespace-cli' Command used to convert SolveSpace files to STL.
$wg3dRenderMemory 3145728 (3 GiB) Memory limit of the renderer, in KiB. Replaces $wgMax3d2pngMemory. Only enforced when $wgShellCgroup or firejail is used.
$wg3dModelColor '#f0ebe8' Color of 3D models, as a hex color. Existing thumbnails keep their old color until their file is purged.
$wg3dMaxRenderWidth 2048 Maximum width at which thumbnails are rendered. Larger thumbnails are scaled up by the browser.
$wg3dProcessEnviron [] Extra environment variables for the renderer.

Development

This fork has no issue tracker or review process. The upstream extension is developed here:

Notes for working on this fork are in AGENTS.md.

Testing

From the extension directory, run:

composer test
grunt test

composer test runs the PHP linting and coding style checks. grunt test runs ESLint and Stylelint to lint JavaScript and CSS/Less files for code style and errors.