DevPyLib

DevPyLib is a comprehensive development library for DCC (Digital Content Creation) applications, with primary support for Autodesk Maya and ongoing development for Houdini and Blender.

It provides professional-grade tools for rigging, animation, simulations, shading, modeling, and pipeline management for VFX and animation studios.

---

🎯 Features

• 🎨 Advanced Rigging - Modular system with Ziva VFX and AdonisFX support
• 💧 Fluid Simulations - Smoke, fire, explosion with modular base system
• 🔷 Bifrost/USD Integration - Full support for Bifrost graphs and USD pipeline
• 🎭 Animation Tools - BVH importer and animation utilities
• 🖼️ Lookdev & Shading - HDRI compensation, shader utilities
• 🛠️ Modeling Tools - UV tools, quad patcher, mesh utilities
• 🚀 Pipeline Integration - Naming conventions, workspace management
• 🖥️ Automatic GUI - Introspective system to generate UI from Python functions
• 🔌 Plugin System - Maya C++ API plugins (tension map, mesh collision)
• 🌍 Cross-Platform - Windows, Linux, macOS
• ⚡ Lazy Loading - Fast startup with on-demand module loading (93% faster imports)

---

⚡ Performance & Lazy Loading

DevPyLib uses lazy loading to minimize Maya startup time. Modules are loaded on-demand when first accessed, not during initial import.

Performance Improvements

• 93.3% faster imports: import mayaLib completes in ~1.3ms (vs. ~18.8ms with eager loading)
• Reduced memory footprint: Only loaded modules consume memory
• Deferred heavy imports: Ziva, AdonisFX, Bifrost load only when needed

How It Works

All modules use Python's __getattr__ pattern for lazy loading:

import mayaLib  # Fast! Only imports the base package (~1.3ms)

# Modules load on first access:
from mayaLib import rigLib  # Loads rigLib now
from mayaLib.fluidLib import fire  # Loads fluidLib, then fire

Backwards Compatibility

100% backwards compatible - all existing code works unchanged:

# All import patterns work identically
import mayaLib
from mayaLib import rigLib
import mayaLib.rigLib
from mayaLib.rigLib import base
from mayaLib.rigLib.utils import control

Behavioral Changes

• First access: Slightly slower (includes import time)
• Subsequent access: Instant (modules are cached)
• Error messages: Import failures occur on first access, not at startup

---

📋 Requirements

• Autodesk Maya 2022-2026
• Python 3.9+ (included with Maya)
• Git (to clone the repository)

Python Dependencies

Dependencies are installed automatically on first Maya startup:

numpy
pymel
GitPython (optional)

Note for Maya 2026: PyMEL 1.5.0 (PyPI) does not support Maya 2026. Install pymel 1.6.0rc2 from iamsleepy's fork instead.

---

🚀 Installation

DevPyLib supports flexible installation on any operating system without manual configuration.

1. Clone the Repository

Clone DevPyLib anywhere on your system (the path will be auto-detected):

# Recommended location
cd ~/Documents/workspace  # Linux/macOS
cd %USERPROFILE%\Documents\workspace  # Windows

# Clone repository
git clone https://github.com/Aiacos/DevPyLib.git
cd DevPyLib

# Update submodules
git submodule update --init --recursive

2. Install Configuration Files

Use the included installer scripts to copy Maya.env and userSetup.py to the correct Maya directories:

Windows

cd DevPyLib
install.bat

Linux / macOS

cd DevPyLib
./install.sh

The installer will:

• Detect installed Maya versions (2024-2026)
• Copy Maya.env to each version's directory (maya/{version}/Maya.env)
• Copy userSetup.py to the shared scripts directory (maya/scripts/userSetup.py)
• Ask before overwriting existing files

Manual Installation

If you prefer to install manually, copy the files yourself:

Source	Destination
mayaLib/Maya.env	~/Documents/maya/{version}/Maya.env
mayaLib/userSetup.py	~/Documents/maya/scripts/userSetup.py

3. Launch Maya

On Maya startup, you'll see:

DevPyLib detected at: /path/to/DevPyLib
All requirements installed successfully!
Added /path/to/DevPyLib to sys.path
Imported mayaLib
Maya command port opened on: 4434
DevPyLib setup complete!

The DevPyLib menu will appear automatically in Maya's interface! 🎉

---

📁 Project Structure

