Realistic textile assets generator for Physical AI.

Maillage generates towels, tea towels, napkins, tablecloths, bed sheets, cleaning cloths, bandanas, silk and knitted scarves and flags with real sizes, fabrics, masses and patterns, meshed for cloth simulation and exported to OpenUSD. Every piece is checked in Blender by a drape test: it imports, simulates without exploding, stretches little, does not go through obstacles and comes to rest.

It is built for Physical AI: robots that fold laundry, lay a table or hand over a towel are trained and tested in simulation, and they need many different cloths, not one subdivided square; perception models need synthetic images of crumpled and draped fabric with exact ground truth. Everything can run on CPU. Maillage is the sister project of Granulaire (granular assets) and follows the same approach: distributions instead of one shape, measured outputs, honest limits.

Waffle-cotton tea towels generated by Maillage (solid, gingham, striped), imported into Blender and draped by the drape test. Render: maillage drop-test output/tea_towel --render.

What it does

• Generates N distinct pieces of a preset (12 by default): format drawn from real retail sizes, size tolerance, corner rounding, an imperfect cut (wavy edges, slight skew), fabric and pattern.
• Meshes each piece for cloth solvers: near-equilateral triangles for any outline (rounded corners, round tablecloths), or a structured quad grid for rectangles (the topology of a woven fabric).
• Draws a procedural pattern (solid, end bands, stripes along or across, gingham, border, flag bands) as a PNG texture that follows the fabric, not the cut.
• Measures every mesh (area, perimeter, edge lengths, minimum angles) and derives the mass from the fabric's areal density.
• Exports an OpenUSD scene: meshes with UVs, a textured UsdPreviewSurface material, hem and pin primvars, and the fabric's physical properties as custom attributes.
• Tests every piece in Blender (maillage drop-test): import, cloth simulation, automatic checks, Cusick drape coefficient, the draped meshes exported back to OpenUSD and an optional Cycles render.

Installation

From PyPI:

pip install "maillage[render]"

From a clone, for development:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[render]"        # add ",dev" for tests and linting

Requires Python 3.10+. For the Blender drape test, either put Blender on the PATH, or install Blender as a Python module (pip install -e ".[blender]", Python 3.13 only, as the bpy wheels exist for one Python version). Tested with Blender 5.2; Blender 4.2 or later should work.

Usage

maillage list
maillage generate --preset tea_towel                     # 12 pieces, triangles
maillage generate --preset tablecloth --count 20 --seed 3
maillage generate --preset bath_towel --topology grid --vertices 2500
maillage generate --preset napkin --fabric silk --no-cut --no-color
maillage generate --preset tablecloth --format "140x180@2,round:150,oval:140x220"
maillage preview output/tea_towel                        # flat sheet (matplotlib)
maillage drop-test output/tea_towel --pieces 4 --render  # Blender drape test
maillage drop-test output/tea_towel --gif                # + animated GIF (Pillow)
maillage drop-test output/flag --wind 4 --render         # flags hang from a pole

python -m maillage ... works too. Without the bpy module or blender on the PATH, maillage drop-test prints the command to run with your Blender:

blender -b -P "$(maillage blender-script)" -- output/tea_towel --render

The script does not import Maillage, so Blender's own Python needs nothing installed. From Python:

from maillage import Variations, generate_scene, write_outputs

towels = generate_scene("tea_towel", count=12, seed=1)
write_outputs(towels, "output")  # -> output/tea_towel/

# 40 cm linen squares with a perfect cut, 2,000 vertices each, quad grid
napkins = generate_scene(
    "napkin",
    count=6,
    fabric="linen",
    topology="grid",
    vertices=2000,
    variations=Variations(cut=False),
)
write_outputs(napkins, "output")

# tablecloths in your own sizes: a 140×180 rectangle twice as often as the rest
tablecloths = generate_scene("tablecloth", count=12, formats="140x180@2, round:150, oval:140x220")
write_outputs(tablecloths, "output")

Presets

One piece of each preset (seed 2), simulated 5 s by the Blender drape test and rendered with Cycles; each image is framed on its own piece, so scales differ (30 cm washcloth to 3 m sheet). Same colours for the three terry presets: they share a palette and, with one seed, the same colour draw.

Sizes are common retail formats; values are realistic orders of magnitude, not measurements of a specific product. Flags use generic two or three band designs with random colours on unequal, asymmetric bands, so that real national flags (equal or symmetric bands) are unlikely.

Fabrics

--fabric gives every piece the same fabric, whatever the preset's mix.

Formats

