py3dconvert 1.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- py3dconvert-1.0.1/LICENSE +14 -0
- py3dconvert-1.0.1/MANIFEST.in +4 -0
- py3dconvert-1.0.1/PKG-INFO +106 -0
- py3dconvert-1.0.1/README.md +69 -0
- py3dconvert-1.0.1/docs/API.md +11 -0
- py3dconvert-1.0.1/docs/ROADMAP.md +5 -0
- py3dconvert-1.0.1/examples/quickstart.py +8 -0
- py3dconvert-1.0.1/pyproject.toml +45 -0
- py3dconvert-1.0.1/setup.cfg +4 -0
- py3dconvert-1.0.1/src/py3dconvert/__init__.py +15 -0
- py3dconvert-1.0.1/src/py3dconvert/_backend.py +33 -0
- py3dconvert-1.0.1/src/py3dconvert/cli.py +89 -0
- py3dconvert-1.0.1/src/py3dconvert/converter.py +129 -0
- py3dconvert-1.0.1/src/py3dconvert/exceptions.py +11 -0
- py3dconvert-1.0.1/src/py3dconvert/formats.py +48 -0
- py3dconvert-1.0.1/src/py3dconvert/gui/__init__.py +1 -0
- py3dconvert-1.0.1/src/py3dconvert/gui/app.py +79 -0
- py3dconvert-1.0.1/src/py3dconvert/inspector.py +48 -0
- py3dconvert-1.0.1/src/py3dconvert/optimizer.py +50 -0
- py3dconvert-1.0.1/src/py3dconvert/validator.py +45 -0
- py3dconvert-1.0.1/src/py3dconvert.egg-info/PKG-INFO +106 -0
- py3dconvert-1.0.1/src/py3dconvert.egg-info/SOURCES.txt +26 -0
- py3dconvert-1.0.1/src/py3dconvert.egg-info/dependency_links.txt +1 -0
- py3dconvert-1.0.1/src/py3dconvert.egg-info/entry_points.txt +3 -0
- py3dconvert-1.0.1/src/py3dconvert.egg-info/requires.txt +22 -0
- py3dconvert-1.0.1/src/py3dconvert.egg-info/top_level.txt +1 -0
- py3dconvert-1.0.1/tests/test_core.py +90 -0
- py3dconvert-1.0.1/tests/test_release.py +33 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Py3DConvert contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this
|
|
6
|
+
software and associated documentation files (the "Software"), to deal in the Software
|
|
7
|
+
without restriction, including without limitation the rights to use, copy, modify, merge,
|
|
8
|
+
publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
|
|
9
|
+
to whom the Software is furnished to do so, subject to the following conditions:
|
|
10
|
+
|
|
11
|
+
The above copyright notice and this permission notice shall be included in all copies
|
|
12
|
+
or substantial portions of the Software.
|
|
13
|
+
|
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: py3dconvert
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: A Python toolkit for converting, inspecting, validating and optimizing static 3D assets
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
7
|
+
Classifier: Intended Audience :: Developers
|
|
8
|
+
Classifier: Operating System :: OS Independent
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Requires-Dist: trimesh>=4.4
|
|
19
|
+
Requires-Dist: numpy>=1.24
|
|
20
|
+
Requires-Dist: Pillow>=10.0
|
|
21
|
+
Provides-Extra: gui
|
|
22
|
+
Requires-Dist: PySide6>=6.6; extra == "gui"
|
|
23
|
+
Requires-Dist: pyvista>=0.43; extra == "gui"
|
|
24
|
+
Requires-Dist: pyvistaqt>=0.11; extra == "gui"
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
27
|
+
Requires-Dist: build>=1.2; extra == "dev"
|
|
28
|
+
Requires-Dist: twine>=5.0; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
30
|
+
Provides-Extra: all
|
|
31
|
+
Requires-Dist: PySide6>=6.6; extra == "all"
|
|
32
|
+
Requires-Dist: pyvista>=0.43; extra == "all"
|
|
33
|
+
Requires-Dist: pyvistaqt>=0.11; extra == "all"
|
|
34
|
+
Provides-Extra: test
|
|
35
|
+
Requires-Dist: pytest>=8.0; extra == "test"
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
|
|
38
|
+
# Py3DConvert
|
|
39
|
+
|
|
40
|
+
**Py3DConvert** is a Python library and CLI for converting, inspecting, validating and performing conservative cleanup on static 3D mesh assets. The desktop GUI is optional. It uses the Python `trimesh` ecosystem and does not require Blender, Assimp executables or a REST service.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
python -m pip install py3dconvert
|
|
46
|
+
python -m pip install "py3dconvert[gui]" # optional desktop UI
|
|
47
|
+
python -m pip install "py3dconvert[dev]" # build, tests, lint and PyPI checks
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Python API
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from py3dconvert import Converter, Inspector, Validator, Optimizer
|
|
54
|
+
|
|
55
|
+
result = Converter().convert("model.obj", "model.glb")
|
|
56
|
+
print(result.output, result.output_size)
|
|
57
|
+
|
|
58
|
+
info = Inspector.inspect("model.glb")
|
|
59
|
+
print(info.geometry_count, info.vertex_count, info.face_count, info.bounds)
|
|
60
|
+
|
|
61
|
+
report = Validator.validate("model.glb")
|
|
62
|
+
if not report.valid:
|
|
63
|
+
print(report.errors)
|
|
64
|
+
|
|
65
|
+
Optimizer.repair_basic("model.obj", "model-clean.obj")
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Batch conversion
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
from pathlib import Path
|
|
72
|
+
from py3dconvert import Converter
|
|
73
|
+
|
|
74
|
+
report = Converter().convert_batch(
|
|
75
|
+
Path("models").glob("*.obj"), "converted", "glb",
|
|
76
|
+
continue_on_error=True,
|
|
77
|
+
)
|
|
78
|
+
print(len(report.results), report.errors)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## CLI
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
py3dconvert formats
|
|
85
|
+
py3dconvert capabilities
|
|
86
|
+
py3dconvert convert input.obj output.glb
|
|
87
|
+
py3dconvert inspect model.glb
|
|
88
|
+
py3dconvert validate model.stl --watertight
|
|
89
|
+
py3dconvert batch ./models ./converted --to glb --continue-on-error
|
|
90
|
+
py3dconvert-gui # requires [gui] extra
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Format support and fidelity
|
|
94
|
+
|
|
95
|
+
The exact import/export capabilities depend on the installed `trimesh` version and optional Python dependencies. Run `py3dconvert formats` to see known extensions, `py3dconvert capabilities` to see the installed import/export registrations, or call `format_capabilities()` from Python. A listed extension is not a guarantee that every source/target pair works. Some formats need optional handlers; some exporters produce sidecar files. Always validate outputs in the application that will consume them.
|
|
96
|
+
|
|
97
|
+
This release targets **static triangle-mesh assets**. It does not claim full preservation or conversion of skeletal rigs, skinning, morph targets, animation timelines, CAD parametric history, physics, cameras, lights or every material/shader graph. Material and texture fidelity is format- and backend-dependent. It is not a universal replacement for Blender or specialist CAD tools.
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
## Development
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
python -m pip install -e ".[dev]"
|
|
104
|
+
python -m pytest
|
|
105
|
+
```
|
|
106
|
+
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Py3DConvert
|
|
2
|
+
|
|
3
|
+
**Py3DConvert** is a Python library and CLI for converting, inspecting, validating and performing conservative cleanup on static 3D mesh assets. The desktop GUI is optional. It uses the Python `trimesh` ecosystem and does not require Blender, Assimp executables or a REST service.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
python -m pip install py3dconvert
|
|
9
|
+
python -m pip install "py3dconvert[gui]" # optional desktop UI
|
|
10
|
+
python -m pip install "py3dconvert[dev]" # build, tests, lint and PyPI checks
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Python API
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
from py3dconvert import Converter, Inspector, Validator, Optimizer
|
|
17
|
+
|
|
18
|
+
result = Converter().convert("model.obj", "model.glb")
|
|
19
|
+
print(result.output, result.output_size)
|
|
20
|
+
|
|
21
|
+
info = Inspector.inspect("model.glb")
|
|
22
|
+
print(info.geometry_count, info.vertex_count, info.face_count, info.bounds)
|
|
23
|
+
|
|
24
|
+
report = Validator.validate("model.glb")
|
|
25
|
+
if not report.valid:
|
|
26
|
+
print(report.errors)
|
|
27
|
+
|
|
28
|
+
Optimizer.repair_basic("model.obj", "model-clean.obj")
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Batch conversion
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
from pathlib import Path
|
|
35
|
+
from py3dconvert import Converter
|
|
36
|
+
|
|
37
|
+
report = Converter().convert_batch(
|
|
38
|
+
Path("models").glob("*.obj"), "converted", "glb",
|
|
39
|
+
continue_on_error=True,
|
|
40
|
+
)
|
|
41
|
+
print(len(report.results), report.errors)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## CLI
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
py3dconvert formats
|
|
48
|
+
py3dconvert capabilities
|
|
49
|
+
py3dconvert convert input.obj output.glb
|
|
50
|
+
py3dconvert inspect model.glb
|
|
51
|
+
py3dconvert validate model.stl --watertight
|
|
52
|
+
py3dconvert batch ./models ./converted --to glb --continue-on-error
|
|
53
|
+
py3dconvert-gui # requires [gui] extra
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Format support and fidelity
|
|
57
|
+
|
|
58
|
+
The exact import/export capabilities depend on the installed `trimesh` version and optional Python dependencies. Run `py3dconvert formats` to see known extensions, `py3dconvert capabilities` to see the installed import/export registrations, or call `format_capabilities()` from Python. A listed extension is not a guarantee that every source/target pair works. Some formats need optional handlers; some exporters produce sidecar files. Always validate outputs in the application that will consume them.
|
|
59
|
+
|
|
60
|
+
This release targets **static triangle-mesh assets**. It does not claim full preservation or conversion of skeletal rigs, skinning, morph targets, animation timelines, CAD parametric history, physics, cameras, lights or every material/shader graph. Material and texture fidelity is format- and backend-dependent. It is not a universal replacement for Blender or specialist CAD tools.
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
## Development
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
python -m pip install -e ".[dev]"
|
|
67
|
+
python -m pytest
|
|
68
|
+
```
|
|
69
|
+
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# API reference
|
|
2
|
+
|
|
3
|
+
- `Converter().convert(source, destination, force=False, progress_callback=None)` converts one asset and returns `ConversionResult`.
|
|
4
|
+
- `Converter().convert_batch(sources, output_dir, target_format, overwrite=False, continue_on_error=False)` converts a collection. With `continue_on_error=True`, returns `BatchConversionReport`.
|
|
5
|
+
- `Inspector.inspect(path)` returns counts, bounds, watertight status, scene-node count and basic visual flags.
|
|
6
|
+
- `Validator.validate(path, require_watertight=False, check_degenerate=True)` returns structural errors and warnings.
|
|
7
|
+
- `Optimizer.remove_unreferenced_vertices(source, destination, force=False)` removes unreferenced vertices.
|
|
8
|
+
- `Optimizer.repair_basic(source, destination, force=False)` applies conservative face cleanup and normal repair.
|
|
9
|
+
- `list_formats()` returns known extensions. `format_capabilities()` returns installed backend importer/exporter registrations.
|
|
10
|
+
|
|
11
|
+
All operations work on static mesh geometry. Fidelity for materials, textures and scene metadata depends on the source format and backend exporter. Animation, rigging, skinning, morph targets and parametric CAD data are outside the supported scope.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
# Roadmap
|
|
2
|
+
|
|
3
|
+
The 1.0 API focuses on static triangle meshes. Future work should be added only with format-specific fixtures and automated round-trip tests.
|
|
4
|
+
|
|
5
|
+
Potential extensions: optional adapters for animation-capable formats, texture extraction/rewriting, decimation via an optional simplification dependency, richer material reports, progress events with structured payloads, and CI across supported Python versions and operating systems. These are not claimed as supported by 1.0.0.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
from py3dconvert import Converter, Inspector, Validator
|
|
2
|
+
|
|
3
|
+
result = Converter().convert("model.obj", "converted/model.glb")
|
|
4
|
+
print("Output:", result.output)
|
|
5
|
+
report = Inspector.inspect(result.output)
|
|
6
|
+
print("Vertices:", report.vertex_count, "Faces:", report.face_count)
|
|
7
|
+
print("Bounds:", report.bounds)
|
|
8
|
+
print("Valid:", Validator.validate(result.output).valid)
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "py3dconvert"
|
|
7
|
+
version = "1.0.1"
|
|
8
|
+
description = "A Python toolkit for converting, inspecting, validating and optimizing static 3D assets"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 5 - Production/Stable",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3.10",
|
|
17
|
+
"Programming Language :: Python :: 3.11",
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Programming Language :: Python :: 3.13",
|
|
20
|
+
"Topic :: Multimedia :: Graphics :: 3D Modeling",
|
|
21
|
+
]
|
|
22
|
+
license = "MIT"
|
|
23
|
+
license-files = ["LICENSE"]
|
|
24
|
+
dependencies = ["trimesh>=4.4", "numpy>=1.24", "Pillow>=10.0"]
|
|
25
|
+
|
|
26
|
+
[project.optional-dependencies]
|
|
27
|
+
gui = ["PySide6>=6.6", "pyvista>=0.43", "pyvistaqt>=0.11"]
|
|
28
|
+
dev = ["pytest>=8.0", "build>=1.2", "twine>=5.0", "ruff>=0.5"]
|
|
29
|
+
all = ["PySide6>=6.6", "pyvista>=0.43", "pyvistaqt>=0.11"]
|
|
30
|
+
test = ["pytest>=8.0"]
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
py3dconvert = "py3dconvert.cli:main"
|
|
34
|
+
py3dconvert-gui = "py3dconvert.gui.app:main"
|
|
35
|
+
|
|
36
|
+
[tool.setuptools.packages.find]
|
|
37
|
+
where = ["src"]
|
|
38
|
+
|
|
39
|
+
[tool.pytest.ini_options]
|
|
40
|
+
testpaths = ["tests"]
|
|
41
|
+
addopts = "-ra"
|
|
42
|
+
|
|
43
|
+
[tool.ruff]
|
|
44
|
+
line-length = 100
|
|
45
|
+
target-version = "py310"
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
from .converter import Converter, ConversionResult, BatchConversionReport
|
|
2
|
+
from .inspector import Inspector, InspectionReport
|
|
3
|
+
from .validator import Validator, ValidationReport
|
|
4
|
+
from .optimizer import Optimizer
|
|
5
|
+
from .exceptions import Py3DConvertError, ConversionError, FileFormatError, DependencyError
|
|
6
|
+
|
|
7
|
+
from .formats import list_formats, format_capabilities
|
|
8
|
+
|
|
9
|
+
__version__ = "1.0.0"
|
|
10
|
+
|
|
11
|
+
__all__ = [
|
|
12
|
+
"Converter", "ConversionResult", "BatchConversionReport", "Inspector", "InspectionReport",
|
|
13
|
+
"Validator", "ValidationReport", "Optimizer", "Py3DConvertError",
|
|
14
|
+
"ConversionError", "FileFormatError", "DependencyError", "list_formats", "format_capabilities", "__version__",
|
|
15
|
+
]
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""Internal trimesh integration."""
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
from .exceptions import DependencyError, FileFormatError
|
|
4
|
+
|
|
5
|
+
def require_trimesh():
|
|
6
|
+
try:
|
|
7
|
+
import trimesh
|
|
8
|
+
return trimesh
|
|
9
|
+
except ImportError as exc:
|
|
10
|
+
raise DependencyError("Install the core backend with: python -m pip install py3dconvert") from exc
|
|
11
|
+
|
|
12
|
+
def load_asset(path):
|
|
13
|
+
"""Load an asset as a Scene, retaining node transforms and instancing."""
|
|
14
|
+
path = Path(path)
|
|
15
|
+
if not path.is_file():
|
|
16
|
+
raise FileNotFoundError(f"Input file does not exist: {path}")
|
|
17
|
+
try:
|
|
18
|
+
asset = require_trimesh().load(str(path), force="scene", process=False)
|
|
19
|
+
if asset is None:
|
|
20
|
+
raise ValueError("The importer returned no asset")
|
|
21
|
+
return asset
|
|
22
|
+
except Exception as exc:
|
|
23
|
+
raise FileFormatError(f"Could not read '{path}': {exc}") from exc
|
|
24
|
+
|
|
25
|
+
def scene_geometry(asset):
|
|
26
|
+
"""Yield mesh instances in world coordinates, applying scene graph transforms."""
|
|
27
|
+
trimesh = require_trimesh()
|
|
28
|
+
if isinstance(asset, trimesh.Trimesh):
|
|
29
|
+
yield asset
|
|
30
|
+
elif isinstance(asset, trimesh.Scene):
|
|
31
|
+
for geometry in asset.dump(concatenate=False):
|
|
32
|
+
if isinstance(geometry, trimesh.Trimesh):
|
|
33
|
+
yield geometry
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import argparse
|
|
2
|
+
import json
|
|
3
|
+
from dataclasses import asdict
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
from .converter import Converter
|
|
7
|
+
from .formats import list_formats, format_capabilities
|
|
8
|
+
from .inspector import Inspector
|
|
9
|
+
from .validator import Validator
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def build_parser():
|
|
13
|
+
parser = argparse.ArgumentParser(
|
|
14
|
+
prog="py3dconvert",
|
|
15
|
+
description="Convert, inspect and validate 3D assets.",
|
|
16
|
+
)
|
|
17
|
+
sub = parser.add_subparsers(dest="command", required=True)
|
|
18
|
+
|
|
19
|
+
p = sub.add_parser("convert", help="Convert one 3D file")
|
|
20
|
+
p.add_argument("source")
|
|
21
|
+
p.add_argument("destination")
|
|
22
|
+
p.add_argument("--force", action="store_true")
|
|
23
|
+
|
|
24
|
+
p = sub.add_parser("inspect", help="Inspect a 3D file")
|
|
25
|
+
p.add_argument("source")
|
|
26
|
+
|
|
27
|
+
p = sub.add_parser("validate", help="Validate a 3D file")
|
|
28
|
+
p.add_argument("source")
|
|
29
|
+
p.add_argument("--watertight", action="store_true",
|
|
30
|
+
help="Treat non-watertight meshes as errors")
|
|
31
|
+
|
|
32
|
+
p = sub.add_parser("batch", help="Convert all supported files in a folder")
|
|
33
|
+
p.add_argument("source_dir")
|
|
34
|
+
p.add_argument("output_dir")
|
|
35
|
+
p.add_argument("--to", required=True, dest="target_format")
|
|
36
|
+
p.add_argument("--force", action="store_true")
|
|
37
|
+
p.add_argument("--continue-on-error", action="store_true")
|
|
38
|
+
|
|
39
|
+
sub.add_parser("formats", help="List known file extensions")
|
|
40
|
+
sub.add_parser("capabilities", help="Show installed import/export capabilities")
|
|
41
|
+
return parser
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def main(argv=None):
|
|
45
|
+
args = build_parser().parse_args(argv)
|
|
46
|
+
try:
|
|
47
|
+
if args.command == "convert":
|
|
48
|
+
result = Converter().convert(
|
|
49
|
+
args.source, args.destination, force=args.force
|
|
50
|
+
)
|
|
51
|
+
print(json.dumps(asdict(result), indent=2))
|
|
52
|
+
elif args.command == "inspect":
|
|
53
|
+
print(json.dumps(asdict(Inspector.inspect(args.source)), indent=2))
|
|
54
|
+
elif args.command == "validate":
|
|
55
|
+
report = Validator.validate(
|
|
56
|
+
args.source, require_watertight=args.watertight
|
|
57
|
+
)
|
|
58
|
+
print(json.dumps(asdict(report), indent=2))
|
|
59
|
+
return 0 if report.valid else 2
|
|
60
|
+
elif args.command == "batch":
|
|
61
|
+
source_dir = Path(args.source_dir)
|
|
62
|
+
if not source_dir.is_dir():
|
|
63
|
+
raise NotADirectoryError(source_dir)
|
|
64
|
+
sources = sorted(
|
|
65
|
+
p for p in source_dir.iterdir()
|
|
66
|
+
if p.is_file() and p.suffix.lower() in list_formats()
|
|
67
|
+
)
|
|
68
|
+
report = Converter().convert_batch(
|
|
69
|
+
sources, args.output_dir, args.target_format,
|
|
70
|
+
overwrite=args.force, continue_on_error=args.continue_on_error,
|
|
71
|
+
)
|
|
72
|
+
if hasattr(report, "results"):
|
|
73
|
+
print(json.dumps({
|
|
74
|
+
"converted": [asdict(item) for item in report.results],
|
|
75
|
+
"errors": list(report.errors),
|
|
76
|
+
"success": report.success,
|
|
77
|
+
}, indent=2))
|
|
78
|
+
return 0 if report.success else 2
|
|
79
|
+
print(f"Converted {len(report)} file(s).")
|
|
80
|
+
else:
|
|
81
|
+
print("\\n".join(list_formats()))
|
|
82
|
+
return 0
|
|
83
|
+
except Exception as exc:
|
|
84
|
+
print(f"Error: {exc}")
|
|
85
|
+
return 1
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
if __name__ == "__main__":
|
|
89
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
"""Single-file and batch conversion API."""
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
from typing import Callable
|
|
5
|
+
import os
|
|
6
|
+
import tempfile
|
|
7
|
+
|
|
8
|
+
from ._backend import load_asset
|
|
9
|
+
from .exceptions import ConversionError, FileFormatError
|
|
10
|
+
from .formats import format_capabilities, is_advertised_format
|
|
11
|
+
|
|
12
|
+
@dataclass(frozen=True)
|
|
13
|
+
class ConversionResult:
|
|
14
|
+
source: str
|
|
15
|
+
output: str
|
|
16
|
+
source_format: str
|
|
17
|
+
target_format: str
|
|
18
|
+
output_size: int
|
|
19
|
+
success: bool = True
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True)
|
|
22
|
+
class BatchConversionReport:
|
|
23
|
+
results: tuple[ConversionResult, ...]
|
|
24
|
+
errors: tuple[str, ...]
|
|
25
|
+
@property
|
|
26
|
+
def success(self) -> bool:
|
|
27
|
+
return not self.errors
|
|
28
|
+
|
|
29
|
+
class Converter:
|
|
30
|
+
"""Convert static 3D assets using trimesh; no external executable required."""
|
|
31
|
+
def convert(self, source, destination, *, force=False, embed_textures=True,
|
|
32
|
+
progress_callback: Callable[[str], None] | None = None):
|
|
33
|
+
"""Convert one asset. Texture embedding is controlled by the backend and target format.
|
|
34
|
+
|
|
35
|
+
`embed_textures` is retained for API compatibility; trimesh's exporter
|
|
36
|
+
determines whether textures are embedded or emitted as sidecar files.
|
|
37
|
+
"""
|
|
38
|
+
source, destination = Path(source), Path(destination)
|
|
39
|
+
if not source.is_file():
|
|
40
|
+
raise FileNotFoundError(f"Input file does not exist: {source}")
|
|
41
|
+
if source.resolve() == destination.resolve():
|
|
42
|
+
raise ConversionError("Source and destination must be different files.")
|
|
43
|
+
if destination.exists() and not force:
|
|
44
|
+
raise FileExistsError(f"{destination} already exists; pass force=True to overwrite.")
|
|
45
|
+
extension = destination.suffix.lstrip(".").lower()
|
|
46
|
+
capabilities = format_capabilities().get("." + extension, {}) if extension else {}
|
|
47
|
+
if not extension or not is_advertised_format(extension) or not capabilities.get("export", False):
|
|
48
|
+
raise FileFormatError(
|
|
49
|
+
f"No exporter for '{destination.suffix}' is available in this installation of trimesh."
|
|
50
|
+
)
|
|
51
|
+
if progress_callback: progress_callback(f"Loading {source.name}")
|
|
52
|
+
asset = load_asset(source)
|
|
53
|
+
destination.parent.mkdir(parents=True, exist_ok=True)
|
|
54
|
+
# Export into a same-directory temporary file then atomically replace the
|
|
55
|
+
# destination. This prevents half-written outputs after a failed export.
|
|
56
|
+
temp_path = None
|
|
57
|
+
try:
|
|
58
|
+
fd, temp_name = tempfile.mkstemp(prefix=f".{destination.stem}.", suffix=destination.suffix, dir=destination.parent)
|
|
59
|
+
os.close(fd)
|
|
60
|
+
temp_path = Path(temp_name)
|
|
61
|
+
if progress_callback: progress_callback(f"Exporting as {extension.upper()}")
|
|
62
|
+
payload = asset.export(file_type=extension)
|
|
63
|
+
if isinstance(payload, dict):
|
|
64
|
+
# Multi-file formats (for example glTF) are written to a staging
|
|
65
|
+
# directory; preserve sidecar files alongside the primary file.
|
|
66
|
+
temp_path.unlink(missing_ok=True)
|
|
67
|
+
staging = Path(tempfile.mkdtemp(prefix=f".{destination.stem}.", dir=destination.parent))
|
|
68
|
+
try:
|
|
69
|
+
for name, content in payload.items():
|
|
70
|
+
out = staging / Path(name).name
|
|
71
|
+
out.write_bytes(content if isinstance(content, bytes) else str(content).encode())
|
|
72
|
+
candidates = list(staging.iterdir())
|
|
73
|
+
primary = next((x for x in candidates if x.suffix.lower() == destination.suffix.lower()), None)
|
|
74
|
+
if primary is None:
|
|
75
|
+
raise RuntimeError("Backend did not return a primary output matching the requested extension")
|
|
76
|
+
for item in candidates:
|
|
77
|
+
target = destination.parent / item.name
|
|
78
|
+
if target.exists() and not force and target != destination:
|
|
79
|
+
raise FileExistsError(target)
|
|
80
|
+
for item in candidates:
|
|
81
|
+
target = destination.parent / (destination.name if item == primary else item.name)
|
|
82
|
+
os.replace(item, target)
|
|
83
|
+
finally:
|
|
84
|
+
for item in staging.iterdir(): item.unlink(missing_ok=True)
|
|
85
|
+
staging.rmdir()
|
|
86
|
+
elif isinstance(payload, (bytes, bytearray)):
|
|
87
|
+
temp_path.write_bytes(payload)
|
|
88
|
+
os.replace(temp_path, destination)
|
|
89
|
+
elif isinstance(payload, str):
|
|
90
|
+
temp_path.write_text(payload, encoding="utf-8")
|
|
91
|
+
os.replace(temp_path, destination)
|
|
92
|
+
else:
|
|
93
|
+
asset.export(str(temp_path), file_type=extension)
|
|
94
|
+
if not temp_path.is_file() or temp_path.stat().st_size == 0:
|
|
95
|
+
raise RuntimeError("Backend did not create a non-empty output file")
|
|
96
|
+
os.replace(temp_path, destination)
|
|
97
|
+
if not destination.is_file() or destination.stat().st_size == 0:
|
|
98
|
+
raise RuntimeError("Conversion produced no output file")
|
|
99
|
+
if progress_callback: progress_callback(f"Created {destination.name}")
|
|
100
|
+
return ConversionResult(str(source), str(destination), source.suffix.lower().lstrip("."), extension, destination.stat().st_size)
|
|
101
|
+
except Exception as exc:
|
|
102
|
+
raise ConversionError(f"Conversion failed: {exc}") from exc
|
|
103
|
+
finally:
|
|
104
|
+
if temp_path is not None: temp_path.unlink(missing_ok=True)
|
|
105
|
+
|
|
106
|
+
def convert_batch(self, sources, output_dir, target_format, *, overwrite=False,
|
|
107
|
+
continue_on_error=False, progress_callback=None):
|
|
108
|
+
output_dir = Path(output_dir)
|
|
109
|
+
extension = str(target_format).lower().lstrip(".")
|
|
110
|
+
if not format_capabilities().get("." + extension, {}).get("export", False):
|
|
111
|
+
raise FileFormatError(f"No exporter for '.{extension}' is available in this installation of trimesh.")
|
|
112
|
+
sources = list(sources)
|
|
113
|
+
output_dir.mkdir(parents=True, exist_ok=True)
|
|
114
|
+
results, errors, seen = [], [], set()
|
|
115
|
+
for index, source in enumerate(sources, 1):
|
|
116
|
+
source = Path(source)
|
|
117
|
+
output = output_dir / f"{source.stem}.{extension}"
|
|
118
|
+
if output.name.casefold() in seen:
|
|
119
|
+
message = f"Output name collision for {source}: {output.name}"
|
|
120
|
+
if not continue_on_error: raise ConversionError(message)
|
|
121
|
+
errors.append(message); continue
|
|
122
|
+
seen.add(output.name.casefold())
|
|
123
|
+
if progress_callback: progress_callback(f"[{index}/{len(sources)}] {source.name}")
|
|
124
|
+
try:
|
|
125
|
+
results.append(self.convert(source, output, force=overwrite, progress_callback=progress_callback))
|
|
126
|
+
except Exception as exc:
|
|
127
|
+
if not continue_on_error: raise
|
|
128
|
+
errors.append(f"{source}: {exc}")
|
|
129
|
+
return BatchConversionReport(tuple(results), tuple(errors)) if continue_on_error else results
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
class Py3DConvertError(Exception):
|
|
2
|
+
"Base exception for this package."
|
|
3
|
+
|
|
4
|
+
class ConversionError(Py3DConvertError):
|
|
5
|
+
"Raised when conversion fails."
|
|
6
|
+
|
|
7
|
+
class FileFormatError(Py3DConvertError):
|
|
8
|
+
"Raised for invalid or unsupported file formats."
|
|
9
|
+
|
|
10
|
+
class DependencyError(Py3DConvertError):
|
|
11
|
+
"Raised when a required dependency is missing."
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""Runtime format capability discovery."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from ._backend import require_trimesh
|
|
5
|
+
|
|
6
|
+
# Known static-mesh formats. Runtime capability reporting below distinguishes
|
|
7
|
+
# formats that this installed trimesh build can actually import/export.
|
|
8
|
+
FALLBACK_EXTENSIONS = {
|
|
9
|
+
".obj", ".stl", ".ply", ".glb", ".gltf", ".off", ".3mf",
|
|
10
|
+
".dae", ".3ds", ".xyz", ".vtk", ".msh", ".json",
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def normalize_extension(value: str) -> str:
|
|
15
|
+
value = str(value).lower().strip()
|
|
16
|
+
return value if value.startswith(".") else "." + value
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _runtime_maps():
|
|
20
|
+
trimesh = require_trimesh()
|
|
21
|
+
importer = set()
|
|
22
|
+
try:
|
|
23
|
+
importer = {str(x).lower().lstrip(".") for x in trimesh.exchange.load.available_formats()}
|
|
24
|
+
except Exception:
|
|
25
|
+
pass
|
|
26
|
+
exporter = set(getattr(trimesh.exchange.export, "_mesh_exporters", {}))
|
|
27
|
+
return importer, exporter
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def list_formats() -> list[str]:
|
|
31
|
+
"""Return the curated set of known static-mesh extensions."""
|
|
32
|
+
return sorted(FALLBACK_EXTENSIONS)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def is_advertised_format(value: str) -> bool:
|
|
36
|
+
return normalize_extension(value) in set(list_formats())
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def format_capabilities() -> dict[str, dict[str, bool]]:
|
|
40
|
+
"""Return actual importer/exporter registration hints for this installation."""
|
|
41
|
+
importer, exporter = _runtime_maps()
|
|
42
|
+
return {
|
|
43
|
+
ext: {
|
|
44
|
+
"import": ext.lstrip(".") in importer,
|
|
45
|
+
"export": ext.lstrip(".") in exporter,
|
|
46
|
+
}
|
|
47
|
+
for ext in list_formats()
|
|
48
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Optional desktop interface."""
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
from pathlib import Path
|
|
2
|
+
|
|
3
|
+
def main():
|
|
4
|
+
try:
|
|
5
|
+
from PySide6.QtWidgets import (
|
|
6
|
+
QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout,
|
|
7
|
+
QLabel, QLineEdit, QPushButton, QFileDialog, QComboBox, QTextEdit,
|
|
8
|
+
QMessageBox
|
|
9
|
+
)
|
|
10
|
+
except ImportError as exc:
|
|
11
|
+
raise SystemExit('Install the GUI extra: pip install "py3dconvert[gui]"') from exc
|
|
12
|
+
|
|
13
|
+
from py3dconvert import Converter
|
|
14
|
+
from py3dconvert.formats import list_formats
|
|
15
|
+
|
|
16
|
+
class MainWindow(QMainWindow):
|
|
17
|
+
def __init__(self):
|
|
18
|
+
super().__init__()
|
|
19
|
+
self.setWindowTitle("Py3DConvert")
|
|
20
|
+
self.resize(700, 400)
|
|
21
|
+
root = QWidget()
|
|
22
|
+
layout = QVBoxLayout(root)
|
|
23
|
+
layout.addWidget(QLabel("Py3DConvert — 3D file converter"))
|
|
24
|
+
self.source = QLineEdit()
|
|
25
|
+
self.source.setPlaceholderText("Source file")
|
|
26
|
+
row = QHBoxLayout()
|
|
27
|
+
row.addWidget(self.source)
|
|
28
|
+
browse = QPushButton("Browse…")
|
|
29
|
+
browse.clicked.connect(self.choose_source)
|
|
30
|
+
row.addWidget(browse)
|
|
31
|
+
layout.addLayout(row)
|
|
32
|
+
self.destination = QLineEdit()
|
|
33
|
+
self.destination.setPlaceholderText("Destination file")
|
|
34
|
+
row = QHBoxLayout()
|
|
35
|
+
row.addWidget(self.destination)
|
|
36
|
+
save = QPushButton("Save as…")
|
|
37
|
+
save.clicked.connect(self.choose_destination)
|
|
38
|
+
row.addWidget(save)
|
|
39
|
+
layout.addLayout(row)
|
|
40
|
+
self.format = QComboBox()
|
|
41
|
+
self.format.addItems([x[1:] for x in list_formats()])
|
|
42
|
+
layout.addWidget(QLabel("Output format"))
|
|
43
|
+
layout.addWidget(self.format)
|
|
44
|
+
run = QPushButton("Convert")
|
|
45
|
+
run.clicked.connect(self.convert)
|
|
46
|
+
layout.addWidget(run)
|
|
47
|
+
self.log = QTextEdit()
|
|
48
|
+
self.log.setReadOnly(True)
|
|
49
|
+
layout.addWidget(self.log)
|
|
50
|
+
self.setCentralWidget(root)
|
|
51
|
+
|
|
52
|
+
def choose_source(self):
|
|
53
|
+
path, _ = QFileDialog.getOpenFileName(self, "Select 3D file")
|
|
54
|
+
if path:
|
|
55
|
+
self.source.setText(path)
|
|
56
|
+
if not self.destination.text():
|
|
57
|
+
self.destination.setText(str(Path(path).with_suffix("." + self.format.currentText())))
|
|
58
|
+
|
|
59
|
+
def choose_destination(self):
|
|
60
|
+
path, _ = QFileDialog.getSaveFileName(self, "Save converted file")
|
|
61
|
+
if path:
|
|
62
|
+
self.destination.setText(path)
|
|
63
|
+
|
|
64
|
+
def convert(self):
|
|
65
|
+
try:
|
|
66
|
+
result = Converter().convert(self.source.text(), self.destination.text())
|
|
67
|
+
self.log.append(f"Success: {result.output} ({result.output_size} bytes)")
|
|
68
|
+
QMessageBox.information(self, "Done", "Conversion completed.")
|
|
69
|
+
except Exception as exc:
|
|
70
|
+
self.log.append(f"Error: {exc}")
|
|
71
|
+
QMessageBox.critical(self, "Conversion failed", str(exc))
|
|
72
|
+
|
|
73
|
+
app = QApplication.instance() or QApplication([])
|
|
74
|
+
window = MainWindow()
|
|
75
|
+
window.show()
|
|
76
|
+
return app.exec()
|
|
77
|
+
|
|
78
|
+
if __name__ == "__main__":
|
|
79
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""Asset inspection."""
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
from ._backend import load_asset, require_trimesh, scene_geometry
|
|
5
|
+
|
|
6
|
+
@dataclass(frozen=True)
|
|
7
|
+
class InspectionReport:
|
|
8
|
+
path: str
|
|
9
|
+
file_size: int
|
|
10
|
+
geometry_count: int
|
|
11
|
+
vertex_count: int
|
|
12
|
+
face_count: int
|
|
13
|
+
bounds: tuple | None
|
|
14
|
+
extents: tuple | None
|
|
15
|
+
is_watertight: bool | None
|
|
16
|
+
materials: tuple[str, ...]
|
|
17
|
+
scene_nodes: int = 0
|
|
18
|
+
has_texture_visuals: bool = False
|
|
19
|
+
has_vertex_colors: bool = False
|
|
20
|
+
def to_dict(self):
|
|
21
|
+
from dataclasses import asdict
|
|
22
|
+
return asdict(self)
|
|
23
|
+
|
|
24
|
+
class Inspector:
|
|
25
|
+
@staticmethod
|
|
26
|
+
def inspect(path):
|
|
27
|
+
path = Path(path)
|
|
28
|
+
asset = load_asset(path)
|
|
29
|
+
meshes = list(scene_geometry(asset))
|
|
30
|
+
vertices = sum(len(m.vertices) for m in meshes)
|
|
31
|
+
faces = sum(len(m.faces) for m in meshes)
|
|
32
|
+
bounds = extents = watertight = None
|
|
33
|
+
if meshes:
|
|
34
|
+
combined = require_trimesh().util.concatenate(meshes)
|
|
35
|
+
bounds = tuple(tuple(float(x) for x in row) for row in combined.bounds)
|
|
36
|
+
extents = tuple(float(x) for x in combined.extents)
|
|
37
|
+
watertight = bool(combined.is_watertight)
|
|
38
|
+
names, textured, vertex_colors = set(), False, False
|
|
39
|
+
for mesh in meshes:
|
|
40
|
+
visual = getattr(mesh, "visual", None)
|
|
41
|
+
material = getattr(visual, "material", None)
|
|
42
|
+
name = getattr(material, "name", None)
|
|
43
|
+
if name: names.add(str(name))
|
|
44
|
+
textured |= getattr(visual, "kind", None) == "texture"
|
|
45
|
+
vertex_colors |= getattr(visual, "kind", None) == "vertex"
|
|
46
|
+
nodes = len(asset.graph.nodes) if hasattr(asset, "graph") else 1
|
|
47
|
+
return InspectionReport(str(path), path.stat().st_size, len(meshes), vertices, faces,
|
|
48
|
+
bounds, extents, watertight, tuple(sorted(names)), nodes, textured, vertex_colors)
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Conservative mesh cleanup utilities."""
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
from ._backend import load_asset, require_trimesh
|
|
4
|
+
from .exceptions import ConversionError, FileFormatError
|
|
5
|
+
from .formats import format_capabilities
|
|
6
|
+
|
|
7
|
+
class Optimizer:
|
|
8
|
+
@staticmethod
|
|
9
|
+
def remove_unreferenced_vertices(source, destination, *, force=False):
|
|
10
|
+
return Optimizer._clean(source, destination, force=force, repair=False)
|
|
11
|
+
@staticmethod
|
|
12
|
+
def repair_basic(source, destination, *, force=False):
|
|
13
|
+
return Optimizer._clean(source, destination, force=force, repair=True)
|
|
14
|
+
@staticmethod
|
|
15
|
+
def _clean(source, destination, *, force, repair):
|
|
16
|
+
source, destination = Path(source), Path(destination)
|
|
17
|
+
if source.resolve() == destination.resolve(): raise ConversionError("Source and destination must differ.")
|
|
18
|
+
if destination.exists() and not force: raise FileExistsError(destination)
|
|
19
|
+
extension = destination.suffix.lstrip(".").lower()
|
|
20
|
+
if not format_capabilities().get("." + extension, {}).get("export", False):
|
|
21
|
+
raise FileFormatError(f"No exporter for '.{extension}' is available in this installation of trimesh.")
|
|
22
|
+
asset = load_asset(source)
|
|
23
|
+
trimesh = require_trimesh()
|
|
24
|
+
# Work on the scene itself so graph transforms, node names and geometry
|
|
25
|
+
# instances are not flattened or silently repositioned.
|
|
26
|
+
if isinstance(asset, trimesh.Trimesh): meshes = [asset]
|
|
27
|
+
else: meshes = list(asset.geometry.values())
|
|
28
|
+
if not meshes: raise ConversionError("No mesh geometry found.")
|
|
29
|
+
for mesh in meshes:
|
|
30
|
+
if not isinstance(mesh, trimesh.Trimesh): continue
|
|
31
|
+
if repair:
|
|
32
|
+
mesh.update_faces(mesh.unique_faces())
|
|
33
|
+
try: mesh.update_faces(mesh.nondegenerate_faces())
|
|
34
|
+
except Exception: pass
|
|
35
|
+
mesh.remove_unreferenced_vertices()
|
|
36
|
+
mesh.fix_normals()
|
|
37
|
+
else: mesh.remove_unreferenced_vertices()
|
|
38
|
+
destination.parent.mkdir(parents=True, exist_ok=True)
|
|
39
|
+
try:
|
|
40
|
+
payload = asset.export(file_type=destination.suffix.lstrip(".").lower())
|
|
41
|
+
if isinstance(payload, bytes): destination.write_bytes(payload)
|
|
42
|
+
elif isinstance(payload, str): destination.write_text(payload, encoding="utf-8")
|
|
43
|
+
elif isinstance(payload, dict):
|
|
44
|
+
for name, content in payload.items():
|
|
45
|
+
out = destination.parent / Path(name).name
|
|
46
|
+
out.write_bytes(content if isinstance(content, bytes) else str(content).encode())
|
|
47
|
+
else: asset.export(str(destination))
|
|
48
|
+
except Exception as exc: raise ConversionError(f"Could not export cleaned mesh: {exc}") from exc
|
|
49
|
+
if not destination.exists(): raise ConversionError("Backend did not create the optimized output.")
|
|
50
|
+
return destination
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""Structural validation for static triangle meshes."""
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
import numpy as np
|
|
5
|
+
from ._backend import load_asset, scene_geometry
|
|
6
|
+
|
|
7
|
+
@dataclass(frozen=True)
|
|
8
|
+
class ValidationReport:
|
|
9
|
+
path: str
|
|
10
|
+
valid: bool
|
|
11
|
+
errors: tuple[str, ...]
|
|
12
|
+
warnings: tuple[str, ...]
|
|
13
|
+
def to_dict(self):
|
|
14
|
+
from dataclasses import asdict
|
|
15
|
+
return asdict(self)
|
|
16
|
+
|
|
17
|
+
class Validator:
|
|
18
|
+
@staticmethod
|
|
19
|
+
def validate(path, *, require_watertight=False, check_degenerate=True):
|
|
20
|
+
path = Path(path)
|
|
21
|
+
errors, warnings = [], []
|
|
22
|
+
try:
|
|
23
|
+
meshes = list(scene_geometry(load_asset(path)))
|
|
24
|
+
if not meshes: errors.append("No triangle mesh geometry found.")
|
|
25
|
+
for index, mesh in enumerate(meshes):
|
|
26
|
+
if len(mesh.vertices) == 0: errors.append(f"Geometry {index} has no vertices.")
|
|
27
|
+
if len(mesh.faces) == 0: errors.append(f"Geometry {index} has no faces.")
|
|
28
|
+
if len(mesh.vertices) and not np.isfinite(mesh.vertices).all():
|
|
29
|
+
errors.append(f"Geometry {index} contains non-finite vertex coordinates.")
|
|
30
|
+
if len(mesh.faces) and (mesh.faces.min() < 0 or mesh.faces.max() >= len(mesh.vertices)):
|
|
31
|
+
errors.append(f"Geometry {index} contains out-of-range face indices.")
|
|
32
|
+
if check_degenerate and len(mesh.faces):
|
|
33
|
+
try:
|
|
34
|
+
count = int((~mesh.nondegenerate_faces()).sum())
|
|
35
|
+
if count: warnings.append(f"Geometry {index} contains {count} degenerate face(s).")
|
|
36
|
+
except Exception: pass
|
|
37
|
+
topology = mesh.copy()
|
|
38
|
+
try: topology.merge_vertices()
|
|
39
|
+
except Exception: pass
|
|
40
|
+
if not topology.is_watertight:
|
|
41
|
+
message = f"Geometry {index} is not watertight."
|
|
42
|
+
(errors if require_watertight else warnings).append(message)
|
|
43
|
+
except Exception as exc:
|
|
44
|
+
errors.append(str(exc))
|
|
45
|
+
return ValidationReport(str(path), not errors, tuple(errors), tuple(warnings))
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: py3dconvert
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: A Python toolkit for converting, inspecting, validating and optimizing static 3D assets
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
7
|
+
Classifier: Intended Audience :: Developers
|
|
8
|
+
Classifier: Operating System :: OS Independent
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Requires-Dist: trimesh>=4.4
|
|
19
|
+
Requires-Dist: numpy>=1.24
|
|
20
|
+
Requires-Dist: Pillow>=10.0
|
|
21
|
+
Provides-Extra: gui
|
|
22
|
+
Requires-Dist: PySide6>=6.6; extra == "gui"
|
|
23
|
+
Requires-Dist: pyvista>=0.43; extra == "gui"
|
|
24
|
+
Requires-Dist: pyvistaqt>=0.11; extra == "gui"
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
27
|
+
Requires-Dist: build>=1.2; extra == "dev"
|
|
28
|
+
Requires-Dist: twine>=5.0; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
30
|
+
Provides-Extra: all
|
|
31
|
+
Requires-Dist: PySide6>=6.6; extra == "all"
|
|
32
|
+
Requires-Dist: pyvista>=0.43; extra == "all"
|
|
33
|
+
Requires-Dist: pyvistaqt>=0.11; extra == "all"
|
|
34
|
+
Provides-Extra: test
|
|
35
|
+
Requires-Dist: pytest>=8.0; extra == "test"
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
|
|
38
|
+
# Py3DConvert
|
|
39
|
+
|
|
40
|
+
**Py3DConvert** is a Python library and CLI for converting, inspecting, validating and performing conservative cleanup on static 3D mesh assets. The desktop GUI is optional. It uses the Python `trimesh` ecosystem and does not require Blender, Assimp executables or a REST service.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
python -m pip install py3dconvert
|
|
46
|
+
python -m pip install "py3dconvert[gui]" # optional desktop UI
|
|
47
|
+
python -m pip install "py3dconvert[dev]" # build, tests, lint and PyPI checks
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Python API
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from py3dconvert import Converter, Inspector, Validator, Optimizer
|
|
54
|
+
|
|
55
|
+
result = Converter().convert("model.obj", "model.glb")
|
|
56
|
+
print(result.output, result.output_size)
|
|
57
|
+
|
|
58
|
+
info = Inspector.inspect("model.glb")
|
|
59
|
+
print(info.geometry_count, info.vertex_count, info.face_count, info.bounds)
|
|
60
|
+
|
|
61
|
+
report = Validator.validate("model.glb")
|
|
62
|
+
if not report.valid:
|
|
63
|
+
print(report.errors)
|
|
64
|
+
|
|
65
|
+
Optimizer.repair_basic("model.obj", "model-clean.obj")
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Batch conversion
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
from pathlib import Path
|
|
72
|
+
from py3dconvert import Converter
|
|
73
|
+
|
|
74
|
+
report = Converter().convert_batch(
|
|
75
|
+
Path("models").glob("*.obj"), "converted", "glb",
|
|
76
|
+
continue_on_error=True,
|
|
77
|
+
)
|
|
78
|
+
print(len(report.results), report.errors)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## CLI
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
py3dconvert formats
|
|
85
|
+
py3dconvert capabilities
|
|
86
|
+
py3dconvert convert input.obj output.glb
|
|
87
|
+
py3dconvert inspect model.glb
|
|
88
|
+
py3dconvert validate model.stl --watertight
|
|
89
|
+
py3dconvert batch ./models ./converted --to glb --continue-on-error
|
|
90
|
+
py3dconvert-gui # requires [gui] extra
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Format support and fidelity
|
|
94
|
+
|
|
95
|
+
The exact import/export capabilities depend on the installed `trimesh` version and optional Python dependencies. Run `py3dconvert formats` to see known extensions, `py3dconvert capabilities` to see the installed import/export registrations, or call `format_capabilities()` from Python. A listed extension is not a guarantee that every source/target pair works. Some formats need optional handlers; some exporters produce sidecar files. Always validate outputs in the application that will consume them.
|
|
96
|
+
|
|
97
|
+
This release targets **static triangle-mesh assets**. It does not claim full preservation or conversion of skeletal rigs, skinning, morph targets, animation timelines, CAD parametric history, physics, cameras, lights or every material/shader graph. Material and texture fidelity is format- and backend-dependent. It is not a universal replacement for Blender or specialist CAD tools.
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
## Development
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
python -m pip install -e ".[dev]"
|
|
104
|
+
python -m pytest
|
|
105
|
+
```
|
|
106
|
+
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
MANIFEST.in
|
|
3
|
+
README.md
|
|
4
|
+
pyproject.toml
|
|
5
|
+
docs/API.md
|
|
6
|
+
docs/ROADMAP.md
|
|
7
|
+
examples/quickstart.py
|
|
8
|
+
src/py3dconvert/__init__.py
|
|
9
|
+
src/py3dconvert/_backend.py
|
|
10
|
+
src/py3dconvert/cli.py
|
|
11
|
+
src/py3dconvert/converter.py
|
|
12
|
+
src/py3dconvert/exceptions.py
|
|
13
|
+
src/py3dconvert/formats.py
|
|
14
|
+
src/py3dconvert/inspector.py
|
|
15
|
+
src/py3dconvert/optimizer.py
|
|
16
|
+
src/py3dconvert/validator.py
|
|
17
|
+
src/py3dconvert.egg-info/PKG-INFO
|
|
18
|
+
src/py3dconvert.egg-info/SOURCES.txt
|
|
19
|
+
src/py3dconvert.egg-info/dependency_links.txt
|
|
20
|
+
src/py3dconvert.egg-info/entry_points.txt
|
|
21
|
+
src/py3dconvert.egg-info/requires.txt
|
|
22
|
+
src/py3dconvert.egg-info/top_level.txt
|
|
23
|
+
src/py3dconvert/gui/__init__.py
|
|
24
|
+
src/py3dconvert/gui/app.py
|
|
25
|
+
tests/test_core.py
|
|
26
|
+
tests/test_release.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
trimesh>=4.4
|
|
2
|
+
numpy>=1.24
|
|
3
|
+
Pillow>=10.0
|
|
4
|
+
|
|
5
|
+
[all]
|
|
6
|
+
PySide6>=6.6
|
|
7
|
+
pyvista>=0.43
|
|
8
|
+
pyvistaqt>=0.11
|
|
9
|
+
|
|
10
|
+
[dev]
|
|
11
|
+
pytest>=8.0
|
|
12
|
+
build>=1.2
|
|
13
|
+
twine>=5.0
|
|
14
|
+
ruff>=0.5
|
|
15
|
+
|
|
16
|
+
[gui]
|
|
17
|
+
PySide6>=6.6
|
|
18
|
+
pyvista>=0.43
|
|
19
|
+
pyvistaqt>=0.11
|
|
20
|
+
|
|
21
|
+
[test]
|
|
22
|
+
pytest>=8.0
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
py3dconvert
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
trimesh = pytest.importorskip("trimesh")
|
|
3
|
+
from py3dconvert import Converter, Inspector, Validator
|
|
4
|
+
from py3dconvert.exceptions import ConversionError
|
|
5
|
+
|
|
6
|
+
def create_box(path):
|
|
7
|
+
trimesh.creation.box().export(path)
|
|
8
|
+
|
|
9
|
+
def test_obj_to_stl(tmp_path):
|
|
10
|
+
src, dst = tmp_path / "box.obj", tmp_path / "box.stl"
|
|
11
|
+
create_box(src)
|
|
12
|
+
result = Converter().convert(src, dst)
|
|
13
|
+
assert result.success and dst.exists() and dst.stat().st_size > 0
|
|
14
|
+
|
|
15
|
+
def test_inspector(tmp_path):
|
|
16
|
+
src = tmp_path / "box.stl"
|
|
17
|
+
create_box(src)
|
|
18
|
+
report = Inspector.inspect(src)
|
|
19
|
+
assert report.vertex_count > 0
|
|
20
|
+
assert report.face_count > 0
|
|
21
|
+
|
|
22
|
+
def test_validator(tmp_path):
|
|
23
|
+
src = tmp_path / "box.stl"
|
|
24
|
+
create_box(src)
|
|
25
|
+
assert Validator.validate(src, require_watertight=True).valid
|
|
26
|
+
|
|
27
|
+
def test_no_overwrite_by_default(tmp_path):
|
|
28
|
+
src, dst = tmp_path / "box.obj", tmp_path / "box.stl"
|
|
29
|
+
create_box(src)
|
|
30
|
+
dst.write_text("keep")
|
|
31
|
+
with pytest.raises(FileExistsError):
|
|
32
|
+
Converter().convert(src, dst)
|
|
33
|
+
assert dst.read_text() == "keep"
|
|
34
|
+
|
|
35
|
+
def test_same_path_rejected(tmp_path):
|
|
36
|
+
src = tmp_path / "box.obj"
|
|
37
|
+
create_box(src)
|
|
38
|
+
with pytest.raises(ConversionError):
|
|
39
|
+
Converter().convert(src, src)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def test_scene_transforms_are_applied_during_inspection(tmp_path):
|
|
44
|
+
scene = trimesh.Scene()
|
|
45
|
+
scene.add_geometry(
|
|
46
|
+
trimesh.creation.box(),
|
|
47
|
+
node_name="left",
|
|
48
|
+
transform=trimesh.transformations.translation_matrix([10, 0, 0]),
|
|
49
|
+
)
|
|
50
|
+
scene.add_geometry(
|
|
51
|
+
trimesh.creation.box(),
|
|
52
|
+
node_name="right",
|
|
53
|
+
transform=trimesh.transformations.translation_matrix([-10, 0, 0]),
|
|
54
|
+
)
|
|
55
|
+
src = tmp_path / "two_objects.glb"
|
|
56
|
+
scene.export(src)
|
|
57
|
+
|
|
58
|
+
report = Inspector.inspect(src)
|
|
59
|
+
assert report.geometry_count == 2
|
|
60
|
+
assert report.bounds[0][0] < -10
|
|
61
|
+
assert report.bounds[1][0] > 10
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def test_batch_continue_on_error(tmp_path):
|
|
65
|
+
from py3dconvert import BatchConversionReport
|
|
66
|
+
|
|
67
|
+
source_dir = tmp_path / "input"
|
|
68
|
+
output_dir = tmp_path / "output"
|
|
69
|
+
source_dir.mkdir()
|
|
70
|
+
create_box(source_dir / "good.obj")
|
|
71
|
+
(source_dir / "missing.obj").write_text("not a mesh")
|
|
72
|
+
|
|
73
|
+
report = Converter().convert_batch(
|
|
74
|
+
[source_dir / "good.obj", source_dir / "missing.obj"],
|
|
75
|
+
output_dir,
|
|
76
|
+
"stl",
|
|
77
|
+
continue_on_error=True,
|
|
78
|
+
)
|
|
79
|
+
assert isinstance(report, BatchConversionReport)
|
|
80
|
+
assert len(report.results) == 1
|
|
81
|
+
assert len(report.errors) == 1
|
|
82
|
+
assert not report.success
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def test_cli_validate(tmp_path):
|
|
86
|
+
from py3dconvert.cli import main
|
|
87
|
+
|
|
88
|
+
src = tmp_path / "box.stl"
|
|
89
|
+
create_box(src)
|
|
90
|
+
assert main(["validate", str(src)]) == 0
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
trimesh = pytest.importorskip("trimesh")
|
|
3
|
+
from py3dconvert import Converter, Inspector, Validator, format_capabilities
|
|
4
|
+
from py3dconvert.exceptions import ConversionError
|
|
5
|
+
|
|
6
|
+
def box(path): trimesh.creation.box().export(path)
|
|
7
|
+
|
|
8
|
+
def test_inspection_exposes_nodes_and_visual_flags(tmp_path):
|
|
9
|
+
src = tmp_path / "box.glb"; box(src)
|
|
10
|
+
report = Inspector.inspect(src)
|
|
11
|
+
assert report.geometry_count >= 1 and report.scene_nodes >= 1
|
|
12
|
+
assert report.vertex_count > 0 and report.face_count > 0
|
|
13
|
+
|
|
14
|
+
def test_validation_rejects_invalid_file(tmp_path):
|
|
15
|
+
src = tmp_path / "bad.obj"; src.write_text("this is not an obj mesh")
|
|
16
|
+
report = Validator.validate(src)
|
|
17
|
+
assert not report.valid and report.errors
|
|
18
|
+
|
|
19
|
+
def test_conversion_is_not_overwritten_on_backend_failure(tmp_path):
|
|
20
|
+
src = tmp_path / "box.obj"; box(src)
|
|
21
|
+
dst = tmp_path / "out.stl"; dst.write_text("original")
|
|
22
|
+
with pytest.raises(FileExistsError): Converter().convert(src, dst)
|
|
23
|
+
assert dst.read_text() == "original"
|
|
24
|
+
|
|
25
|
+
def test_batch_detects_stem_collision(tmp_path):
|
|
26
|
+
a=tmp_path/"a"; b=tmp_path/"b"; out=tmp_path/"out"; a.mkdir(); b.mkdir()
|
|
27
|
+
box(a/"same.obj"); box(b/"same.ply")
|
|
28
|
+
report=Converter().convert_batch([a/"same.obj", b/"same.ply"], out, "stl", continue_on_error=True)
|
|
29
|
+
assert len(report.results)==1 and len(report.errors)==1
|
|
30
|
+
|
|
31
|
+
def test_capabilities_are_structured():
|
|
32
|
+
caps=format_capabilities()
|
|
33
|
+
assert ".obj" in caps and set(caps[".obj"]) == {"import", "export"}
|