Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
# SculptForge - Blender bridge: the add-on's exchange code (no Blender needed, only numpy)
# SPDX-License-Identifier: GPL-3.0-or-later
#
# python3 tests/blender/test_exchange.py [--cli path/to/sculptforge-cli]
#
# With --cli, meshes written the way the add-on writes them go through SculptForge (blender_receive, then
# blender_send) and must come back identical: positions, faces and their winding, UVs, vertex paint, mask and
# face groups, for objects with a rotation, a scale, a negative scale (mirrored) and n-gons. CMake runs this
# when it finds Python 3 with numpy (ctest -R blender_exchange).
import argparse
import os
import subprocess
import sys
import tempfile
import numpy as np
# exchange.py alone: the package's __init__ needs bpy.
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "addons", "blender", "sculptforge_bridge"))
import exchange # noqa: E402
N = exchange.NO_INDEX
failures = []
def check(cond, what):
if not cond:
failures.append(what)
print("FAIL:", what)
# ---------------------------------------------------------------------------- a Blender-like mesh
def grid_with_ngon():
"""A 3x3 grid of quads (z = bumpy), a pentagon and a triangle hanging off it, as Blender stores
polygons: vertex positions, loop_start / loop_total and the loops' vertices."""
co = []
for j in range(4):
for i in range(4):
co.append((i * 0.5, j * 0.5, 0.1 * np.sin(i + 2 * j)))
polys = []
for j in range(3):
for i in range(3):
a = j * 4 + i
polys.append([a, a + 1, a + 5, a + 4])
base = len(co)
co += [(2.0, 0.0, 0.2), (2.4, 0.6, 0.3), (2.1, 1.2, 0.25)]
polys.append([3, base, base + 1, base + 2, 7]) # pentagon on the grid's right edge
polys.append([7, base + 2, 11]) # a triangle
starts, totals, loop_vert = [], [], []
for p in polys:
starts.append(len(loop_vert))
totals.append(len(p))
loop_vert += p
return np.array(co), np.array(starts), np.array(totals), np.array(loop_vert)
def only_ngons():
"""A hexagon and two triangles: a mesh with no quads at all (SculptForge must not pair its fans)."""
co = [(np.cos(a), np.sin(a), 0.0) for a in np.linspace(0, 2 * np.pi, 7)[:-1]] + [(0.0, 0.0, 1.0), (1.5, 0.0, 0.5)]
polys = [[0, 1, 2, 3, 4, 5], [0, 6, 1], [5, 7, 0]]
starts, totals, loop_vert = [], [], []
for p in polys:
starts.append(len(loop_vert))
totals.append(len(p))
loop_vert += p
return np.array(co), np.array(starts), np.array(totals), np.array(loop_vert)
def rotation(axis, degrees):
a = np.radians(degrees)
c, s = np.cos(a), np.sin(a)
x, y, z = np.asarray(axis, float) / np.linalg.norm(axis)
return np.array([[c + x * x * (1 - c), x * y * (1 - c) - z * s, x * z * (1 - c) + y * s],
[y * x * (1 - c) + z * s, c + y * y * (1 - c), y * z * (1 - c) - x * s],
[z * x * (1 - c) - y * s, z * y * (1 - c) + x * s, c + z * z * (1 - c)]])
def matrix(rot, scale, translate):
m = np.eye(4)
m[:3, :3] = rot @ np.diag(scale)
m[:3, 3] = translate
return m
def object_arrays(mesh, mirrored, seed):
co, starts, totals, loop_vert = mesh
rng = np.random.default_rng(seed)
loops, face_poly = exchange.polygon_corners(starts, totals, mirrored)
faces = exchange.faces_from_loops(loops, loop_vert)
# Values that survive the file exactly: UVs in float32, colours in bytes, mask in 1/65535 steps.
loop_uv = rng.random((len(loop_vert), 2)).astype(np.float32).astype(np.float64)
colors = rng.integers(0, 256, (len(co), 3)) / 255.0
mask = rng.integers(0, 65536, len(co)) / 65535.0
facegroups = rng.integers(0, 5, len(starts))
return {"positions": co, "faces": faces, "uvs": loop_uv[np.maximum(loops, 0)], "colors": colors,
"mask": mask, "groups": facegroups[face_poly]}, loops
# ---------------------------------------------------------------------------- unit tests
def test_polygon_corners():
co, starts, totals, loop_vert = grid_with_ngon()
loops, face_poly = exchange.polygon_corners(starts, totals)
check(len(loops) == 9 + 3 + 1, "9 quads, a pentagon as 3 triangles, 1 triangle")
check(list(loops[9]) == [36, 37, 38, -1] and list(loops[10]) == [36, 38, 39, -1] and list(loops[11]) == [36, 39, 40, -1],
"pentagon fan (0, i, i+1)")
check(list(face_poly[9:13]) == [9, 9, 9, 10], "fan faces point at their polygon")
m, _ = exchange.polygon_corners(starts, totals, mirrored=True)
check(list(m[0]) == [0, 3, 2, 1], "mirrored quad reversed")
check(list(m[12]) == [41, 43, 42, -1], "mirrored triangle reversed")
# Mirrored fan = fan of the reversed polygon (0, 4, 3, 2, 1).
check([list(r) for r in m[9:12]] == [[36, 40, 39, -1], [36, 39, 38, -1], [36, 38, 37, -1]], "mirrored pentagon fan")
def test_canonical_and_reverse():
f = np.array([[5, 2, 7, 1], [4, 9, 3, N]], dtype=np.uint32)
c, r = exchange.canonical_faces(f)
check(c.tolist() == [[1, 5, 2, 7], [3, 4, 9, N]] and r.tolist() == [3, 2], "canonical rotation keeps winding")
rev, data = exchange.reverse_faces(f, np.arange(8).reshape(2, 4))
check(rev.tolist() == [[5, 1, 7, 2], [4, 3, 9, N]], "reverse_faces")
check(data.tolist() == [[0, 3, 2, 1], [4, 6, 5, 7]], "reverse_faces moves corner data along")
check(exchange.same_topology(f, np.roll(f[:1], 1, axis=1).tolist() + [[9, 3, 4, N]]), "rotated faces are the same")
check(not exchange.same_topology(f, rev), "reversed faces are not")
rotated = np.array([[7, 1, 5, 2], [3, 4, 9, N]], dtype=np.uint32)
cm = exchange.corner_map(f, rotated)
check(all(f[i, s] == rotated[i, cm[i, s]] for i in range(2) for s in range(3)) and f[0, 3] == rotated[0, cm[0, 3]],
"corner_map finds each corner's vertex")
def test_bridge_round_trip(tmp):
arrays, _ = object_arrays(grid_with_ngon(), False, 1)
path = os.path.join(tmp, "t.Bridge")
exchange.write_bridge(path, "Grid Ünïcode.001", **arrays)
g = exchange.read_bridge(path)
check(g.name == "Grid_n_code_001", "Bridge name escaped like GoB (got %r)" % g.name)
check(np.allclose(g.positions, arrays["positions"], atol=1e-6), "Bridge positions")
check(np.array_equal(g.faces, arrays["faces"]), "Bridge faces")
tri = arrays["faces"][:, 3] == N
check(np.allclose(g.uvs[~tri], arrays["uvs"][~tri]) and np.allclose(g.uvs[tri, :3], arrays["uvs"][tri, :3]), "Bridge UVs")
check(np.allclose(g.colors, arrays["colors"]), "Bridge vertexpaint")
check(np.allclose(g.mask, arrays["mask"], atol=1e-9), "Bridge mask")
check(np.array_equal(g.groups, arrays["groups"]), "Bridge facegroups")
with open(path, "rb") as f:
head = f.read(64)
check(head.startswith(exchange.HEADER), "Bridge header as GoB writes it")
def test_manifest(tmp):
folder = os.path.join(tmp, "m")
check(exchange.revision(folder) == -1, "no manifest yet")
r1 = exchange.write_manifest(folder, [{"name": "A", "file": "r1_000.Bridge"}])
open(os.path.join(folder, "r1_000.Bridge"), "wb").close()
check(exchange.next_file_prefix(folder) == "r2_", "next prefix")
open(os.path.join(folder, "r2_000.Bridge"), "wb").close()
r2 = exchange.write_manifest(folder, [{"name": "A", "file": "r2_000.Bridge"}])
check((r1, r2) == (1, 2), "revisions count up")
check(not os.path.exists(os.path.join(folder, "r1_000.Bridge")), "old files removed")
check(os.path.exists(os.path.join(folder, "r2_000.Bridge")), "current files kept")
with open(exchange.manifest_path(folder), "w") as f:
f.write('{"format": "sculptforge-bridge", "objects": [{"name": "x", "file": "../evil"}]}')
try:
exchange.read_manifest(folder)
check(False, "a manifest naming ../evil is refused")
except ValueError:
pass
# ---------------------------------------------------------------------------- through SculptForge
def test_round_trip_through_sculptforge(tmp, cli):
root = os.path.join(tmp, "exchange")
out = exchange.outbox(root)
os.makedirs(out)
rot = rotation((1.0, 2.0, 0.5), 37.0)
objects = [
("Grid", grid_with_ngon(), matrix(rot, (1.0, 1.0, 1.0), (0.3, -1.2, 2.0))),
("Grid.scaled", grid_with_ngon(), matrix(rot.T, (2.0, 0.5, 3.0), (-4.0, 1.0, 0.0))),
("Mirrored", grid_with_ngon(), matrix(np.eye(3), (-1.0, 1.0, 1.0), (1.0, 1.0, 1.0))),
("Hexagon ünïcode", only_ngons(), matrix(rotation((0, 0, 1), 90), (1, 1, 1), (0, 0, 5))),
]
sent = {}
entries = []
for k, (name, mesh, m) in enumerate(objects):
mirrored = np.linalg.det(m[:3, :3]) < 0
arrays, _ = object_arrays(mesh, mirrored, k + 10)
file = "r1_%03d.Bridge" % k
exchange.write_bridge(os.path.join(out, file), name, **arrays)
entries.append({"name": name, "file": file, "matrix_world": m.tolist()})
sent[name] = (mesh, m, arrays)
exchange.write_manifest(out, entries, "test")
r = subprocess.run([cli, "-c", 'blender_receive folder="%s"; blender_send folder="%s"' % (root, root)],
capture_output=True, text=True)
print(r.stdout.strip())
check(r.returncode == 0, "sculptforge-cli ran (%s)" % r.stderr.strip())
if r.returncode:
return
manifest = exchange.read_manifest(exchange.inbox(root))
names = [o["name"] for o in manifest["objects"]]
check(names == [o[0] for o in objects], "every object comes back under its Blender name (got %s)" % names)
for entry in manifest["objects"]:
name = entry["name"]
if name not in sent:
continue
mesh, m, arrays = sent[name]
g = exchange.read_bridge(os.path.join(exchange.inbox(root), entry["file"]))
# What the add-on does on receive (update_object): into object space, and the faces compared with the
# ones it sent (reversed for a mirrored object).
local = exchange.transform_points(np.linalg.inv(m), g.positions)
mirrored = np.linalg.det(m[:3, :3]) < 0
co, starts, totals, loop_vert = mesh
loops, face_poly = exchange.polygon_corners(starts, totals, mirrored)
expect = exchange.faces_from_loops(loops, loop_vert)
same = exchange.same_topology(expect, g.faces)
check(same, "%s: same faces and winding" % name)
err = np.abs(local - co).max()
check(err < 1e-5, "%s: positions back in object space (max error %.2g)" % (name, err))
# World placement in SculptForge's file: Blender world space.
world = exchange.transform_points(m, co)
check(np.abs(g.positions - world).max() < 1e-5, "%s: placed in the scene as in Blender" % name)
# Placed with a negative scale, the reversed faces wind outwards again: the normals SculptForge sees
# point the way Blender's do (here: the grid's first quad, whose Blender normal is +z before the matrix).
f0 = g.faces[0]
n = np.cross(g.positions[f0[1]] - g.positions[f0[0]], g.positions[f0[2]] - g.positions[f0[0]])
p = co[mesh[3][mesh[1][0]:mesh[1][0] + 3]]
nb = np.cross(p[1] - p[0], p[2] - p[0])
expect_n = np.linalg.inv(m[:3, :3]).T @ nb
check(np.dot(n, expect_n) > 0, "%s: winding faces outwards in SculptForge" % name)
if not same:
continue
cm = exchange.corner_map(expect, g.faces)
# Per loop: the UV that was sent and the one that came back.
loop_uv_sent = np.zeros((len(loop_vert), 2))
loop_uv_sent[loops[loops >= 0]] = arrays["uvs"][loops >= 0]
back = np.take_along_axis(g.uvs, cm[:, :, None].repeat(2, axis=2), axis=1)
loop_uv_back = np.zeros_like(loop_uv_sent)
loop_uv_back[loops[loops >= 0]] = back[loops >= 0]
check(np.allclose(loop_uv_back, loop_uv_sent, atol=1e-6), "%s: UVs" % name)
check(g.colors is not None and np.allclose(g.colors, arrays["colors"]), "%s: vertexpaint" % name)
check(g.mask is not None and np.allclose(g.mask, arrays["mask"], atol=1e-9), "%s: mask" % name)
check(g.groups is not None and np.array_equal(g.groups, arrays["groups"]), "%s: facegroups" % name)
# A second send from SculptForge: the next revision, the previous files gone.
r = subprocess.run([cli, "-c", 'blender_receive folder="%s"; blender_send folder="%s"' % (root, root)],
capture_output=True, text=True)
check(exchange.revision(exchange.inbox(root)) == 2, "SculptForge's revision counts up")
left = sorted(f for f in os.listdir(exchange.inbox(root)) if f.startswith("r1_"))
check(not left, "SculptForge removes its earlier files (left: %s)" % left)
def test_shapes_through_sculptforge(tmp, cli):
"""Sculpt layers (here the 52 ARKit facial shapes) travel as a shapes file beside the Bridge, which holds the base
shape: read_shapes gives the names in order and offsets in Blender's axes (jawOpen drops the chin: -Z)."""
root = os.path.join(tmp, "shapes")
r = subprocess.run([cli, "-c", 'new_head; face_shapes_generate; blender_send folder="%s"' % root],
capture_output=True, text=True)
check(r.returncode == 0, "sculptforge-cli new_head; face_shapes_generate; blender_send (%s)" % r.stderr.strip())
if r.returncode:
return
folder = exchange.inbox(root) # (the add-on's inbox: what SculptForge sent)
manifest = exchange.read_manifest(folder)
head = [o for o in manifest["objects"] if o["name"] == "Head"]
check(len(head) == 1 and head[0].get("shapes"), "the Head object names its shapes file")
if not head or not head[0].get("shapes"):
return
g = exchange.read_bridge(os.path.join(folder, head[0]["file"]))
nv, shapes = exchange.read_shapes(os.path.join(folder, head[0]["shapes"]))
check(nv == len(g.positions), "shapes file vertex count matches the .Bridge")
names = [s[0] for s in shapes]
check(len(names) == 52 and names[0] == "browDownLeft" and names[-1] == "tongueOut" and "jawOpen" in names,
"the 52 ARKit names, in order")
jaw = shapes[names.index("jawOpen")]
check(len(jaw[2]) > 100 and jaw[3][:, 2].min() < -0.01, "jawOpen moves the chin down (Blender -Z)")
check(all(s[1] == 0.0 for s in shapes), "weights are sent (all 0 after generating)")
eyes = [o for o in manifest["objects"] if o["name"] == "Eyes"]
check(len(eyes) == 1 and eyes[0].get("shapes"), "the Eyes Part has its eyeLook shapes too")
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--cli", help="sculptforge-cli, for the round trip through SculptForge")
args = ap.parse_args()
with tempfile.TemporaryDirectory() as tmp:
test_polygon_corners()
test_canonical_and_reverse()
test_bridge_round_trip(tmp)
test_manifest(tmp)
if args.cli:
test_round_trip_through_sculptforge(tmp, args.cli)
test_shapes_through_sculptforge(tmp, args.cli)
if failures:
print("%d check(s) failed" % len(failures))
return 1
print("all checks passed")
return 0
if __name__ == "__main__":
sys.exit(main())