Each preset draws from its own retail formats (table above). --format (Python: formats=) replaces them with your sizes and shapes, in cm, as a comma-separated list:

Weights. Each piece draws one format at random, with a probability proportional to its weight: weight / sum of the weights. With --format "140x180@2,round:150,oval:140x220" the weights are 2, 1 and 1 (sum 4), so each tablecloth has a 50 % chance of being 140×180, 25 % of being round and 25 % of being oval: about 6, 3 and 3 out of 12 on average, the exact counts depending on the seed. Only the ratios matter (@2, @1, @1 is the same as @50, @25, @25), and without any @ all formats are equally likely. With --no-size, nothing is drawn: every piece takes the first format of the list, at its exact size. The presets' own formats use the same weights (a bath_towel is 70×140 with weight 0.7, 90×150 with weight 0.3).

The longer side is always the length, so 70x50 is the same as 50x70. The preset's size tolerance, cut, corners, fabric and patterns still apply. In Python, a format can also be a dict ({"width": 50, "length": 70, "shape": "rect", "weight": 1}) or a tuple ((50, 70), (150, 150, "round")). With --topology grid, round and oval formats are skipped (at least one rectangle is needed). summary.json counts the pieces of each format drawn.

Variations

Each aspect has its own random stream: turning one off leaves the others unchanged (same shapes with plain colours, same colours with a perfect cut…).

Mesh

maillage preview output/tea_towel on a grid-topology set: the texture is drawn over each piece and the mesh shown on top; the wavy grid lines are the imperfect cut, spread across the piece.

Outputs (per preset, under output/<preset>/)

OpenUSD layout

Z up, metres, kilograms. /World is the default prim.

/World
  /Looks/<piece>      UsdPreviewSurface + UsdUVTexture (textures/<piece>.png)
  /Cloths/<piece>     UsdGeom.Mesh, flat on the ground, laid out in rows
  /Ground             collision ground (UsdPhysics.CollisionAPI)

Each cloth mesh has subdivisionScheme = none, is double sided, and carries:

OpenUSD has no standard schema for cloth simulation (UsdPhysics covers rigid bodies and joints), so these properties are custom attributes. Blender's USD importer reads the geometry, UVs, material, texture and the hem and pin primvars (as mesh attributes); the drape test reads the maillage:* attributes with the OpenUSD bindings shipped with Blender.

Blender drape test

maillage drop-test imports the scene into Blender and, for each tested piece:

1. sets up Blender's cloth solver from the maillage:* attributes: stiffness rescaled to the mesh and the piece's real mass, stiffer bending on the hem, collisions and self-collisions;
2. drape: lays the piece flat on a round pedestal (diameter 60 % of the shorter side), its centre clamped as between the two discs of a Cusick drape tester, and lets the rest fall; hang: a flag hangs from its two hoist corners on a pole, optionally in the wind;
3. simulates 5 s (120 frames at 24 fps);
4. checks the result and writes drop_test.json:

It also measures the drape coefficient of each draped piece, as in the Cusick test: (projected area − pedestal area) / (flat area − pedestal area), from 1 (stays flat) to 0 (hangs straight down). The draped meshes are exported to draped.usdc with their maillage:* attributes copied back: ready-to-use draped assets.

Results

Indicative results of maillage drop-test on three pieces of each preset (seed 1, ~1,500 vertices per piece, 120 frames, Blender 5.2):

No piece went through the pedestal or the floor. The drape coefficient depends on the shape of the piece as much as on the fabric (a long towel hangs further past a pedestal sized on its short side), so it compares pieces of one preset, not presets with each other. To compare fabrics, the same 40 cm square was draped in each (maillage generate --preset napkin --no-size --no-cut --fabric silk,polyester_knit,cotton_plain,linen,cotton_terry,denim):

In this version the fabrics differ in mass, thickness, friction and look much more than in drape: the drape coefficients stay within 0.35–0.42, where real silk and denim are far apart (see the roadmap).

Silk, plain cotton, linen and denim squares falling onto the clamped pedestals, slowed down twice: maillage generate --preset napkin --count 4 --fabric silk,cotton_plain,linen,denim then maillage drop-test output/napkin --frames 40 --gif --gif-step 1.

Flags hung by their hoist corners in the wind: maillage drop-test output/flag --wind 4 --gif.

Blender values

