Material files

Modlumi shares materials as .mlmat files. The format is open: anyone may read and write it, and this page is its full specification. To import or export one in the app, see Share materials.

The .mlmat format

A .mlmat file is a zip archive. Its entries may be stored or compressed with Deflate, and their names are UTF-8 with / between folders. It holds:

• material.json, which describes the material.
• The material’s image, if it has one, under the name material.json gives.
• Optionally a small preview image, under the name material.json gives.

A material file needs no other files and readers ignore any it has.

material.json

{
  "format": "modlumi-material",
  "version": 1,
  "id": "red-brick",
  "name": "Red brick",
  "category": "Masonry",
  "tags": ["brick", "wall"],
  "color": [1, 1, 1, 1],
  "image": { "file": "color.jpg", "width": 1.0, "height": 0.75 },
  "thumbnail": "thumbnail.png",
  "credit": {
    "source": "ambientCG",
    "url": "https://ambientcg.com/view?id=Bricks085",
    "authors": [],
    "license": "CC0-1.0",
    "license_url": "https://creativecommons.org/publicdomain/zero/1.0/"
  }
}

Field	Required	Meaning
format	Yes	Always "modlumi-material".
version	Yes	The format version, 1 for this page. A reader refuses newer versions it doesn’t know.
name	Yes	The material’s name as the Materials panel shows it.
id	No	A stable identifier, such as the material’s id in a library.
category	No	A group to show the material in, such as "Wood".
tags	No	Words to search for the material by.
color	No	Red, green, blue and opacity from 0 to 1, in sRGB. Without an image it’s the material’s color; with one it multiplies the image, so [1, 1, 1, 1] shows the image unchanged. Defaults to [1, 1, 1, 1].
image	No	The material’s image: file names its entry in the archive, and width and height give the real-world size in meters that one copy of the image covers, so it repeats at the right scale. PNG, JPEG or BMP, of at most 32 MB.
thumbnail	No	Names a PNG or JPEG entry to preview the material with.
credit	No	Who made the material and on what terms. Every field is optional: source names where it comes from, url links to it, authors lists its makers, license gives an SPDX identifier or name, and license_url links to the license text.

Readers ignore fields they don’t know, so later versions can add fields without breaking older readers.

Modlumi keeps a material’s credit when you paint with it, saves it with the model, and writes it back when you export the material, so the credit travels with every copy.

Material libraries

The Library tab of the Materials panel lists the materials of a library served over HTTPS, Modlumi’s own at https://modlumi.com/api/materials/. A library is a folder of files:

• index.json lists the materials.
• <id>/material.mlmat is each material’s file.
• <id>/thumbnail.jpg is each material’s swatch.

index.json looks like this:

{
  "format": "modlumi-material-library",
  "version": 1,
  "materials": [
    {
      "id": "red-brick",
      "name": "Red brick",
      "category": "Masonry",
      "tags": ["brick", "wall"],
      "credit": { "source": "ambientCG", "license": "CC0-1.0" },
      "sha256": "9f2c…",
      "size": 158213
    }
  ]
}

An id uses lowercase letters, digits, -, _ and ., doesn’t start with a dot or contain .., and is at most 128 characters long. sha256 is the SHA-256 digest of the material’s .mlmat file in lowercase hexadecimal, and size its size in bytes. Modlumi checks every material it downloads against its digest, and a new digest tells it a material changed. Modlumi skips entries it can’t use and ignores fields it doesn’t know.

The desktop app keeps the index and the materials it downloads, so the library still works offline.

Converting SketchUp materials

Modlumi imports SketchUp .skm material files directly: their name, color, opacity, image and real-world image size carry over, and the creator their file names becomes the credit’s author. Other texture maps of physically based .skm materials are skipped. Export the material afterwards to share it as a .mlmat file.

Only convert materials you have the right to share. The materials that ship with SketchUp are licensed for use with SketchUp, not for redistribution.