Free, open-source file converter. Convert 263 formats offline by drag & drop — images, PDF, Word, Excel, PowerPoint, HWP/HWPX, video, audio, e-books and archives. No upload, no Office needed.
C# audio-converteravaloniabatch-conversionconvertercsharpdocument-converterdocx-to-pdfdotnetdrag-and-dropfile-conversionfile-converterheic-converterhwphwpximage-converterlinuxmacospdf-convertervideo-converterwindows
// 3D models: GLB, glTF, STL, OBJ, 3MF and PLY into each other and to pictures. Meshes are generated (ModelBuilders)
// or written as text / bytes here; every format pair is converted through the job queue and read back.
using System.Buffers.Binary;
using System.IO.Compression;
using System.Numerics;
using System.Text;
using System.Text.Json.Nodes;
using Filee.Core.Conversion;
using Filee.Core.Presets;
using Filee.Engines.Models3D;
using ImageMagick;
using SharpGLTF.Schema2;
namespace Filee.Engines.Tests;
public class ModelTests(EngineFixture fx) : IClassFixture<EngineFixture>
{
private static readonly string[] Formats = ModelConverter.Formats;
private static readonly string[] WithNormals = ["obj", "ply", "glb", "gltf"];
private static readonly string[] WithUvs = ["obj", "ply", "glb", "gltf"];
private static readonly string[] WithVertexColors = ["obj", "ply", "3mf", "glb", "gltf"];
private static readonly string[] WithMaterials = ["obj", "3mf", "glb", "gltf"];
private static readonly string[] WithTextures = ["obj", "glb", "gltf"];
private async Task<ConversionJob> RunAsync(string input, string target)
{
var job = await fx.ConvertAsync([input], new Preset { TargetFormat = target });
Assert.True(job.State == JobState.Completed, string.Join("; ", job.Files.Select(f => $"{f.ErrorKey} {f.ErrorDetail}")));
return job;
}
private async Task<string> FailAsync(string input, string target)
{
var job = await fx.ConvertAsync([input], new Preset { TargetFormat = target });
Assert.Equal(JobState.Failed, job.State);
return job.Files.Single().ErrorDetail ?? "";
}
public static TheoryData<string, string, string> Pairs()
{
var data = new TheoryData<string, string, string>();
foreach (var kind in new[] { "cube", "sphere", "fan" })
foreach (var from in Formats)
foreach (var to in Formats.Where(t => t != from))
data.Add(kind, from, to);
return data;
}
// ───────────────────────── Routes ─────────────────────────
[Fact]
public void Every_pair_and_every_picture_is_one_step_of_the_3d_engine()
{
var planner = fx.Catalog.CreatePlanner();
foreach (var from in Formats)
{
foreach (var to in Formats.Where(t => t != from).Concat(["png", "jpg", "webp"]))
{
var route = planner.Plan(from, to);
Assert.NotNull(route);
Assert.Equal("model3d", Assert.Single(route.Steps).Converter.Id);
}
}
}
// ───────────────────────── Every format pair ─────────────────────────
[Theory]
[MemberData(nameof(Pairs))]
public async Task Converting_keeps_geometry_and_what_both_formats_store(string kind, string from, string to)
{
var folder = fx.NewFolder();
var source = ModelBuilders.Save(ModelBuilders.Make(kind), folder, kind, from);
var expected = ModelBuilders.Load(source, from);
var job = await RunAsync(source, to);
var output = job.Outputs.First(o => o.EndsWith("." + to, StringComparison.OrdinalIgnoreCase));
var actual = ModelBuilders.Load(output, to);
Assert.Equal(expected.TriangleCount, actual.TriangleCount);
var (expectedMin, expectedMax) = expected.Bounds();
var (actualMin, actualMax) = actual.Bounds();
AssertClose(expectedMin, actualMin, 1e-3f);
AssertClose(expectedMax, actualMax, 1e-3f);
Assert.Equal(ModelBuilders.SignedVolume(expected), ModelBuilders.SignedVolume(actual), 0.05);
Assert.Equal(ModelBuilders.Area(expected), ModelBuilders.Area(actual), 0.05);
Assert.Equal(ModelBuilders.Positions(expected), ModelBuilders.Positions(actual));
if (WithNormals.Contains(to) && expected.Parts.Any(p => p.Normals is not null))
AssertAttributesMatch(expected, actual, p => p.Normals is not null, (p, v) => new Vector4(p.Normal(v), 0), 1e-3f);
if (WithUvs.Contains(to) && expected.Parts.Any(p => p.TexCoords is not null))
AssertAttributesMatch(expected, actual, p => p.TexCoords is not null, (p, v) => new Vector4(p.TexCoord(v), 0, 0), 1e-4f);
if (WithVertexColors.Contains(to) && expected.Parts.Any(p => p.Colors is not null))
AssertAttributesMatch(expected, actual, p => p.Colors is not null, (p, v) => p.Color(v), 2.5f / 255);
if (WithMaterials.Contains(to) && expected.Materials.Count > 0)
{
var color = Assert.Single(actual.Materials).BaseColor;
AssertClose(expected.Materials[0].BaseColor, color, to == "3mf" ? 0.01f : 1e-4f);
if (WithTextures.Contains(to) && expected.Materials[0].BaseColorTexture is { } texture)
Assert.Equal(texture.Data, actual.Materials[0].BaseColorTexture?.Data);
}
}
/// <summary>Every vertex of <paramref name="actual"/> has a value that some vertex at the same place had before.</summary>
private static void AssertAttributesMatch(Model3D expected, Model3D actual, Func<MeshPart, bool> has, Func<MeshPart, int, Vector4> value, float tolerance)
{
var known = new Dictionary<(int, int, int), List<Vector4>>();
foreach (var part in expected.Parts.Where(has))
{
for (var v = 0; v < part.VertexCount; v++)
{
var key = ModelBuilders.Key(part.Position(v));
if (!known.TryGetValue(key, out var list))
known[key] = list = [];
list.Add(value(part, v));
}
}
Assert.Contains(actual.Parts, p => has(p));
foreach (var part in actual.Parts.Where(has))
{
for (var v = 0; v < part.VertexCount; v++)
{
var found = value(part, v);
var candidates = known[ModelBuilders.Key(part.Position(v))];
Assert.True(candidates.Any(c => Vector4.Distance(c, found) <= tolerance * 2),
$"Vertex {v} at {part.Position(v)} has {found}; expected one of {string.Join(", ", candidates)}");
}
}
}
private static void AssertClose(Vector3 expected, Vector3 actual, float tolerance) =>
Assert.True(Vector3.Distance(expected, actual) <= tolerance, $"Expected {expected}, got {actual}");
private static void AssertClose(Vector4 expected, Vector4 actual, float tolerance) =>
Assert.True(Vector4.Distance(expected, actual) <= tolerance, $"Expected {expected}, got {actual}");
// ───────────────────────── Units and axes ─────────────────────────
[Fact]
public async Task Stl_millimetres_and_z_up_become_gltf_metres_and_y_up()
{
// A box 10 × 20 mm wide and 50 mm tall along Z, as a 3D printer sees it.
var folder = fx.NewFolder();
var stl = Path.Combine(folder, "tower.stl");
WriteBinaryStl(stl, Box(new Vector3(0, 0, 0), new Vector3(10, 20, 50)));
var glb = (await RunAsync(stl, "glb")).Outputs.Single();
var root = ModelRoot.Load(glb);
var position = root.LogicalMeshes.Single().Primitives.Single().GetVertexAccessor("POSITION");
var (min, max) = position.Bounds;
Assert.Equal(0.010, max[0] - min[0], 1e-6);
Assert.Equal(0.050, max[1] - min[1], 1e-6); // up
Assert.Equal(0.020, max[2] - min[2], 1e-6);
// And back: the same box, standing on Z again.
var raw = ReadBinaryStl((await RunAsync(glb, "stl")).Outputs.Single());
Assert.Equal(new Vector3(10, 20, 50), raw.Max - raw.Min);
Assert.Equal(12, raw.Facets.Count);
}
[Fact]
public async Task Gltf_from_3mf_in_inches_is_scaled_to_metres()
{
var folder = fx.NewFolder();
var path = Path.Combine(folder, "inch.3mf");
Write3mf(path, """
<model unit="inch" xmlns="http://schemas.microsoft.com/3dmanufacturing/core/2015/02">
<resources>
<object id="1" type="model"><mesh>
<vertices><vertex x="0" y="0" z="0"/><vertex x="1" y="0" z="0"/><vertex x="0" y="1" z="0"/><vertex x="0" y="0" z="1"/></vertices>
<triangles><triangle v1="0" v2="2" v3="1"/><triangle v1="0" v2="1" v3="3"/><triangle v1="0" v2="3" v3="2"/><triangle v1="1" v2="2" v3="3"/></triangles>
</mesh></object>
</resources>
<build><item objectid="1"/></build>
</model>
""");
var glb = (await RunAsync(path, "glb")).Outputs.Single();
var (min, max) = ModelRoot.Load(glb).LogicalMeshes.Single().Primitives.Single().GetVertexAccessor("POSITION").Bounds;
Assert.Equal(0.0254, max[0] - min[0], 1e-6);
Assert.Equal(0.0254, max[1] - min[1], 1e-6);
}
[Fact]
public async Task Stl_facet_normals_point_outward()
{
var folder = fx.NewFolder();
var source = ModelBuilders.Save(ModelBuilders.Cube(), folder, "cube", "glb");
var stl = ReadBinaryStl((await RunAsync(source, "stl")).Outputs.Single());
var center = (stl.Min + stl.Max) / 2;
Assert.Equal(12, stl.Facets.Count);
foreach (var (normal, a, b, c) in stl.Facets)
{
Assert.Equal(1, normal.Length(), 1e-4);
Assert.True(Vector3.Dot(normal, (a + b + c) / 3 - center) > 0);
}
}
// ───────────────────────── Outputs with several files ─────────────────────────
[Fact]
public async Task Obj_output_writes_the_material_library_and_texture_next_to_it()
{
var folder = fx.NewFolder();
var glb = ModelBuilders.Save(ModelBuilders.Cube(), folder, "kubus", "glb");
var job = await RunAsync(glb, "obj");
var obj = job.Outputs.Single(o => o.EndsWith(".obj", StringComparison.Ordinal));
var mtl = job.Outputs.Single(o => o.EndsWith(".mtl", StringComparison.Ordinal));
var png = job.Outputs.Single(o => o.EndsWith(".png", StringComparison.Ordinal));
Assert.All(job.Outputs, o => Assert.Equal(Path.GetDirectoryName(obj), Path.GetDirectoryName(o)));
Assert.Contains($"mtllib {Path.GetFileName(mtl)}", File.ReadAllText(obj));
Assert.Contains($"map_Kd {Path.GetFileName(png)}", File.ReadAllText(mtl));
Assert.Equal(ModelBuilders.Checker(), File.ReadAllBytes(png));
}
[Theory]
[InlineData(0x41u)]
[InlineData(0x40u)]
public async Task Obj_dds_texture_keeps_its_colours_in_glb(uint flags)
{
var folder = fx.NewFolder();
byte[] pixels = [.. Enumerable.Repeat<byte[]>([255, 0, 0, 255], 16).SelectMany(p => p)];
File.WriteAllBytes(Path.Combine(folder, "red.dds"), ImageFormatTests.Dds(flags, 0xFF, 0xFF00, 0xFF0000, 0xFF000000, pixels));
await File.WriteAllTextAsync(Path.Combine(folder, "model.mtl"), "newmtl red\nmap_Kd red.dds\n", TestContext.Current.CancellationToken);
var obj = Path.Combine(folder, "model.obj");
await File.WriteAllTextAsync(obj, """
mtllib model.mtl
v 0 0 0
v 1 0 0
v 0 1 0
vt 0 0
vt 1 0
vt 0 1
usemtl red
f 1/1 2/2 3/3
""", TestContext.Current.CancellationToken);
var job = await RunAsync(obj, "glb");
var data = await File.ReadAllBytesAsync(job.Outputs.Single(), TestContext.Current.CancellationToken);
Assert.Equal(0x46546C67u, BinaryPrimitives.ReadUInt32LittleEndian(data));
Assert.Equal(2u, BinaryPrimitives.ReadUInt32LittleEndian(data.AsSpan(4)));
Assert.Equal((uint)data.Length, BinaryPrimitives.ReadUInt32LittleEndian(data.AsSpan(8)));
var jsonLength = BinaryPrimitives.ReadInt32LittleEndian(data.AsSpan(12));
Assert.Equal(0x4E4F534Au, BinaryPrimitives.ReadUInt32LittleEndian(data.AsSpan(16)));
var json = JsonNode.Parse(data.AsSpan(20, jsonLength))!;
var binHeader = 20 + jsonLength;
var binLength = BinaryPrimitives.ReadInt32LittleEndian(data.AsSpan(binHeader));
Assert.Equal(0x004E4942u, BinaryPrimitives.ReadUInt32LittleEndian(data.AsSpan(binHeader + 4)));
Assert.Equal(data.Length, binHeader + 8 + binLength);
var material = Assert.Single(json["materials"]!.AsArray())!;
var textureIndex = (int)material["pbrMetallicRoughness"]!["baseColorTexture"]!["index"]!;
var imageIndex = (int)json["textures"]![textureIndex]!["source"]!;
var embedded = json["images"]![imageIndex]!;
Assert.Equal("image/png", (string)embedded["mimeType"]!);
var view = json["bufferViews"]![(int)embedded["bufferView"]!]!;
Assert.Equal(0, (int)view["buffer"]!);
var offset = (int?)view["byteOffset"] ?? 0;
var length = (int)view["byteLength"]!;
Assert.InRange(offset, 0, binLength - length);
var png = data.AsSpan(binHeader + 8 + offset, length).ToArray();
Assert.Equal(new byte[] { 137, 80, 78, 71, 13, 10, 26, 10 }, png[..8]);
using var image = new MagickImage(png);
Assert.Equal(MagickFormat.Png, image.Format);
Assert.Equal((4u, 4u), (image.Width, image.Height));
Assert.Equal(pixels.Where((_, i) => i % 4 != 3).ToArray(), image.GetPixels().ToByteArray(PixelMapping.RGB));
}
[Fact]
public async Task Gltf_output_is_one_file_with_the_buffer_inside()
{
var folder = fx.NewFolder();
var source = ModelBuilders.Save(ModelBuilders.Cube(), folder, "cube", "obj");
var gltf = (await RunAsync(source, "gltf")).Outputs.Single();
var json = JsonNode.Parse(File.ReadAllText(gltf))!;
Assert.StartsWith("data:application/octet-stream;base64,", (string)json["buffers"]![0]!["uri"]!);
Assert.Empty(Directory.GetFiles(folder, "*.bin"));
var root = ModelRoot.Load(gltf);
Assert.Equal(12, root.LogicalMeshes.Single().Primitives.Single().GetTriangleIndices().Count());
Assert.NotNull(root.LogicalMaterials.Single().FindChannel("BaseColor")!.Value.Texture);
}
[Fact]
public async Task Gltf_with_a_separate_buffer_and_texture_is_read()
{
var folder = fx.NewFolder();
// The node scales by 2 and moves up by 1 m: both end up in the vertices.
var root = TexturedQuad(Matrix4x4.CreateScale(2) * Matrix4x4.CreateTranslation(0, 1, 0));
var gltf = Path.Combine(folder, "quad.gltf");
root.SaveGLTF(gltf, new WriteSettings { ImageWriting = ResourceWriteMode.SatelliteFile });
Assert.NotEmpty(Directory.GetFiles(folder, "*.bin"));
var model = ModelBuilders.Load((await RunAsync(gltf, "ply")).Outputs.Single(), "ply");
var (min, max) = model.Bounds();
AssertClose(new Vector3(0, 1000, 0), min, 1e-2f);
AssertClose(new Vector3(2000, 3000, 0), max, 1e-2f);
Assert.Equal(2, model.TriangleCount);
// glTF's UV origin is the top left, PLY's the bottom left.
Assert.Equal(new Vector2(0, 0), model.Parts[0].TexCoord(Enumerable.Range(0, 4).Single(v => model.Parts[0].Position(v) is { X: < 1, Y: < 1001 })));
var objJob = await RunAsync(gltf, "obj");
Assert.Equal(3, objJob.Outputs.Count()); // .obj, .mtl and the texture
}
[Fact]
public void Gltf_buffers_and_pictures_stay_beside_the_model()
{
var folder = fx.NewFolder();
var source = Directory.CreateDirectory(Path.Combine(folder, "source")).FullName;
var outside = Directory.CreateDirectory(Path.Combine(folder, "outside")).FullName;
Directory.CreateDirectory(Path.Combine(source, "textures"));
var gltf = Path.Combine(source, "quad.gltf");
TexturedQuad(Matrix4x4.Identity).SaveGLTF(gltf, new WriteSettings { ImageWriting = ResourceWriteMode.SatelliteFile });
var picture = Path.GetFileName(Directory.GetFiles(source, "*.png").Single());
var buffer = Path.GetFileName(Directory.GetFiles(source, "*.bin").Single());
var json = File.ReadAllText(gltf);
Model3D Load(string from, string to)
{
File.WriteAllText(gltf, json.Replace($"\"{from}\"", $"\"{to}\"", StringComparison.Ordinal));
return ModelBuilders.Load(gltf, "gltf");
}
// A folder below the model's is fine.
File.Move(Path.Combine(source, picture), Path.Combine(source, "textures", picture));
var model = Load(picture, "textures/" + picture);
Assert.Equal(ModelBuilders.Checker(), model.MaterialOf(model.Parts.Single())!.BaseColorTexture!.Data);
// A picture up and out of it, or a buffer at an absolute path, is never opened.
File.Move(Path.Combine(source, "textures", picture), Path.Combine(outside, picture));
Assert.Contains(picture, Assert.Throws<InvalidDataException>(() => Load(picture, "../outside/" + picture)).Message);
File.Move(Path.Combine(outside, picture), Path.Combine(source, picture));
File.Move(Path.Combine(source, buffer), Path.Combine(outside, buffer));
Assert.Throws<InvalidDataException>(() => Load(buffer, new Uri(Path.Combine(outside, buffer)).AbsoluteUri));
Assert.Throws<InvalidDataException>(() => Load(buffer, Path.Combine(outside, buffer).Replace('\\', '/')));
}
[Fact]
public void Gltf_reads_percent_encoded_buffer_and_picture_names()
{
var folder = fx.NewFolder();
var source = Directory.CreateDirectory(Path.Combine(folder, "source")).FullName;
var gltf = Path.Combine(source, "quad.gltf");
TexturedQuad(Matrix4x4.Identity).SaveGLTF(gltf, new WriteSettings { ImageWriting = ResourceWriteMode.SatelliteFile });
var json = JsonNode.Parse(File.ReadAllText(gltf))!;
var picture = (string)json["images"]![0]!["uri"]!;
var buffer = (string)json["buffers"]![0]!["uri"]!;
File.Move(Path.Combine(source, picture), Path.Combine(source, "paint image.png"));
File.Move(Path.Combine(source, buffer), Path.Combine(source, "mesh data.bin"));
json["images"]![0]!["uri"] = "paint%20image.png";
json["buffers"]![0]!["uri"] = "mesh%20data.bin";
File.WriteAllText(gltf, json.ToJsonString());
var model = ModelBuilders.Load(gltf, "gltf");
Assert.Equal(2, model.TriangleCount);
Assert.Equal(ModelBuilders.Checker(), model.MaterialOf(model.Parts.Single())!.BaseColorTexture!.Data);
// Decoding must still leave the existing folder boundary in force.
var outside = Directory.CreateDirectory(Path.Combine(folder, "outside")).FullName;
File.Move(Path.Combine(source, "paint image.png"), Path.Combine(outside, "paint image.png"));
json["images"]![0]!["uri"] = "..%2Foutside%2Fpaint%20image.png";
File.WriteAllText(gltf, json.ToJsonString());
Assert.Throws<InvalidDataException>(() => ModelBuilders.Load(gltf, "gltf"));
}
private static ModelRoot TexturedQuad(Matrix4x4 transform)
{
var root = ModelRoot.CreateModel();
var material = root.CreateMaterial("Painted");
material.InitializePBRMetallicRoughness();
material.FindChannel("BaseColor")!.Value.SetTexture(0, root.UseImage(new SharpGLTF.Memory.MemoryImage(ModelBuilders.Checker())), null,
TextureWrapMode.REPEAT, TextureWrapMode.REPEAT, TextureMipMapFilter.DEFAULT, TextureInterpolationFilter.DEFAULT);
var mesh = root.CreateMesh("Quad");
var primitive = mesh.CreatePrimitive();
primitive.SetVertexAccessor("POSITION", Accessor(root, [new Vector3(0, 0, 0), new Vector3(1, 0, 0), new Vector3(1, 1, 0), new Vector3(0, 1, 0)]));
primitive.SetVertexAccessor("TEXCOORD_0", Accessor(root, [new Vector2(0, 1), new Vector2(1, 1), new Vector2(1, 0), new Vector2(0, 0)]));
var indices = root.CreateAccessor();
indices.SetIndexData(root.UseBufferView(new byte[] { 0, 0, 1, 0, 2, 0, 0, 0, 2, 0, 3, 0 }, 0, null, 0, BufferMode.ELEMENT_ARRAY_BUFFER), 0, 6, IndexEncodingType.UNSIGNED_SHORT);
primitive.SetIndexAccessor(indices);
primitive.Material = material;
var node = root.UseScene("Scene").CreateNode("Quad");
node.Mesh = mesh;
node.LocalMatrix = transform;
return root;
}
private static Accessor Accessor<T>(ModelRoot root, T[] values) where T : unmanaged
{
var view = root.UseBufferView(System.Runtime.InteropServices.MemoryMarshal.AsBytes(values.AsSpan()).ToArray(), 0, null, 0, BufferMode.ARRAY_BUFFER);
var accessor = root.CreateAccessor();
accessor.SetVertexData(view, 0, values.Length, new SharpGLTF.Memory.AttributeFormat(typeof(T) == typeof(Vector3) ? DimensionType.VEC3 : DimensionType.VEC2));
accessor.UpdateBounds();
return accessor;
}
// ───────────────────────── Real-world files ─────────────────────────
[Fact]
public async Task Ascii_stl_with_two_solids_becomes_two_meshes()
{
var folder = fx.NewFolder();
var path = Path.Combine(folder, "two.stl");
File.WriteAllText(path, """
solid first
facet normal 0 0 1
outer loop
vertex 0 0 0
vertex 1 0 0
vertex 0 1 0
endloop
endfacet
endsolid first
solid second
facet normal 0 0 1
outer loop
vertex 5 0 0
vertex 6.5e0 0 0
vertex 5 1 0
endloop
endfacet
endsolid second
""");
var model = ModelBuilders.Load(path, "stl");
Assert.Equal(["first", "second"], model.Parts.Select(p => p.Name));
var glb = ModelRoot.Load((await RunAsync(path, "glb")).Outputs.Single());
Assert.Equal(2, glb.LogicalMeshes.Count);
}
[Fact]
public void Binary_stl_with_a_solid_header_and_extra_bytes_is_read_as_binary()
{
var folder = fx.NewFolder();
var path = Path.Combine(folder, "solid.stl");
WriteBinaryStl(path, Box(Vector3.Zero, new Vector3(1, 2, 3)));
var data = File.ReadAllBytes(path);
"solid exported by a CAD program"u8.CopyTo(data);
File.WriteAllBytes(path, [.. data, .. "trailing"u8]);
var model = ModelBuilders.Load(path, "stl");
Assert.Equal(12, model.TriangleCount);
Assert.Equal(8, model.VertexCount);
}
[Fact]
public async Task Obj_with_polygons_negative_indices_colours_and_a_material_library()
{
var folder = fx.NewFolder();
File.WriteAllBytes(Path.Combine(folder, "wood grain.png"), ModelBuilders.Checker());
File.WriteAllText(Path.Combine(folder, "parts.mtl"), """
newmtl wood
Kd 0.5 0.25 0.125
map_Kd -s 1 1 1 -bm 0.5 wood grain.png
""");
// A U-shaped octagon (concave: a fan from its first corner would cover the notch) and a quad with
// negative indices and vertex colours.
File.WriteAllText(Path.Combine(folder, "parts.obj"), """
mtllib parts.mtl
o U
v 2 2 0 1 0 0
v 2 1 0 1 0 0
v 1 1 0 1 0 0
v 1 2 0 1 0 0
v 0 2 0 1 0 0
v 0 0 0 1 0 0
v 3 0 0 1 0 0
v 3 2 0 1 0 0
usemtl wood
f 1 2 3 4 5 6 7 8
o Quad
v 10 0 0 0 0 255
v 11 0 0 0 0 255
v 11 1 0 0 0 255
v 10 1 0 0 0 255
vt 0 0
vt 1 1
f -4/-2 -3/-2 -2/-1 -1/-1
""");
var model = ModelBuilders.Load(Path.Combine(folder, "parts.obj"), "obj");
var u = model.Parts.Single(p => p.Name == "U");
Assert.Equal(6, u.TriangleCount);
Assert.Equal(5, ModelBuilders.Area(new Model3D { Parts = { u } }), 1e-4);
Assert.Equal("wood", model.MaterialOf(u)!.Name);
Assert.Equal(new Vector4(0.5f, 0.25f, 0.125f, 1), model.MaterialOf(u)!.BaseColor);
Assert.Equal(ModelBuilders.Checker(), model.MaterialOf(u)!.BaseColorTexture!.Data);
var quad = model.Parts.Single(p => p.Name == "Quad");
Assert.Equal(2, quad.TriangleCount);
Assert.Equal(new Vector4(0, 0, 1, 1), quad.Color(0)); // 0–255 values are scaled
var glb = ModelRoot.Load((await RunAsync(Path.Combine(folder, "parts.obj"), "glb")).Outputs.Single());
Assert.Equal(8, glb.LogicalMeshes.Sum(m => m.Primitives.Sum(p => p.GetTriangleIndices().Count())));
Assert.NotNull(glb.LogicalMaterials.Single(m => m.Name == "wood").FindChannel("BaseColor")!.Value.Texture);
}
[Fact]
public void Obj_textures_stay_beside_the_model()
{
var root = fx.NewFolder();
var source = Directory.CreateDirectory(Path.Combine(root, "source")).FullName;
var outside = Directory.CreateDirectory(Path.Combine(root, "outside")).FullName;
var allowed = Path.Combine(source, "allowed.png");
var secret = Path.Combine(outside, "secret.png");
File.WriteAllBytes(allowed, ModelBuilders.Checker());
File.WriteAllBytes(secret, ModelBuilders.Checker());
File.WriteAllText(Path.Combine(source, "materials.mtl"), $$"""
newmtl allowed
map_Kd allowed.png
newmtl parent
map_Kd ../outside/secret.png
newmtl absolute
map_Kd {{secret.Replace('\\', '/')}}
""");
File.WriteAllText(Path.Combine(source, "drawing.obj"), """
mtllib materials.mtl
v 0 0 0
v 1 0 0
v 0 1 0
vt 0 0
vt 1 0
vt 0 1
o allowed
usemtl allowed
f 1/1 2/2 3/3
o parent
usemtl parent
f 1/1 2/2 3/3
o absolute
usemtl absolute
f 1/1 2/2 3/3
""");
var model = ModelBuilders.Load(Path.Combine(source, "drawing.obj"), "obj");
Assert.Equal(ModelBuilders.Checker(), model.MaterialOf(model.Parts.Single(p => p.Name == "allowed"))!.BaseColorTexture!.Data);
Assert.Null(model.MaterialOf(model.Parts.Single(p => p.Name == "parent"))!.BaseColorTexture);
Assert.Null(model.MaterialOf(model.Parts.Single(p => p.Name == "absolute"))!.BaseColorTexture);
}
[Fact]
public void Ply_ascii_with_quads_and_colours_and_big_endian_binary_are_read()
{
var folder = fx.NewFolder();
var ascii = Path.Combine(folder, "ascii.ply");
File.WriteAllText(ascii, """
ply
format ascii 1.0
comment a quad and a triangle
element vertex 5
property float x
property float y
property float z
property uchar red
property uchar green
property uchar blue
element face 2
property list uchar int vertex_indices
end_header
0 0 0 255 0 0
1 0 0 0 255 0
1 1 0 0 0 255
0 1 0 255 255 255
2 0 0 0 0 0
4 0 1 2 3
3 1 4 2
""");
var model = ModelBuilders.Load(ascii, "ply");
Assert.Equal(3, model.TriangleCount);
Assert.Equal(new Vector4(0, 1, 0, 1), model.Parts[0].Color(1));
// Z up → Y up: the quad lies in the XZ plane.
Assert.Equal(new Vector3(1, 0, -1), model.Parts[0].Position(2));
var binary = Path.Combine(folder, "big.ply");
using (var stream = File.Create(binary))
{
stream.Write(Encoding.ASCII.GetBytes("ply\nformat binary_big_endian 1.0\nelement vertex 3\nproperty double x\nproperty double y\nproperty double z\nproperty ushort red\nproperty ushort green\nproperty ushort blue\nelement edge 1\nproperty int vertex1\nproperty int vertex2\nelement face 1\nproperty list uchar uint vertex_indices\nend_header\n"));
Span<byte> buffer = stackalloc byte[8];
foreach (var (x, y, z) in new[] { (0.0, 0.0, 0.0), (4.0, 0.0, 0.0), (0.0, 3.0, 0.0) })
{
foreach (var value in new[] { x, y, z })
{
BinaryPrimitives.WriteDoubleBigEndian(buffer, value);
stream.Write(buffer);
}
foreach (var channel in new ushort[] { 65535, 0, 32768 })
{
BinaryPrimitives.WriteUInt16BigEndian(buffer, channel);
stream.Write(buffer[..2]);
}
}
BinaryPrimitives.WriteInt32BigEndian(buffer, 0);
stream.Write(buffer[..4]);
BinaryPrimitives.WriteInt32BigEndian(buffer, 1);
stream.Write(buffer[..4]);
stream.WriteByte(3);
foreach (var index in new uint[] { 0, 1, 2 })
{
BinaryPrimitives.WriteUInt32BigEndian(buffer, index);
stream.Write(buffer[..4]);
}
}
var big = ModelBuilders.Load(binary, "ply");
Assert.Equal(1, big.TriangleCount);
Assert.Equal(6, ModelBuilders.Area(big), 1e-5);
Assert.Equal(1, big.Parts[0].Color(0).X, 1e-4);
Assert.Equal(0.5, big.Parts[0].Color(0).Z, 1e-3);
}
[Fact]
public void Three_mf_components_transforms_materials_and_colour_groups_are_read()
{
var folder = fx.NewFolder();
var path = Path.Combine(folder, "assembly.3mf");
Write3mf(path, """
<model unit="millimeter" xmlns="http://schemas.microsoft.com/3dmanufacturing/core/2015/02" xmlns:m="http://schemas.microsoft.com/3dmanufacturing/material/2015/02">
<resources>
<basematerials id="1"><base name="Orange" displaycolor="#FF8000"/><base name="Blue" displaycolor="#0000FFFF"/></basematerials>
<m:colorgroup id="2"><m:color color="#FF0000"/><m:color color="#00FF00"/></m:colorgroup>
<object id="3" type="model" pid="1" pindex="0"><mesh>
<vertices><vertex x="0" y="0" z="0"/><vertex x="10" y="0" z="0"/><vertex x="0" y="10" z="0"/><vertex x="10" y="10" z="0"/></vertices>
<triangles><triangle v1="0" v2="1" v3="2"/><triangle v1="1" v2="3" v3="2" pid="1" p1="1"/></triangles>
</mesh></object>
<object id="4" type="model"><mesh>
<vertices><vertex x="0" y="0" z="0"/><vertex x="1" y="0" z="0"/><vertex x="0" y="1" z="0"/></vertices>
<triangles><triangle v1="0" v2="1" v3="2" pid="2" p1="0" p2="1"/></triangles>
</mesh></object>
<object id="5" type="support"><mesh>
<vertices><vertex x="0" y="0" z="0"/><vertex x="1" y="0" z="0"/><vertex x="0" y="1" z="0"/></vertices>
<triangles><triangle v1="0" v2="1" v3="2"/></triangles>
</mesh></object>
<object id="6" type="model"><components>
<component objectid="3"/>
<component objectid="4" transform="1 0 0 0 1 0 0 0 1 100 0 0"/>
<component objectid="5"/>
</components></object>
</resources>
<build><item objectid="6" transform="1 0 0 0 1 0 0 0 1 0 0 5"/></build>
</model>
""");
var model = ModelBuilders.Load(path, "3mf");
Assert.Equal(3, model.TriangleCount); // the support is left out
Assert.Equal(["Orange", "Blue"], model.Materials.Select(m => m.Name));
AssertClose(new Vector4(1, MeshMath.SrgbToLinear(128 / 255f), 0, 1), model.Materials[0].BaseColor, 1e-4f);
var colored = model.Parts.Single(p => p.Colors is not null);
var corner = Enumerable.Range(0, colored.VertexCount).Single(v => colored.Position(v).X > 100.5f);
Assert.Equal(new Vector4(0, 1, 0, 1), colored.Color(corner)); // p2 → second colour
// Z up → Y up, and the item's 5 mm lift becomes Y.
Assert.All(model.Parts, p => Assert.Equal(5, p.Position(0).Y, 1e-4));
}
[Fact]
public async Task Ply_output_turns_material_colours_into_vertex_colours()
{
var folder = fx.NewFolder();
var source = ModelBuilders.Save(ModelBuilders.Cube(), folder, "cube", "3mf");
var model = ModelBuilders.Load((await RunAsync(source, "ply")).Outputs.Single(), "ply");
var expected = MeshMath.LinearToSrgb(ModelBuilders.CubeColor);
Assert.All(Enumerable.Range(0, model.VertexCount), v => AssertClose(expected, model.Parts[0].Color(v), 1.5f / 255));
}
[Fact]
public async Task Missing_normals_are_computed_where_the_output_has_them()
{
// A sphere with normals and a fan without, in one OBJ (the fan's faces have no "vn"): every vertex of the
// PLY gets a unit normal, the fan's pointing up.
var model = ModelBuilders.Sphere();
var fan = ModelBuilders.Fan().Parts[0];
fan.Colors = null;
model.Parts.Add(fan);
var folder = fx.NewFolder();
var obj = ModelBuilders.Save(model, folder, "mixed", "obj");
var ply = ModelBuilders.Load((await RunAsync(obj, "ply")).Outputs.Single(), "ply");
var part = ply.Parts.Single();
Assert.NotNull(part.Normals);
for (var v = 0; v < part.VertexCount; v++)
Assert.Equal(1, part.Normal(v).Length(), 1e-3);
var fanVertices = Enumerable.Range(0, part.VertexCount).Where(v => part.Position(v).Y == 0 && part.Position(v).Length() > 9.9f && part.Normal(v).Y > 0.99f);
Assert.Equal(6, fanVertices.Count());
// A face without normals among faces with them: the part's normals are computed from the faces.
var path = Path.Combine(folder, "partial.obj");
File.WriteAllText(path, "v 0 0 0\nv 1 0 0\nv 0 0 -1\nv 1 0 -1\nvn 0 1 0\nf 1//1 2//1 3//1\nf 2 4 3\n");
var partial = ModelBuilders.Load(path, "obj").Parts.Single();
Assert.All(Enumerable.Range(0, partial.VertexCount), v => Assert.Equal(1, partial.Normal(v).Y, 1e-4));
}
// ───────────────────────── Pictures ─────────────────────────
[Fact]
public async Task A_rotate_preset_turns_the_rendered_picture_once()
{
var folder = fx.NewFolder();
var source = ModelBuilders.Save(ModelBuilders.Fan(), folder, "fan", "stl");
var plain = (await RunAsync(source, "png")).Outputs.Single();
var job = await fx.ConvertAsync([source], new Preset { TargetFormat = "png", Image = { Rotation = ImageRotation.Left90 } });
Assert.True(job.State == JobState.Completed, string.Join("; ", job.Files.Select(f => $"{f.ErrorKey} {f.ErrorDetail}")));
using var expected = new MagickImage(plain);
expected.Rotate(-90);
using var turned = new MagickImage(job.Outputs.Single());
using var unturned = new MagickImage(plain);
Assert.True(unturned.Compare(expected, ErrorMetric.RootMeanSquared) > 0.01); // the fan looks different turned
Assert.True(turned.Compare(expected, ErrorMetric.RootMeanSquared) < 0.01);
}
[Fact]
public async Task A_model_renders_to_a_shaded_picture_with_a_transparent_background()
{
var folder = fx.NewFolder();
var source = ModelBuilders.Save(ModelBuilders.Sphere(), folder, "ball", "ply");
var png = (await RunAsync(source, "png")).Outputs.Single();
using var image = new MagickImage(png);
Assert.Equal(1024u, image.Width);
Assert.Equal(1024u, image.Height);
using var pixels = image.GetPixels();
Assert.Equal(0, pixels.GetPixel(2, 2)!.GetChannel(3));
var center = pixels.GetPixel(512, 512)!;
Assert.Equal(255, center.GetChannel(3));
// The sphere's colours come through (not a grey default).
var colors = Enumerable.Range(0, 16).Select(i => pixels.GetPixel(300 + i * 25, 512)!).Where(p => p.GetChannel(3) == 255)
.Select(p => (p.GetChannel(0), p.GetChannel(1), p.GetChannel(2))).Distinct().Count();
Assert.True(colors > 4);
var jpg = (await RunAsync(source, "jpg")).Outputs.Single();
Assert.Equal(MagickFormat.Jpeg, new MagickImageInfo(jpg).Format);
}
// ───────────────────────── Large files ─────────────────────────
[Fact]
public async Task A_million_triangle_stl_converts_in_seconds()
{
var folder = fx.NewFolder();
var path = Path.Combine(folder, "terrain.stl");
const int grid = 708; // 708 × 708 × 2 = 1,002,528 triangles
using (var stream = new BufferedStream(File.Create(path), 1 << 20))
{
var header = new byte[84];
BinaryPrimitives.WriteUInt32LittleEndian(header.AsSpan(80), grid * grid * 2);
stream.Write(header);
var record = new byte[50];
Vector3 P(int x, int y) => new(x, y, MathF.Sin(x * 0.05f) * MathF.Cos(y * 0.05f) * 5);
for (var y = 0; y < grid; y++)
{
for (var x = 0; x < grid; x++)
{
WriteFacet(stream, record, P(x, y), P(x + 1, y), P(x + 1, y + 1));
WriteFacet(stream, record, P(x, y), P(x + 1, y + 1), P(x, y + 1));
}
}
}
var watch = System.Diagnostics.Stopwatch.StartNew();
var glb = (await RunAsync(path, "glb")).Outputs.Single();
watch.Stop();
Assert.True(watch.Elapsed < TimeSpan.FromSeconds(30), $"took {watch.Elapsed}");
var primitive = ModelRoot.Load(glb).LogicalMeshes.Single().Primitives.Single();
Assert.Equal(grid * grid * 2, primitive.GetIndexAccessor().Count / 3);
Assert.Equal((grid + 1) * (grid + 1), primitive.GetVertexAccessor("POSITION").Count); // merged by position
}
private static void WriteFacet(Stream stream, byte[] record, Vector3 a, Vector3 b, Vector3 c)
{
var i = 12;
foreach (var v in new[] { a, b, c })
{
BinaryPrimitives.WriteSingleLittleEndian(record.AsSpan(i), v.X);
BinaryPrimitives.WriteSingleLittleEndian(record.AsSpan(i + 4), v.Y);
BinaryPrimitives.WriteSingleLittleEndian(record.AsSpan(i + 8), v.Z);
i += 12;
}
stream.Write(record);
}
// ───────────────────────── Bad input ─────────────────────────
[Fact]
public async Task Broken_files_fail_with_a_clear_message()
{
var folder = fx.NewFolder();
var truncated = Path.Combine(folder, "cut.stl");
var header = new byte[84 + 50];
BinaryPrimitives.WriteUInt32LittleEndian(header.AsSpan(80), 10);
File.WriteAllBytes(truncated, header);
Assert.Contains("cut short", await FailAsync(truncated, "glb"));
var badIndex = Path.Combine(folder, "bad.obj");
File.WriteAllText(badIndex, "v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 7\n");
Assert.Contains("vertex 7, which does not exist", await FailAsync(badIndex, "stl"));
var noFaces = Path.Combine(folder, "points.obj");
File.WriteAllText(noFaces, "v 0 0 0\nv 1 0 0\n");
Assert.Contains("contains no triangles", await FailAsync(noFaces, "stl"));
var notPly = Path.Combine(folder, "text.ply");
File.WriteAllText(notPly, "hello");
Assert.Contains("not a PLY file", await FailAsync(notPly, "stl"));
var not3mf = Path.Combine(folder, "text.3mf");
File.WriteAllText(not3mf, "hello");
Assert.Contains("not a 3MF package", await FailAsync(not3mf, "stl"));
var notGltf = Path.Combine(folder, "text.gltf");
File.WriteAllText(notGltf, "{ \"asset\": ");
Assert.Contains("glTF", await FailAsync(notGltf, "stl"));
var draco = Path.Combine(folder, "draco.gltf");
File.WriteAllText(draco, """
{"asset":{"version":"2.0"},"extensionsUsed":["KHR_draco_mesh_compression"],"extensionsRequired":["KHR_draco_mesh_compression"],
"meshes":[{"primitives":[{"attributes":{"POSITION":0},"extensions":{"KHR_draco_mesh_compression":{"bufferView":0,"attributes":{"POSITION":0}}}}]}],
"accessors":[{"componentType":5126,"count":3,"type":"VEC3","min":[0,0,0],"max":[1,1,0]}],
"bufferViews":[{"buffer":0,"byteLength":4}],"buffers":[{"byteLength":4,"uri":"data:application/octet-stream;base64,AAAAAA=="}],
"nodes":[{"mesh":0}],"scenes":[{"nodes":[0]}],"scene":0}
""");
Assert.Contains("Draco-compressed", await FailAsync(draco, "stl"));
}
// ───────────────────────── Helpers ─────────────────────────
private static void Write3mf(string path, string model)
{
using var zip = ZipFile.Open(path, ZipArchiveMode.Create);
using (var writer = new StreamWriter(zip.CreateEntry("_rels/.rels").Open()))
writer.Write("""<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Target="/3D/3dmodel.model" Id="rel0" Type="http://schemas.microsoft.com/3dmanufacturing/2013/01/3dmodel"/></Relationships>""");
using (var writer = new StreamWriter(zip.CreateEntry("3D/3dmodel.model").Open()))
writer.Write(model);
}
/// <summary>The 12 triangles of an axis-aligned box, outward facing.</summary>
private static List<(Vector3, Vector3, Vector3)> Box(Vector3 min, Vector3 max)
{
Vector3 C(int i) => new((i & 1) == 0 ? min.X : max.X, (i & 2) == 0 ? min.Y : max.Y, (i & 4) == 0 ? min.Z : max.Z);
int[][] quads = [[0, 2, 3, 1], [4, 5, 7, 6], [0, 1, 5, 4], [2, 6, 7, 3], [0, 4, 6, 2], [1, 3, 7, 5]];
return [.. quads.SelectMany(q => new[] { (C(q[0]), C(q[1]), C(q[2])), (C(q[0]), C(q[2]), C(q[3])) })];
}
private static void WriteBinaryStl(string path, List<(Vector3, Vector3, Vector3)> triangles)
{
using var stream = File.Create(path);
var header = new byte[84];
BinaryPrimitives.WriteUInt32LittleEndian(header.AsSpan(80), (uint)triangles.Count);
stream.Write(header);
var record = new byte[50];
foreach (var (a, b, c) in triangles)
WriteFacet(stream, record, a, b, c);
}
private static (List<(Vector3 Normal, Vector3 A, Vector3 B, Vector3 C)> Facets, Vector3 Min, Vector3 Max) ReadBinaryStl(string path)
{
var data = File.ReadAllBytes(path);
var count = BinaryPrimitives.ReadInt32LittleEndian(data.AsSpan(80));
var facets = new List<(Vector3, Vector3, Vector3, Vector3)>();
var min = new Vector3(float.MaxValue);
var max = new Vector3(float.MinValue);
for (var i = 0; i < count; i++)
{
var v = new Vector3[4];
for (var k = 0; k < 4; k++)
{
var o = 84 + i * 50 + k * 12;
v[k] = new Vector3(BitConverter.ToSingle(data, o), BitConverter.ToSingle(data, o + 4), BitConverter.ToSingle(data, o + 8));
if (k > 0)
{
min = Vector3.Min(min, v[k]);
max = Vector3.Max(max, v[k]);
}
}
facets.Add((v[0], v[1], v[2], v[3]));
}
return (facets, min, max);
}
}