Blender's cloth stiffness acts per edge and is not divided by the vertex mass, so the same numbers make a fabric stiffer or softer depending on the mesh resolution. Maillage stores the stiffness for a reference mesh with 1 cm edges and the real mass, and the drape test rescales it: tension and shear with the edge length, bending unchanged, air damping with the area per vertex. The solver itself runs with Blender's usual 0.3 kg vertex mass and every stiffness and damping multiplied by the same factor, which leaves the motion unchanged and keeps Blender's solver in the range its tolerances are tuned for.

Tension gives about 3 % stretch when a piece drapes; bending is smaller for softer fabrics, and kept low for all of them (see the roadmap). The values are not calibrated against measured fabric properties.

Method in brief

1. Outline. A rectangle with rounded corners or an ellipse, parametrised by arc length. The cut adds a smooth normal displacement (sum of a few sines along the perimeter: long gentle deviations plus a small wobble) and a slight shear.
2. Mesh. tri: the outline is sampled at the target edge length (sharp corners kept, roundings below the resolution merged into one vertex), the inside filled with a jittered hexagonal lattice kept at least half an edge away from the outline, then a Delaunay triangulation clipped to the outline. grid: transfinite (Coons) interpolation of the four cut edges.
3. Fabric and mass. The fabric is drawn from the preset's mix; the mass is the measured area times the areal density.
4. Hem and pins. Vertices within the hem width of the outline get hem = 1; for flags, vertices near the two hoist corners get pin = 1.
5. Pattern. Parameters drawn per piece (colours from the preset's palettes, periods, band widths), rendered on the nominal rectangle with a faint weave noise; texture coordinates follow the fabric, so a skewed or wavy cut shows as a pattern not quite parallel to the edge, as on real pieces.

Limits

• Blender only, so far. The drape test validates the assets in Blender's cloth solver. Nothing is exported yet for NVIDIA OmniPhysics deformables (Isaac Sim) or MuJoCo flex; the geometry and physical attributes are there, the engine-specific schemas are not.
• Fabrics drape alike. Bending stiffness is kept low for every fabric (see the roadmap), and no value is calibrated against measurements (no Kawabata or Cusick data behind them).
• Flat pieces only. No garments (sewn panels), no holes or grommets (a flag is pinned at its hoist corners instead), no folded or crumpled starting states, no wet cloth.
• Textures are procedural. Patterns are clean and regular; no prints, logos, stains or wear.

Roadmap

1. Stiff fabrics that drape like real ones. Blender's angular bending model (the only one that works on triangle meshes) becomes unstable when the bending stiffness is high relative to the vertex mass, as with stiff fabrics on fine meshes: instead of settling, the cloth keeps vibrating, and adding damping makes it worse. Every fabric's bending stiffness is therefore kept below this limit (about 0.015 × areal density for 1 cm edges, measured), so a 40 cm square drapes with a coefficient of 0.35–0.42 whether it is silk or denim. Next steps: more solver steps or a coarser simulation mesh for stiff fabrics, quad-grid meshes with Blender's linear bending model, and other engines.
2. Pre-draped and crumpled states as OpenUSD variants (the drape test already exports draped meshes), and folded states for laundry-folding tasks.
3. Engine-neutral physical stiffness (tensile and bending rigidity in SI units) with per-engine mappings, starting with OmniPhysics surface deformables.
4. Calibration against published fabric measurements.
5. Simple garments from sewing patterns.

Development

The project follows GitHub Flow:

1. main is always releasable and protected: changes reach it only through pull requests, nobody pushes to it directly.
2. Every change starts on a short-lived branch from main, named after its type: feat/<name>, fix/<name>, docs/<name>, ci/<name>, …
3. Push the branch and open a pull request into main; CI runs on it.
4. Merge when CI is green, then delete the branch.

Releasing is a change like any other: on a chore/release-X.Y.Z branch, bump version in pyproject.toml and move the Unreleased entries of CHANGELOG.md under the new version; merge the pull request, then tag vX.Y.Z on main (or create the release on the GitHub web page with that new tag). The release workflow builds the packages and attaches them.

A versioned pre-push hook refuses direct pushes to main. Enable it once per clone with git config core.hooksPath .githooks (emergency override: ALLOW_MAIN_PUSH=1 git push).

Continuous integration

GitHub Actions runs these workflows (.github/workflows/):

Ruff is pinned in CI so that a new ruff release cannot fail the build on unchanged code; update the pin and run ruff format . together.

License

MIT © 2026 Daniel Régis Sarmento Caon

The logo is set in IBM Plex Sans (SIL Open Font License 1.1), outlined into paths, so it displays without the font installed.

Maillage is part of Primvaria, physics-ready variability for Physical AI, in OpenUSD: pip install primvaria installs the whole suite.