Skip to content
BranchesTags

Repository files navigation

SceneQC Icon

SceneQC

AI-Powered Scene Quality Control for Autodesk Maya

Deterministic pipeline validation meets multimodal AI visual review — seamlessly integrated into your Maya workflow.

Python Maya FastAPI PySide License

Overview

SceneQC is a professional pipeline tool that bridges the gap between rule-based QC automation and intelligent AI review. It operates as a dual-process system: a headless FastAPI backend manages AI inference and data processing, while a polished, native PySide interface provides the artist-facing experience — launching automatically in the background when Maya opens.

Artists can validate geometry, naming conventions, shading, and render settings against studio-defined profiles, then immediately cross-reference those results with a multimodal AI visual quality review — all without leaving Maya.

Features

🔬 Technical Diagnostics

Comprehensive scene auditing driven by studio-defined pipeline rules in a portable YAML format:

Check What it Catches
Geometry Polygon count limits (warning / critical), non-manifold geometry, construction history
Transforms Unfrozen scale and rotation, empty group nodes
Naming Missing _GEO, _MAT, _GRP, _CTRL suffixes; configurable prefix enforcement
Shading Missing textures, unassigned geometry (default Lambert), invalid UDIM paths
Scene Missing render camera, FPS requirements, unknown plugin dependencies

🤖 AI Visual Quality Review

SceneQC integrates a multimodal Vision Language Model to review your viewport render like an experienced Art Director. It produces:

  • A numeric Visual Score (out of 10)
  • A prose Artistic Summary with lighting, composition, and material notes
  • Prioritized Visual Improvements with exact issue locations

Two AI providers, one interface:

Provider Model Use Case
Local (GGUF) Qwen3-VL (2B → 235B-A22B) Air-gapped studios, offline production
Cloud API Any OpenAI-compatible endpoint Modal, Alibaba Cloud, etc.

🗂️ Quality Profiles

Profiles are YAML files that define the full validation ruleset for a project or pipeline stage. Create, edit, and switch between profiles from inside Maya without restarting.

🗺️ Polygon Density Heatmap

Generates a tessellated false-color image of the scene geometry, colored by polygon count relative to screen-space coverage. Useful for catching density hotspots before rendering.

⚡ One-Click Installation

A drag-and-drop Python file creates a shelf button in the active Maya shelf. The backend server starts automatically on first launch and a built-in terminal log shows the startup progress.

Architecture

maya-scene-qc/
├── drag_and_drop_install.py     ← Drop into Maya to install
├── start_server.bat             ← Launched automatically by Maya client
├── config.yaml                  ← Global validation rules (default profile)
├── requirements.txt
│
└── sceneqc/
    ├── backend/                 ← Standalone FastAPI process
    │   ├── settings.json        ← AI settings persistence
    │   └── app/
    │       ├── main.py          ← Uvicorn entrypoint
    │       ├── routes/api.py    ← REST endpoints (/analyze, /ai-settings, ...)
    │       ├── services/
    │       │   ├── ai.py        ← Local GGUF + Cloud API inference engine
    │       │   └── validation.py   ← Deterministic Maya data auditing
    │       └── utils/
    │           ├── settings_manager.py
    │           └── config.py    ← YAML profile loader
    │
    └── maya_client/             ← Maya PySide2/6 plugin
        ├── main.py              ← Singleton launcher
        ├── ui/
        │   ├── view.py          ← Root SceneQCView dialog
        │   ├── styles.py        ← Centralized QSS stylesheet
        │   ├── components/
        │   │   ├── toolbar.py
        │   │   ├── technical_panel.py
        │   │   ├── visual_panel.py
        │   │   ├── state_widget.py
        │   │   ├── metric_panel.py
        │   │   ├── download_thread.py  ← HuggingFace GGUF downloader
        │   │   └── ...
        │   └── dialogs/
        │       ├── ai_settings.py      ← Setup wizard + settings dialog
        │       ├── profile_editor.py
        │       ├── heatmap.py
        │       └── manual_image.py
        └── scripts/
            ├── network/api_client.py   ← HTTP client for the backend
            ├── extraction/             ← Maya cmds scene data extractors
            ├── generators/             ← Heatmap tessellation
            └── profile_manager.py

How it works: SceneQC handles its own lifecycle. Maya launches the backend API as a detached subprocess via start_server.bat. The Maya client then polls http://127.0.0.1:8000/health and transitions the UI from the startup log to the main dashboard as soon as the server is ready. Analysis jobs are sent as multipart form payloads (scene JSON + viewport render) to the /analyze endpoint.

Screenshots

Startup & Server Boot Full Analysis — Running State
Startup Screen Analysis Running
Technical Diagnostics Panel AI Visual Quality Review
Technical Panel Visual Panel
AI Provider Settings Profile Editor
AI Provider Settings Profile Editor

Getting Started

Prerequisites

