Developer Docs

Introduction

EnviScale bridges the gap between raw 3D assets and high-fidelity physics simulators. By automating the mechanical property extraction, collision geometry generation, and scene assembly pipeline, EnviScale eliminates manual parameter tuning and guesswork.

Quick Start

Interact with the API immediately by posting raw geometries. Here is how to ingest an individual CAD model/mesh or package a multi-object benchmark stage.

curl -X POST https://api.enviscale.com/api/v1/scene \
  -H "X-API-Key: es_live_YOUR_KEY" \
  -F "file=@gearbox_housing.step" \
  -F "export_format=mjcf" \
  -F "collision_quality=balanced" \
  --output gearbox_simready.zip

curl -X POST https://api.enviscale.com/api/v1/scene/composition \
  -H "X-API-Key: es_live_YOUR_KEY" \
  -F "files=@cup.glb" \
  -F "files=@pliers.glb" \
  -F "template=tabletop_manipulation" \
  -F "seed=42" \
  -F "export_format=mjcf" \
  --output tabletop_benchmark.zip

CLI & Python SDK

Automate your robotics training pipeline with the official enviscale package. Provides headless single-asset compilation, Parallel-Axis inertia calculation for multi-part CAD, deterministic scene composition, and domain randomization hooks.

pip install enviscale

1. Command-Line Interface (CLI)

Use the enviscale executable in your asset ingestion scripts and CI/CD pipelines without writing boilerplate code. Set ENVISCALE_API_KEY in your environment.

# Ingest and compile raw 3D mesh or multi-part STEP CAD assembly
enviscale compile gearbox_housing.step \
  --format mjcf \
  --quality balanced \
  --output ./simready_gearbox/

# Container-aware liquid filling profiles
enviscale compile mug.glb --fill full --output ./simready_mug/

# Package multi-object evaluation stage on calibrated tabletop
enviscale compose mug.glb screwdriver.glb \
  --template tabletop_manipulation \
  --seed 42 \
  --output ./tabletop_benchmark/

2. Programmatic Python SDK

The Python SDK integrates directly into your data generation and reinforcement learning training loops:

from enviscale import EnviScale

# Initialize client (picks up ENVISCALE_API_KEY automatically)
client = EnviScale()

# 1. Ingest asset with multi-part Parallel-Axis Theorem inertia
asset = client.compile(
    file_path="lantern.gltf",
    scene_name="lantern_asset",
    export_format="mjcf",
    output_dir="./simready_lantern"
)

print(f"Reconciled Mass: {asset.mass_kg:.3f} kg")
print(f"Full Inertia Tensor: {asset.inertia_tensor}")
print(f"Native Parts ({asset.native_parts_count}):")
for part in asset.native_parts:
    print(f" - {part.name}: {part.material} ({part.mass_kg:.3f} kg)")

# 2. Package benchmark evaluation stage
scene = client.compose(
    files=["lantern.gltf", "screwdriver.glb"],
    template="tabletop_manipulation",
    seed=101,
    output_dir="./sim_stage"
)

print(f"Spawned {scene.object_count} objects in {scene.world_xml_path}")

3. Robotics CI/CD & RL Training Integration

Automate simulation asset validation on every pull request using GitHub Actions:

name: Verify Simulation Assets
on: [push, pull_request]

jobs:
  validate-assets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          
      - name: Install EnviScale
        run: pip install enviscale
        
      - name: Ingest & Certify Simulation Assets
        env:
          ENVISCALE_API_KEY: ${{ secrets.ENVISCALE_API_KEY }}
        run: |
          enviscale compile cad/gripper.step --format mjcf -o ./sim/gripper/
          enviscale compile cad/housing.step --format usd_physics -o ./sim/housing/

Authentication

All API requests must be explicitly authenticated. Generate a key from your dashboard and inject it as the X-API-Key header.

Supported Formats

EnviScale ingests visual, mechanical assembly, or CAD formats, and unrolls nested ZIP packages natively to resolve external textures or material definitions.

Single Object API Reference

Extract physical parameters, analyze geometry, reconcile native multi-part assemblies via the 3D Parallel-Axis Theorem, and generate randomized domain files from a single input model.

