EnviScale Python SDK & CLI

The official Python SDK and Command-Line Interface (enviscale) for EnviScale — the physics grounding and SimReady pipeline engine for robotics and reinforcement learning.

Key Features

• ⚡ Native Multi-Part Extraction: Discovers assemblies in GLTF/GLB, STEP, and USD; reconciles part masses against an anchor prior.
• 📐 3D Parallel-Axis Theorem: Calculates authoritative $3 \times 3$ rigid-body cumulative inertia tensors ($I_{\text{global}}$) rather than diagonal box simplifications.
• 🧪 Fluid Fill States: Voxel cavity extraction to simulate empty, half, and full containers with displaced Center of Mass and viscous friction damping.
• 🤖 Multi-Simulator Export: Generates validated MuJoCo MJCF XMLs (fullinertia), URDFs, and Isaac Sim USD Physics.
• 🗃️ Programmatic Scene Composition: Automatically lays out multi-object evaluation scenes on workspace tables, desks, bins, or shelves.
• 🔄 Domain Randomization (DR): Iterates over calibrated friction wear and mass variation profiles directly in PyTorch/Gymnasium training loops.

Installation

pip install enviscale

Or for local development:

git clone https://github.com/enviscale/enviscale-sdk.git
cd enviscale-sdk
pip install -e .

Quickstart: Python SDK

import enviscale

# 1. Initialize client (defaults to http://localhost:8000 or ENVISCALE_BASE_URL)
client = enviscale.Client(api_key="es_live_YOUR_API_KEY")

# 2. Compile an asset with automatic multi-part physics
asset = client.compile(
    file_path="lantern.glb",
    export_format="mjcf",
    surface_condition="all",
    output_dir="./compiled_lantern",
)

print(f"Object: {asset.object_name}")
print(f"Reconciled Mass: {asset.mass_kg:.3f} kg")
print(f"Center of Mass: {asset.center_of_mass}")

if asset.is_native_multipart:
    print(f"Multi-Part Mode: {asset.native_parts_count} parts reconciled via Parallel-Axis Theorem")
    print(f"Full Inertia: {asset.inertia_tensor}")  # [Ixx, Iyy, Izz, Ixy, Ixz, Iyz]

# 3. Access MuJoCo XML for simulation
xml_content = asset.get_xml(profile_prefix="clean")

Reinforcement Learning Domain Randomization Loop

import mujoco
import enviscale

client = enviscale.Client()
asset = client.compile("drill.step", export_format="mjcf")

# Train policy across physically calibrated wear and fill profiles
for profile in asset.profiles:
    print(f"Training on profile: {profile.profile_name}")
    print(f"  Friction: {profile.friction_sliding}")
    print(f"  DR Mass Bounds: {profile.dr_mass_range}")
    
    # Load profile directly into MuJoCo model
    xml_str = asset.get_xml(profile_prefix=profile.profile_name)
    model = mujoco.MjModel.from_xml_string(xml_str)

Programmatic Scene Composition

import enviscale

client = enviscale.Client()

scene = client.compose(
    files=["mug.glb", "pliers.step", "box.obj"],
    template="tabletop_manipulation",
    seed=101,
    output_dir="./eval_scene",
)

print(f"Generated scene world file at ./eval_scene/scene.xml")

Quickstart: CLI Tool

The package registers the enviscale command directly in your shell:

Compile a single asset:

enviscale compile gearbox.step --format mjcf -o ./gearbox_simready

Compile multi-part container with fill states:

enviscale compile travel_mug.glb --fill all --quality precise -o ./mug_simready

Compose multi-object evaluation scene:

enviscale compose cup.glb pliers.glb screwdriver.step \
  --template tabletop_manipulation \
  --seed 42 \
  -o ./composed_bench

Check API connectivity:

enviscale status

CI/CD Pipeline Integration (GitHub Actions)

Add physical validity checks before merging robot simulation assets:

name: Simulation Asset Verification

on:
  pull_request:
    paths:
      - 'assets/**'

jobs:
  validate-assets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install EnviScale
        run: pip install enviscale
      
      - name: Compile and Verify Asset
        env:
          ENVISCALE_API_KEY: ${{ secrets.ENVISCALE_API_KEY }}
        run: |
          enviscale compile ./assets/new_tool.glb --format mjcf -o ./dist/

License

MIT License. Developed for the robotics and simulation community.