DevPyLib/
├── mayaLib/                    # Main Maya library (~28K LOC)
│   ├── animationLib/          # Animation tools
│   ├── ariseLib/              # Arise rig system (HumanIK, face rig)
│   ├── bifrostLib/            # Bifrost graph and USD integration
│   ├── fluidLib/              # Fluid system (smoke, fire, explosion)
│   ├── guiLib/                # Automatic GUI system
│   ├── lookdevLib/            # Lookdev and shading tools
│   ├── modelLib/              # Modeling utilities
│   ├── pipelineLib/           # Pipeline and naming conventions
│   ├── plugin/                # Maya C++ API plugins
│   ├── rigLib/                # Modular rigging system
│   │   ├── base/             # Base modules (Limb, Spine, Face, etc.)
│   │   ├── utils/            # 31+ utility modules
│   │   ├── Ziva/             # Ziva VFX integration
│   │   └── AdonisFX/         # AdonisFX integration
│   ├── shaderLib/            # Shader utilities
│   ├── usdLib/               # USD export/import
│   └── utility/              # General utilities
├── houdiniLib/               # Houdini tools and HDAs
├── blenderLib/               # Blender tools (in development)
├── prismLib/                 # Prism Pipeline integration
├── pyfrost/                  # Bifrost utilities (git submodule)
├── tools/                    # Standalone tools
├── wiki/                     # Complete documentation
│   ├── MayaLib/             # MayaLib documentation
│   ├── HoudiniLib/          # HoudiniLib documentation
│   └── BlenderLib/          # BlenderLib documentation
├── install.bat               # Windows installer (copies Maya.env + userSetup.py)
├── install.sh                # Linux/macOS installer
└── requirements.txt          # Python dependencies

---

🎓 Basic Usage

Automatic GUI System

DevPyLib automatically generates UI for Python functions:

import mayaLib.guiLib.main_menu as mm

# Menu is created automatically
# All functions with docstrings appear in the menu

Example: Create Base Rig

from mayaLib.rigLib.base.module import Base

# Create base rig structure
rig = Base(characterName='Character01', scale=1.0)

# Structure is created automatically:
# - Character01_rig_GRP/
#   - global_CTRL
#   - main_CTRL
#   - model_GRP/
#   - rig_GRP/
#   - skeleton_GRP/

Example: Fluids

from mayaLib.fluidLib.smoke import Smoke

# Create smoke system
smoke = Smoke()

Example: Bifrost + USD

from mayaLib.bifrostLib import bifrost_api

# Create Bifrost graph
graph = bifrost_api.create_bifrost_graph(name='myGraph')

# Get USD stage
stage = bifrost_api.get_maya_usd_stage()

---

🔧 Advanced Configuration

Environment Variables

The mayaLib/Maya.env file configures environment variables per Maya version. Key variables:

Variable	Purpose
DEVPYLIB_PATH	Path to DevPyLib root directory
PYTHONPATH	Set to DEVPYLIB_PATH for Python imports
BIFROST_LIB_CONFIG_FILES	Path to custom Bifrost compound libraries
DEVPYLIB_DISABLE_LUNA	Set to 1 to disable Luna loading at startup

Disabling Luna

To prevent Luna from loading at startup (recommended if not using Luna):

# In Maya.env
DEVPYLIB_DISABLE_LUNA=1

This blocks Luna at all levels: Python import, menu discovery, and UI button.

Auto-Update from Git

Uncomment in userSetup.py to enable automatic git pull on startup:

# userSetup.py - line 98
git_pull_gitpython(libDir, branch="master")  # Remove comment

Command Port

Maya automatically opens command port 4434 for external connections. To change:

# userSetup.py - line 91
port = "4434"  # Change port number

---

🧪 Testing

Verify Installation

1. Open Maya
2. Open Script Editor (Python)
3. Run:

import mayaLib
print(mayaLib.__file__)  # Should show correct path

Test Scripts

Tests are in mayaLib/test/:

# In Maya Script Editor
execfile('/path/to/DevPyLib/mayaLib/test/MayaLib.py')

---

📚 Documentation

Wiki

Complete documentation is available in the wiki/ folder:

Section	Description
Home	Overview and navigation
Architecture	Design patterns and structure
API Reference	Quick API reference
Cross-Platform	Platform compatibility guide
Contributing	Contribution guidelines

MayaLib Documentation

Page	Description
MayaLib Home	MayaLib overview
Getting Started	Setup guide
RigLib	Rigging library
AnimationLib	Animation tools
FluidLib	Fluid simulations
BifrostLib	Bifrost/USD integration
GuiLib	UI framework

Other DCCs