Scene Composition API Reference

Generate a multi-object scene composition. Places 1 to 8 files or zip objects onto a layout surface (table, desk, shelf, or bin), resolving physics for each object and returning a single aggregated simulation environment.

Legacy endpoint alias: POST /api/v1/scene/room is preserved for backward compatibility.

Physics Constraints

EnviScale does not estimate physics values arbitrarily. The system enforces strict physical bounds derived directly from geometric properties:

Calibration Overrides

Advanced workflows benefit from injecting real hardware calibration measurements. Optional override parameters let you overwrite inferred defaults:

Domain Randomization (DR) Profiles

EnviScale generates multiple, distinct simulator profiles to support robust sim-to-real transfer. These profiles permute friction parameters and mass distribution:

Robot & USD Validation

Prior to returning response binaries, EnviScale runs automated simulation QA tests on the generated files to prevent physics errors:

X-Processing-Time: 4.82s
X-Confidence: 0.92
X-Final-Mass: 0.3541
X-Inferred-Material: plastic
X-Object-Name: spray_bottle
X-Overrides-Applied: false

Code Examples

Integrate EnviScale processing endpoints into your Python training or dataset preparation scripts.

import requests

url = "https://api.enviscale.com/api/v1/scene"
headers = {"X-API-Key": "es_live_YOUR_API_KEY"}
data = {
    "export_format": "mjcf",
    "collision_quality": "balanced"
}

with open("mug.glb", "rb") as f:
    response = requests.post(url, headers=headers, files={"file": f}, data=data)

with open("mug_compiled.zip", "wb") as out:
    out.write(response.content)

import requests

url = "https://api.enviscale.com/api/v1/scene"
headers = {"X-API-Key": "es_live_YOUR_API_KEY"}
data = {
    "mass_override_kg": "0.24",      # exact weight from scale
    "friction_override": "0.45"      # calibrated slide friction
}

with open("pliers.gltf", "rb") as f:
    response = requests.post(url, headers=headers, files={"file": f}, data=data)

import requests

url = "https://api.enviscale.com/api/v1/scene"
headers = {"X-API-Key": "es_live_YOUR_API_KEY"}

with open("vase_textures_bundle.zip", "rb") as f:
    response = requests.post(
        url,
        headers=headers,
        files={"file": ("vase.zip", f, "application/zip")}
    )

import requests

url = "https://api.enviscale.com/api/v1/scene/composition"
headers = {"X-API-Key": "es_live_YOUR_API_KEY"}
data = {
    "template": "tabletop_manipulation",    # Places on 0.6m table
    "seed": "101",                          # Deterministic layout seed
    "surface_condition": "clean"
}

files = [
    ("files", ("mug.zip", open("mug.zip", "rb"), "application/zip")),
    ("files", ("pliers.zip", open("pliers.zip", "rb"), "application/zip")),
]

response = requests.post(url, headers=headers, files=files, data=data)

with open("compiled_scene_composition.zip", "wb") as out:
    out.write(response.content)

Response Structure

The API responds directly with an `application/zip` stream. Below is the internal format and structure of files contained within the returned archive:

Sample physics_report.json Telemetry Data

{
  "job_id": "8b949e22-4a62-43e7-9381-c886080a8c26",
  "scene_name": "ceramic_vase",
  "object_category": "container",
  "primary_material": "ceramic",
  "unit_resolution": {
    "source_units": "millimeters",
    "scale_factor": 0.001,
    "unit_confidence": 0.95
  },
  "geometry": {
    "volume_m3": 0.000215,
    "bounding_box_m": [0.082, 0.082, 0.165],
    "collision_strategy": "convex_decomposition",
    "is_watertight": true
  },
  "base_physics": {
    "inferred": {
      "mass_kg": 0.516,
      "density_kgm3": 2400
    },
    "final": {
      "mass_kg": 0.516,
      "density_kgm3": 2400,
      "friction_sliding": 0.60
    }
  },
  "is_native_multipart": false,
  "native_parts_count": 0,
  "inertia_source": "regional_mass_distribution_clamped",
  "warnings": [],
  "processing_time_seconds": 3.82
}

Errors & Limits