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 process a single asset or compile a full tabletop room workspace.

curl -X POST https://api.enviscale.com/api/v1/scene \
  -H "X-API-Key: es_live_YOUR_KEY" \
  -F "file=@mug.glb" \
  --output mug_profiles.zip

curl -X POST https://api.enviscale.com/api/v1/scene/room \
  -H "X-API-Key: es_live_YOUR_KEY" \
  -F "files=@pliers.zip" \
  -F "files=@vase.zip" \
  -F "template=tabletop_manipulation" \
  -F "seed=42" \
  --output tabletop_scene.zip

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, and generate randomized domain files from a single input model.

Room Scene API Reference

Generate a multi-object room workspace. 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 MJCF simulation environment.

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/room"
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_room_scene.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
    }
  },
  "warnings": [],
  "processing_time_seconds": 3.82
}

Errors & Limits