• HoudiniLib - Houdini tools and HDAs
• BlenderLib - Blender utilities

Other Documentation

• CHANGELOG.md - Version history and changes
• CLAUDE.md - Detailed architecture and patterns for developers
• CROSS_PLATFORM_MIGRATION.md - Cross-platform migration notes
• Inline docs - All functions have complete docstrings

Online Resources

• Repository: https://github.com/Aiacos/DevPyLib
• Issues: https://github.com/Aiacos/DevPyLib/issues

---

🛠️ Development

Architecture

DevPyLib uses a layered modular architecture:

• Base Classes - Foundations for rigs, fluids, UI (*/base/)
• Utility Layer - Reusable orthogonal functions (*/utils/)
• Specialized Systems - Domain-specific implementations
• GUI Layer - Automatic UI generation via introspection

See CLAUDE.md for complete architecture details.

Contributing

1. Create a branch for changes: git checkout -b feature/feature-name
2. Follow code conventions (see below)
3. Test on at least 2 platforms (Windows/Linux/macOS)
4. Create Pull Request

Code Style

# Use PyMEL for Maya operations
import pymel.core as pm

# Use pathlib for paths
from pathlib import Path

# Naming conventions
_GRP   # For groups
_CTRL  # For controls
_LOC   # For locators
_JNT   # For joints

# Docstrings for all functions (used by GUI)
def myFunction(param1, param2=True):
    """
    Brief function description.

    Args:
        param1 (str): Parameter description
        param2 (bool): Description with default

    Returns:
        type: Return description
    """
    pass

Cross-Platform Guidelines

• ✅ Always use pathlib.Path for path operations
• ✅ Use subprocess.run() instead of os.system()
• ✅ Use shutil instead of shell commands (rm, cp, etc.)
• ✅ Test on Windows, Linux, and macOS when possible
• ❌ Don't use hardcoded paths
• ❌ Don't use manual path separators (/ or \)

Branch Protection Rules

To maintain code quality and ensure stable releases, we recommend configuring the following branch protection rules for the main/master branch:

Required Settings

Rule	Description
Require status checks before merging	All CI jobs (lint, test) must pass before a PR can be merged
Require pull request reviews	At least 1 reviewer approval required before merging
Require branches to be up to date	Branch must be current with base branch before merging

Recommended Settings

Rule	Description
Require linear history	Prevents merge commits, enforces rebase/squash workflow
Require signed commits	Ensures commit authenticity (optional)
Include administrators	Applies rules to repository admins as well

How to Configure (GitHub)

1. Go to Settings → Branches in your repository
2. Under "Branch protection rules", click Add rule
3. Enter main (or master) as the branch name pattern
4. Enable the desired protection rules
5. Click Create to save

CI Status Checks

The following status checks should be required to pass:

• lint - Ruff linting and formatting checks
• test (3.9) - pytest on Python 3.9
• test (3.10) - pytest on Python 3.10
• test (3.11) - pytest on Python 3.11

See .github/workflows/ci.yml for the complete CI pipeline configuration.

---

🔍 Troubleshooting

Menu Doesn't Appear

# Check in Script Editor
import sys
print('/path/to/DevPyLib' in sys.path)  # Must be True

import mayaLib.guiLib.main_menu as mm
mm.MainMenu('/path/to/DevPyLib')  # Create menu manually

Missing Dependencies

# Install manually if needed
mayapy -m pip install -r /path/to/DevPyLib/requirements.txt

GitPython Not Available

GitPython is optional. If missing, you'll see:

GitPython not available - git operations disabled

To install:

mayapy -m pip install GitPython

Path Not Detected Correctly

Verify the symlink:

# Linux/macOS
ls -la ~/maya/scripts/userSetup.py

# Windows (PowerShell)
Get-Item $env:USERPROFILE\Documents\maya\scripts\userSetup.py | Select-Object Target

---

📊 Compatibility

Operating System	Maya Version	Status
Windows 10/11	2022-2026	✅ Tested
Linux (Ubuntu/CentOS/Rocky)	2022-2026	✅ Tested
macOS (Intel)	2022-2025	✅ Tested
macOS (Apple Silicon)	2022-2026	✅ Tested (Rosetta)

---

📝 License

See LICENSE file for details.

---

👤 Author

Lorenzo Argentieri

---

📮 Support

• Issues: https://github.com/Aiacos/DevPyLib/issues
• Discussions: https://github.com/Aiacos/DevPyLib/discussions

---

Happy creating with DevPyLib! 🎨✨