Metadata-Version: 2.4
Name: extapps
Version: 0.10.2
Summary: Standalone Qt tools for content pipelines: texture map compositing and conversion, photogrammetry, Substance Painter and Marmoset Toolbag automation, Unity and WebXR hand-off, and mesh conversion.
Author-email: Ryan Simpson <m3trik@outlook.com>
License: LGPL-3.0-or-later
Project-URL: Homepage, https://github.com/m3trik/extapps
Project-URL: Repository, https://github.com/m3trik/extapps
Project-URL: Changelog, https://github.com/m3trik/extapps/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/m3trik/extapps/issues
Keywords: m3trik,photogrammetry,pbr,substance-painter,gltf,technical-art,pyside6
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: pythontk>=0.23.0
Requires-Dist: uitk>=1.11.0
Requires-Dist: qtpy
Provides-Extra: mesh
Requires-Dist: pythontk[mesh]; extra == "mesh"
Dynamic: license-file

[![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0.en.html)
[![Tests](https://img.shields.io/badge/Tests-844%20passed-brightgreen.svg)](../tests/)

<!-- short_description_start -->
Standalone Switchboard apps for content-pipeline workflows — map compositing, texture conversion and channel packing, photogrammetry, mesh conversion, Substance / Marmoset / Unity automation, WebXR preview and look matching.
<!-- short_description_end -->

# extapps

Each app is a self-contained subpackage -- its engine, panel and Slots class --
on pythontk and uitk alone, registered with uitk's `ExternalAppHandler` via the
`uitk.external_apps.in_process` entry-point group. A host (tentacle's Maya and
Blender menus) opens one by name -- no host-side imports, and extapps imports no
host.

<!-- diagram:ecosystem/extapps -->
<!-- Generated by m3trik/scripts/generate_readme_diagrams.py from the workspace's declarations: change those and re-run it, never this block. -->
<p align="center">
<a href="https://github.com/m3trik/m3trik#readme"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/m3trik/m3trik/main/docs/diagrams/ecosystem-extapps-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/m3trik/m3trik/main/docs/diagrams/ecosystem-extapps-light.svg"><img alt="extapps (highlighted) in the ecosystem: uitk requires pythontk; unitytk requires pythontk; mayatk requires uitk; blendertk requires uitk; tentacle requires uitk; extapps requires uitk; tentacle installs mayatk as its [maya] extra; tentacle installs blendertk as its [blender] extra; tentacle opens extapps by name (its [apps] extra) and never imports it; mayatk and blendertk share a mirrored API. tentacle and extapps are products, which nothing imports." src="https://raw.githubusercontent.com/m3trik/m3trik/main/docs/diagrams/ecosystem-extapps-light.svg" width="781"></picture></a>
</p>
<!-- /diagram:ecosystem/extapps -->

## Tools

| Tool | Purpose | Engine | Docs |
|---|---|---|---|
| `compositor` | Multi-layer texture compositing | `pythontk.core_utils.engines.textures.map_compositor` | [→](map_compositor.md) |
| `metashape_workflow` · `realityscan_workflow` · `gaussian_splat_workflow` | End-to-end photogrammetry runs, one app per engine — frame extraction/curation → align → mesh → texture, with per-engine presets | bundled runners (Metashape SDK, RealityScan RSNode, gaussian splat) | [Metashape engine →](metashape_workflow.md) · [Tuning →](../extapps/photogrammetry/TUNING.md) |
| `substance_scripts` | Substance 3D Painter scripts, built-in and your own | vendored (mayatk's Painter engine) | [→](substance_scripts.md) |
| `marmoset_scripts` | Run Marmoset Toolbag scripts on a model file in a new Toolbag: the bundled import / lookdev and your own, each script's rows from its tokens | bundled `_marmoset_engine` (SDK-specific) | _TBD_ |
| `unity_scripts` | Run built-in and your own C# editor scripts in a Unity project you have open, each script's settings as rows: Send to Unity, Make Prefab, Reimport Folder. A script that takes an asset gets a model file, or, opened from Maya / Blender, the scene exported by the Scene Exporter | `pythontk.FolderDeliverer` (delivery) + `pythontk.JobQueue` (served by the editor package it installs into the project); the host's `UnityBridge` (`ptk.SceneExportHandoff`) | [→](unity_scripts.md) |
| `converter` | Texture conversion (normal DX↔GL, smoothness↔roughness, spec→PBR, bump→normal, optimize, flip/swizzle channels), color+alpha pack/unpack, PBR prep | `pythontk.ImgUtils` / `MapFactory` | _TBD_ |
| `packer` | Channel-pack **and unpack** textures via per-channel sources (built-in templates: ORM, MRAO, MSAO, Metallic Smoothness, glTF clearcoat / iridescence / transmission-volume) | `pythontk.ImgUtils` / `MapFactory` | _TBD_ |
| `mesh_convert` | FBX → glTF / GLB conversion | `pythontk.file_utils.mesh_convert` | _TBD_ |
| `webxr_preview` | Preview a scene (from a host) or an FBX / GLB file live in a browser or XR headset, and share a link | `pythontk.net_utils.preview` | [→](https://github.com/m3trik/pythontk/blob/main/docs/webxr_preview.md) |
| `look_match` | Light a baked scene to match a reference image: the mix of light layers, a live comparison, region scores, solve / fit proposals, WebXR renders, Update layers, rigs saved to the shared library | `pythontk.core_utils.engines.lighting` | [→](https://github.com/m3trik/pythontk/blob/main/docs/look_match.md) |

## Install

```powershell
pip install extapps
```

## Launch (standalone)

Installing extapps adds an `extapps` command (`python -m extapps` runs the same
program):

| Command | Opens |
|---|---|
| `extapps` | A browser listing every panel: search, filter by tag, double-click to open |
| `extapps compositor` | One panel, by its name in the Tools table (`metashape_workflow`, `mesh_convert`, ...) |
| `extapps --shortcut desktop` | Writes a desktop shortcut that opens the browser, then exits (`--shortcut start_menu`: the Start menu, or the Linux applications menu) |
| `extapps compositor --shortcut desktop` | Writes a shortcut that opens one panel (named "extapps Compositor") |

The command opens no console window, and quits once its last window is closed
or hidden. It is uitk's `ExternalAppHub`; `extapps/__main__.py` only declares its
name, icon and taskbar identity.

### Desktop and Start-menu shortcuts

Three ways to get one; run any of them again to refresh a shortcut (after moving
or upgrading the Python it runs, say):

- **From the browser:** its menu, *Launch from the desktop:* section,
  *Create desktop shortcut* / *Add to Start menu*.
- **From inside Maya or Blender (tentacle):** open the UI Browser, right-click a
  panel's row, *Create desktop shortcut* / *Add to Start menu*. The shortcut runs
  the host's own Python (`mayapy`, Blender's `python`) without opening the host.
- **From a terminal:** `extapps --shortcut desktop`.

Before writing anything, the shortcut is tried: extapps has to import in that
Python as the desktop starts it, without the host's startup scripts. When it does
not (extapps reaches the host only through `userSetup.py` or `Maya.env`), no
shortcut is written and the message says why. Fix it by installing extapps into
that Python with pip, or by putting the extapps folder on a `PYTHONPATH` saved in
your user environment.

A shortcut into a host's Python (which has no console-free twin, unlike a
python.org or venv Python's `pythonw`) opens a console window for a moment; the
program closes it as it starts.

### When nothing seems to happen

A program started from the desktop has no console, so its output goes to a log:
`%LOCALAPPDATA%\uitk\extapps\extapps.log` on Windows (the previous run's is
`extapps.log.1`); on Linux the desktop session's journal. An uncaught error also
shows in a message box.

### From Python

```powershell
python -c "from extapps.texture_maps.compositor import CompositorUI; CompositorUI().show(pos='screen', app_exec=True)"
```

## Launch (from a host)

Hosts that load uitk's `ExternalAppHandler` discover apps automatically:

```python
sb.handlers.external_app.launch("compositor")
```

## Dependencies

- `pythontk` — domain logic
- `uitk` — UI framework
- `qtpy` — Qt abstraction

The `metashape_workflow` tool additionally requires the Agisoft Metashape Python module to be importable (installed alongside Metashape itself). The `substance_scripts` tool requires an Adobe Substance 3D Painter install (auto-detected) to launch one, or your own Painter with its plugin installed (Install in Painter).

## License

LGPL-3.0-or-later — see [COPYING.LESSER](https://github.com/m3trik/extapps/blob/main/COPYING.LESSER) and [COPYING](https://github.com/m3trik/extapps/blob/main/COPYING).
