Metadata-Version: 2.4
Name: meshvault
Version: 0.1.0
Summary: A professional 3D asset browser for rapid browsing, previewing, and managing OBJ/FBX files
License: MIT
License-File: LICENSE
Keywords: 3d,asset-browser,obj,fbx,three.js,viewer,meshvault
Author: Laurent-Philippe Albou
Author-email: contact@abstractcore.ai
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Multimedia :: Graphics :: Viewers
Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
Requires-Dist: fastapi (>=0.115.0,<0.116.0)
Requires-Dist: python-multipart (>=0.0.9,<0.0.10)
Requires-Dist: rarfile (>=4.2,<5.0)
Requires-Dist: trimesh (>=4.4.0,<5.0.0)
Requires-Dist: uvicorn[standard] (>=0.30.0,<0.31.0)
Project-URL: Documentation, https://github.com/lpalbou/meshvault/tree/main/docs
Project-URL: Homepage, https://github.com/lpalbou/meshvault
Project-URL: Repository, https://github.com/lpalbou/meshvault
Description-Content-Type: text/markdown

# MeshVault

A professional, local web-based tool for rapidly browsing, previewing, and managing 3D assets (`.obj`, `.fbx`, `.gltf`, `.glb`, `.stl`) across your filesystem — including assets buried inside `.zip` and `.rar` archives.

[![CI](https://github.com/lpalbou/meshvault/actions/workflows/ci.yml/badge.svg)](https://github.com/lpalbou/meshvault/actions)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![FastAPI](https://img.shields.io/badge/backend-FastAPI-009688)](https://fastapi.tiangolo.com)
[![Three.js](https://img.shields.io/badge/3D-Three.js%20r170-black)](https://threejs.org)
[![PyPI](https://img.shields.io/pypi/v/meshvault)](https://pypi.org/project/meshvault/)
[![npm](https://img.shields.io/npm/v/meshvault)](https://www.npmjs.com/package/meshvault)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Features

| Feature | Description |
|---------|-------------|
| **Folder Browsing** | Navigate your filesystem with a clean sidebar tree. Go up, go home, double-click to enter. List/grid view toggle. |
| **Search & Filter** | Real-time search input to filter folders and assets in the current directory. |
| **3D Asset Detection** | Finds `.obj`, `.fbx`, `.gltf`, `.glb`, `.stl` files — including inside `.zip` and `.rar` archives. |
| **Interactive 3D Viewer** | Click an asset to load it with high-quality PBR rendering, SSAO, soft shadows, tone mapping. |
| **Orbit / FPV Toggle** | Orbit mode (mouse orbit/zoom/pan, right-click pivot) and FPV drone mode (WASD fly, A/D yaw, mouse look). |
| **Viewer Toolbar** | Toggle grid, XYZ axes (colored + labeled), wireframe, and light controls from the top-right toolbar. |
| **Light Controls** | Adjustable key/fill/ambient intensity, light direction (azimuth/elevation), and exposure. |
| **Background Presets** | 12 background color swatches (dark, gray, light, tinted) for evaluating models on any backdrop. |
| **Model Transforms** | Center at origin, ground on Y=0, auto-orient via PCA, reset to original. All without moving the camera. |
| **Model Scaling** | Real-time scale slider (0.25×–2.0×). |
| **Modified Export** | Export applies all transforms (center, ground, orient, scale) — saves modified OBJ via Three.js OBJExporter. |
| **FBX Auto-Conversion** | Old FBX files (version < 7000) are auto-converted to OBJ via a built-in binary parser. |
| **Persistent Settings** | Scene settings (wireframe, grid, axes, background) persist across model loads. |

## Quick Start

### Prerequisites

- **Python 3.10+**
- **Poetry** ([install guide](https://python-poetry.org/docs/#installation))
- For `.rar` support, one of: `bsdtar`, `unrar`, `7z`, or `unar` (auto-detected)

### Install & Run

```bash
git clone https://github.com/lpalbou/meshvault.git
cd meshvault
poetry install --no-root
poetry run meshvault
```

Then open **http://localhost:8420** in your browser.

### Install from PyPI

```bash
pip install meshvault
meshvault
```

### Install from NPM

```bash
npx meshvault
```

## Usage

1. **Browse**: Navigate folders in the sidebar. Toggle list/grid view. Filter by name.
2. **Preview**: Click any 3D asset to load it in the viewer (green=OBJ, orange=FBX, cyan=GLTF, purple=STL/archived).
3. **Navigate**: Orbit mode (left-drag orbit, scroll zoom, right-drag pan, right-click pivot) or FPV drone mode (W/Shift forward, S/Ctrl backward, A/D yaw, E/Q altitude). Spacebar resets camera.
4. **Scene tools**: Toggle grid, axes (XYZ), wireframe, and lighting from the toolbar. Pick background color from swatches.
5. **Transform**: Center model at origin, ground it on Y=0, or auto-orient via PCA. Reset undoes all transforms.
6. **Export**: Set name and path in the top bar, click Export. Modified models (centered/oriented/scaled) are exported as OBJ with baked transforms.

## Project Structure

```
meshvault/
├── backend/
│   ├── app.py                 # FastAPI server + routes
│   ├── file_browser.py        # Filesystem navigation + asset discovery
│   ├── archive_inspector.py   # ZIP/RAR inspection + multi-tool extraction
│   ├── export_manager.py      # Asset export with renaming
│   └── fbx_converter.py       # FBX 6100 binary parser + OBJ converter
├── frontend/
│   ├── index.html             # Main HTML page
│   ├── css/styles.css         # Dark professional theme
│   └── js/
│       ├── app.js             # Main orchestrator
│       ├── file_browser.js    # File browser + search + grid/list
│       ├── viewer_3d.js       # Three.js 3D viewer
│       └── export_panel.js    # Rename/export controls
├── tests/
│   └── test_file_browser.py   # Backend unit tests
├── docs/                      # Full documentation
├── pyproject.toml             # Poetry / PyPI configuration
├── package.json               # NPM configuration
└── poetry.lock
```

## Documentation

- [Getting Started](docs/getting_started.md) — Installation, first run, basic usage
- [Architecture](docs/architecture.md) — System design, components, design decisions
- [API Reference](docs/api.md) — REST API endpoints, request/response schemas
- [FAQ](docs/faq.md) — Common questions and troubleshooting

## Tests

```bash
poetry run pytest tests/ -v
```

## Contributing

Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/lpalbou/meshvault).

## License

MIT License — see [LICENSE](LICENSE) for details.

© 2026 Laurent-Philippe Albou — contact@abstractcore.ai

