- PHP 61.4%
- JavaScript 36.5%
- Less 2.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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> |
||
| .phan | ||
| i18n | ||
| modules | ||
| src | ||
| .eslintignore | ||
| .eslintrc.json | ||
| .gitignore | ||
| .gitreview | ||
| .mailmap | ||
| .phpcs.xml | ||
| .stylelintrc.json | ||
| AGENTS.md | ||
| CODE_OF_CONDUCT.md | ||
| composer.json | ||
| CONTRIBUTING.md | ||
| COPYING | ||
| extension.json | ||
| Gruntfile.js | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
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
- Help:Extension:3D — end-user documentation
- Extension:3D — technical 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:
-
Install firejail, e.g. with
apt install firejailon Debian. -
Make MediaWiki use it. It does by default on Linux when it finds firejail (
$wgShellRestrictionMethod = 'autodetect'), but setting it explicitly inLocalSettings.phpmakes MediaWiki fail instead of running commands without a sandbox when firejail is missing:$wgShellRestrictionMethod = 'firejail'; -
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 -
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:
- Code Review via Gerrit: mediawiki/extensions/3D
- Issue tracker via Phabricator: 3D project
- Contributing guidelines: refer to CONTRIBUTING.md
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.