Skip to content

docs: publish Maya transfer setup guide #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SeeleAIBot2 merged 1 commit into from
Aug 13, 2026
Merged

docs: publish Maya transfer setup guide #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 171 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,191 @@
# SEELE Maya Transfer 0.2.0
# SEELE Transfer for Maya

SEELE → Maya 2022+ 的 `dcc-transfer.v1` 接收插件。它提供仅监听 loopback 的 HTTP receiver、manifest 校验、安全 staging、任务状态管理，以及在 Maya 主线程执行的资产导入与回滚。
![Maya 2022+](https://img.shields.io/badge/Autodesk%20Maya-2022%2B-0696D7?logo=autodesk&logoColor=white)
![Version 0.2.0](https://img.shields.io/badge/Version-0.2.0-4c8bf5)

## 当前格式范围
**[Download SEELE Transfer for Maya 0.2.0](https://static.seeles.ai/kokokeepall/Plugin/Maya/SEELE-Maya-Transfer-0.2.0.zip)**

- FBX、OBJ、ABC：P0 格式；只有真实 Maya runtime probe 通过后才会在 health 中声明 ready。
- DAE：0.2.0 暂不对外声明 ready；取得 Maya golden import 证据后再启用。
- USD、USDA、USDC：0.2.0 明确禁用。当前没有导入 handler 或可启用路径，即使安装了 `mayaUsdPlugin` 也不会声明 ready。
- 普通 Python 环境只提供 mock health、CORS 和 contract 测试，不接受真实 transfer，也不会降级为 mock importer。
SEELE Transfer for Maya is a Maya plugin/add-on that receives and imports 3D assets sent from SEELE Workspace. It is a secure localhost receiver and Maya import bridge—not an AI generator running inside Maya.

OBJ 引用的 MTL 未提供时，插件仍导入几何，并以 `OBJ_MTL_NOT_PROVIDED` 完成 warning；已声明文件的 hash、大小、路径或安全校验失败仍是致命错误。
For browser-based generation, use [AI 3D Model Generator: Start Creating 3D Assets | SEELE AI](https://www.seeles.ai/features/tools/ai-3d-model-generator-entry). After an asset is available in SEELE Workspace, this plugin provides the Maya-side path to send 3D assets to Maya.

## Maya 安装
## What It Does

将 `SeeleMaya.mod` 和 `SeeleMaya/` 一起复制到 Maya modules 目录；目录不存在时可以手动创建。例如 Windows：
- Receives `dcc-transfer.v1` asset-transfer manifests from the production SEELE website.
- Downloads declared files over HTTPS, stages them safely, and checks the manifest-provided file size and SHA-256 digest before import.
- Imports FBX, OBJ, or Alembic (`.abc`) only when the current Maya runtime reports the required importer capability as ready.
- Runs Maya imports on Maya's main thread and rolls back incomplete imports when possible.
- Keeps its receiver local to the machine at `127.0.0.1:9879`.

```text
%USERPROFILE%\Documents\maya\modules\
This repository contains the Maya receiver/import bridge only. SEELE Workspace and the AI 3D model generator are separate services.

## Who It Is For

SEELE Transfer is for artists, technical artists, designers, and developers who create or select an asset in SEELE Workspace and want to continue working on it in Autodesk Maya. It is intended for a handoff workflow: create an asset on SEELE, send it to an open Maya session, inspect the imported scene, then continue using Maya's own tools.

## Requirements

- Autodesk Maya **2022 or newer**.
- Access to [seeles.ai](https://www.seeles.ai) and an internet connection while transferred assets are downloading.
- Permission for Maya to bind the local loopback port `127.0.0.1:9879`.
- The official 0.2.0 package, downloaded from the link above.

## Install on Windows or macOS

Maya modules must be installed as extracted files. **Do not point Maya at the ZIP directly.**

1. Download and extract `SEELE-Maya-Transfer-0.2.0.zip`.
2. Keep `SeeleMaya.mod` and the `SeeleMaya/` folder as siblings in the same directory. Do not rename either item.
3. Copy both items into your personal Maya modules directory:

| Platform | Typical personal modules directory |
| --- | --- |
| Windows | `%USERPROFILE%\Documents\maya\modules\` |
| macOS | `~/Library/Preferences/Autodesk/maya/modules/` |

Create the `modules` directory if it does not exist.
4. Restart Maya so it discovers `SeeleMaya.mod`.
5. Open **Windows > Settings/Preferences > Plug-in Manager**, find `seele_maya_plugin.py`, load it, and enable **Auto load** if you want the receiver to start with Maya.

### Upgrade

1. Quit Maya completely.
2. Replace the existing sibling pair—`SeeleMaya.mod` and `SeeleMaya/`—with the extracted pair from the new package.
3. Restart Maya and confirm that `seele_maya_plugin.py` loads in Plug-in Manager.

### Uninstall

Quit Maya, then remove the installed `SeeleMaya.mod` file and its sibling `SeeleMaya/` folder from the Maya modules directory. The plugin's per-user transfer data is stored separately under the local SEELE application-data directory; removing the module does not automatically remove that data.

## Quick Start

1. Start Maya and load `seele_maya_plugin.py`.
2. Confirm the local receiver is running; its fixed address is `127.0.0.1:9879`.
3. In SEELE Workspace, choose an asset and use the Maya transfer action.
4. SEELE sends a short-lived manifest to Maya. The receiver downloads, verifies, and imports the declared asset when its format is available in that Maya runtime.
5. Inspect the imported scene, including geometry, materials, textures, scale, and hierarchy, before continuing production work.

## Workflow

```mermaid
flowchart LR
A[Create or select a 3D asset in SEELE Workspace]
B[Send asset to Maya]
C[Local receiver at 127.0.0.1:9879]
D[HTTPS download and SHA-256 / size verification]
E[Maya runtime capability check]
F[Import into the Maya scene]

A --> B --> C --> D --> E --> F
```

重启 Maya，在 Plug-in Manager 中加载并按需勾选自动加载 `seele_maya_plugin.py`。默认监听 `127.0.0.1:9879`。
## Compatibility

| Format or environment | Status in 0.2.0 | Notes |
| --- | --- | --- |
| Autodesk Maya | Maya 2022+ | Requires the extracted module installation. |
| FBX | Capability-driven | Available only when the running Maya runtime reports the FBX importer ready. |
| OBJ | Capability-driven | Available only when the running Maya runtime reports the OBJ translator ready. Missing referenced MTL files can complete with an `OBJ_MTL_NOT_PROVIDED` warning; other declared-file validation failures are fatal. |
| Alembic (`.abc`) | Capability-driven | Available only when the running Maya runtime reports `AbcImport` ready. |
| DAE / COLLADA | Not advertised ready | The importer surface has not been product-validated for this release. |
| USD, USDA, USDC | Disabled | No import handler is enabled in 0.2.0, including where `mayaUsdPlugin` is installed. |

The plugin can report runtime readiness for FBX, OBJ, and Alembic import. That is not a claim that every asset variant has been validated on every Maya/OS combination; evaluate imports in your target Maya environment.

## Security, Privacy, and Network Behavior

## 配置
- **Local receiver only:** the HTTP receiver binds to `127.0.0.1:9879`, not a public network interface.
- **Production origin:** browser requests are accepted only from the exact origin `https://www.seeles.ai` by default. Wildcard origins are not supported.
- **Allowed downloads:** transferred files must use HTTPS and an exact allowlisted SEELE download host. Redirects are checked again; lookalike subdomains, unsafe DNS results, and non-HTTPS URLs are rejected.
- **Integrity checks:** declared content length is checked before download and each downloaded file is checked against its declared size and SHA-256 digest before import.
- **Safe staging:** paths and collisions are validated before files are committed to the local staging area.
- **No shell execution:** the receiver does not invoke a shell to process transfers; imports use the available Maya API/import surface.

公开生产版默认 exact Origin allowlist 仅包含：
Optional `SEELE_ALLOWED_ORIGINS` and `SEELE_ALLOWED_DOWNLOAD_HOSTS` environment values append trusted, comma-separated entries for controlled deployments. They do not support `*`; administrators should add only hosts they trust.

## Official Package Integrity

The production package currently published at the download link above has the following release metadata:

| Property | Value |
| --- | --- |
| Version | `0.2.0` |
| File size | `26,793 bytes` |
| SHA-256 | `d13cea96e9cb58597a127141127d9c14a854e61b12be8f933338e7cb67123415` |
| Audited source commit | `b7b59a41d34fe1296b1a2cacee70a0d1eb948fe9` |

To independently check a downloaded archive:

```powershell
Get-FileHash .\SEELE-Maya-Transfer-0.2.0.zip -Algorithm SHA256
```

```text
https://www.seeles.ai
```bash
shasum -a 256 SEELE-Maya-Transfer-0.2.0.zip
```

Feature 测试 Origin 不包含在公开生产包中。测试构建只允许 `https://code4agent-feature-maya-dcc-server-web.seele.chat`。`SEELE_ALLOWED_ORIGINS` 和 `SEELE_ALLOWED_DOWNLOAD_HOSTS` 使用逗号分隔，只用于追加可信来源或下载域名；不支持 `*`。插件已经内置 SEELE 官方静态资源、S3、CloudFront 和 Azure Blob 下载域名。下载只允许 HTTPS，且每次 redirect 都必须继续满足 allowlist 和网络安全检查。
## FAQ

下载 host 采用 IDNA canonicalization 后的 exact match，不自动信任子域；DNS 结果必须全部是公网地址，连接固定到已验证 IP，并继续使用原始 hostname 做 TLS 校验。macOS/Linux 使用逐段 `openat`/`O_NOFOLLOW` 和 directory fd 完成 staging 写入与原子替换；Windows 使用 handle-relative `NtCreateFile`/`NtSetInformationFile`，逐段拒绝 reparse point，并基于同一父目录 handle 创建和重命名临时文件。
### Is SEELE Transfer for Maya an AI 3D model generator?

## 本地测试（无需 Maya）
No. SEELE Transfer for Maya is a Maya plugin/add-on that receives, verifies, and imports 3D assets from SEELE Workspace. Use the [AI 3D Model Generator: Start Creating 3D Assets | SEELE AI](https://www.seeles.ai/features/tools/ai-3d-model-generator-entry) to generate assets in the browser.

### Can I send 3D assets to Maya directly from SEELE?

Yes, when Maya is open, `seele_maya_plugin.py` is loaded, and the local receiver is ready. SEELE Workspace sends a transfer manifest to the receiver at `127.0.0.1:9879`; the plugin then downloads and imports the asset if the required Maya importer is available.

### Which import formats does the Maya plugin support?

FBX, OBJ, and Alembic import are capability-driven: the plugin only reports them ready when that exact Maya runtime exposes the necessary importer. DAE is not advertised ready, and USD/USD variants are disabled in version 0.2.0.

### Does the plugin send my Maya scene to SEELE?

The receiver's documented role is to accept an incoming transfer manifest and download the asset files it declares from allowlisted HTTPS hosts. It is not a scene-export or remote-control plugin.

### Why is an OBJ imported without its materials?

An OBJ transfer without a provided referenced MTL file may import geometry and report `OBJ_MTL_NOT_PROVIDED`. Inspect the result and supply the asset's required material files when fidelity matters.

### Is this a public-network server?

No. The receiver is fixed to the loopback address `127.0.0.1:9879`, so it is intended to accept requests from the local machine rather than listen on the LAN or internet.

## Troubleshooting

### Maya does not discover the module

Verify that `SeeleMaya.mod` and `SeeleMaya/` are siblings inside a Maya `modules` directory, not inside the ZIP or an extra nested folder. Restart Maya after correcting the location.

### The plug-in will not load

Use Maya 2022 or newer. In Plug-in Manager, load `seele_maya_plugin.py` and review Maya's Script Editor for the specific load error. A full Maya restart after an upgrade clears a previously loaded module version.

### SEELE cannot connect to Maya

Keep Maya open and the plugin loaded. Confirm that local security software is not blocking localhost port `9879`, then retry from the exact production origin `https://www.seeles.ai`.

### A format is reported unavailable

The plugin fails closed when an importer is unavailable. Check that the required Maya importer is installed and available in that Maya session. DAE is not ready for this public release, and USD/USD variants are intentionally disabled.

### Download or verification fails

Confirm internet access and retry the transfer. The receiver rejects URLs outside its HTTPS allowlist and rejects declared files when their size or SHA-256 digest does not match; these checks are deliberate safeguards, not import fallbacks.

## Development and Tests

The repository includes pure-Python contract, security, readiness, HTTP, and format tests that can run without Maya:

```bash
PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -v
```

For Maya runtime smoke coverage, run the smoke test through the `mayapy` executable for each supported Maya/OS build. A smoke pass establishes evidence for that exact environment only; release validation should additionally cover golden FBX/OBJ/ABC imports, cancellation/rollback, and path-safety behavior.

```powershell
$env:PYTHONDONTWRITEBYTECODE='1'
python -m unittest discover -s tests -v
& "C:\Program Files\Autodesk\Maya2022\bin\mayapy.exe" tests_maya\smoke.py
```

这些测试不等同于 Maya 真机验证。发布前仍需在 Maya 2022+ 的 Windows/macOS 环境运行 load/unload、FBX/OBJ/ABC golden assets、取消/回滚和路径安全测试。
## License

This repository currently does not include a `LICENSE` file. Do not infer an open-source or redistribution license from the repository or package; obtain the applicable terms from SEELE before redistribution or commercial use.
Loading