Requirement Version
Autodesk Maya 2024 or later (PySide2 / PySide6)
Python 3.10+ (standalone environment outside Maya)
NVIDIA GPU (Local AI) ≥ 4 GB VRAM for 2B model
Internet (Cloud AI) Access to a cloud API endpoint

Installation

1. Clone the repository

git clone https://github.com/ok-elawady/maya-scene-qc.git

2. Install into Maya — drag and drop

Open Autodesk Maya, then drag drag_and_drop_install.py directly into the Maya viewport. This will:

  • Add a SceneQC shelf button to your current shelf
  • Configure the launch command with the correct repository path

3. First launch

Click the shelf button. On the first launch, the plugin will automatically create an isolated Python virtual environment, install all required dependencies, and configure the correct CUDA binaries for local AI hardware acceleration.

The startup screen appears with a live terminal log while the backend server boots. On first run, a Setup Wizard will prompt you to choose an AI provider.

AI Provider Configuration

Option A — Local Model (Offline)

SceneQC downloads Qwen3-VL GGUF weights directly from HuggingFace inside the Maya UI. Select a model size based on your available VRAM:

Model Size VRAM Required Recommended For
2B ~3 GB Quick reviews, low-end hardware
4B ~4 GB General use — best value
8B ~8 GB Higher quality outputs
30B-A3B ~16 GB Production quality, MoE architecture
32B ~24 GB High-fidelity review
235B-A22B ~120 GB+ Maximum quality, multi-GPU setups

Option B — Cloud API (Any OpenAI-Compatible Endpoint)

Enter any OpenAI-compatible base URL. The Authorization token is optional — useful for self-hosted deployments like Modal or vLLM:

Base URL:       https://your-workspace.modal.run/v1
Authorization:  (leave blank for unauthenticated endpoints)

Cold-start handling: SceneQC automatically detects serverless cold starts (HTTP 503). It retries for up to 5 minutes with a 5-second interval and surfaces a live "Warming up Cloud Server..." indicator in the analysis loading screen.

Analysis Modes

Mode What Runs
Full Analysis Technical diagnostics + AI visual review. Renders a low-res proxy, audits the full scene DAG, and generates an integrated report.
Technical Only Pipeline rules validation without any rendering or AI inference. Fast, deterministic.
Visual Only Renders and sends to the AI for visual critique only — skips scene extraction.
Custom Image Select any local JPEG/PNG for AI review — perfect for checking offline renders or reference plates.

Validation Profiles

Profiles are YAML files stored in the profiles/ directory. They override the global config.yaml defaults to define project-specific rules.

# profiles/my_project.yaml
validation:
  geometry:
    poly_limit_warning: 30000
    poly_limit_critical: 150000
  naming:
    enforce_suffixes: true
    geo_suffix: "_GEO"
    grp_suffix: "_GRP"
  shading:
    check_missing_textures: true
    check_default_lambert: true

Create, edit, and switch profiles directly from the toolbar dropdown without restarting Maya or the backend.

REST API Reference

The backend exposes a local REST API on http://127.0.0.1:8000. While normally consumed by the Maya client, it can be queried directly during development.

Endpoint Method Description
/health GET Server liveness check
/config GET Active pipeline configuration
/ai-status GET AI provider readiness state
/ai-settings GET Current AI settings (masked key)
/ai-settings POST Update AI provider configuration
/analyze POST Full scene analysis (multipart form)

Example: Check AI status

curl http://127.0.0.1:8000/ai-status
# {"provider": "cloud", "local_models_ready": false, "cloud_configured": true}

Example: Update Cloud provider

curl -X POST http://127.0.0.1:8000/ai-settings \
  -H "Content-Type: application/json" \
  -d '{"ai_provider": "cloud", "cloud": {"base_url": "https://your-endpoint.com/v1"}}'

Development

Running the backend standalone

cd maya-scene-qc
venv\Scripts\activate
uvicorn sceneqc.backend.app.main:app --host 127.0.0.1 --port 8000 --reload

Project conventions

  • Commit format: type(scope): description — e.g. feat(maya), refactor(backend), chore(config)
  • Validation profiles: Live in profiles/ (gitignored). A default profile is created from config.yaml on first run.
  • Settings persistence: sceneqc/backend/settings.json (gitignored). Stores the active AI provider and its credentials.

Tech Stack

Layer Technology
Maya Plugin UI PySide2 / PySide6, Outfit font, custom QSS
Backend API FastAPI + Uvicorn
Local AI Inference llama-cpp-python (Llava / Qwen3-VL GGUF)
Cloud AI httpx, OpenAI-compatible REST
Pipeline Config PyYAML
Model Downloads HuggingFace Hub (urllib, no extra deps)
Scene Extraction Maya Python API (maya.cmds)

License

Apache 2.0 © Omar Elawady

About

AI-powered Scene Quality Control for Autodesk Maya. Deterministic pipeline validation meets multimodal AI visual review

Topics

fastapimayapysidepythonquality-controlqwen-vlvlm

Resources

Readme
License
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages