
# STL File Import

You can find the STL loader [here](https://cdn.babylonjs.com/loaders/babylon.stlFileLoader.js).

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

To use it, you just have to reference it after Babylon.js:

```html
<script src="Babylon.js"></script>
<script src="babylon.stlFileLoader.js"></script>
```

When using the Babylon npm packages in your own build, it is preferable to register the STL file importer via the top-level dynamic loader registration function `registerBuiltInLoaders`. See [Loading Any File Type](/features/featuresDeepDive/importers/loadingFileTypes#npm) for more information.

If you want to import the STL file importer statically (not recommended), you can do so via:

```javascript
import "@babylonjs/loaders/STL/stlFileLoader";
```

You can read more about [NPM support](/setup/frameworkPackages/npmSupport).

By default, the STL loader swaps the Y and Z axes. To disable this behavior, set:

```javascript
BABYLON.STLFileLoader.DO_NOT_ALTER_FILE_COORDINATES = true;
```



## OBJ File Import

To use it, you just have to reference the loader file:

```html
<script src="babylon.js"></script>
<script src="babylon.objFileLoader.js"></script>
```

You can find it [here](https://cdn.babylonjs.com/loaders/babylon.objFileLoader.js).

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

When using the Babylon npm packages in your own build, it is preferable to register the OBJ file importer via the top-level dynamic loader registration function `registerBuiltInLoaders`. See [Loading Any File Type](/features/featuresDeepDive/importers/loadingFileTypes#npm) for more information.

If you want to import the OBJ file importer statically (not recommended), you can do so via:

```javascript
import "@babylonjs/loaders/OBJ/objFileLoader";
```

You can read more about [NPM support](/setup/frameworkPackages/npmSupport).

### Load

See [how to load from any file type](/features/featuresDeepDive/importers/loadingFileTypes).
Babylon.js will know how to load the obj file and its mtl file automatically:

## Good things to know

- Your model doesn't have to be triangulated, as this loader will do it automatically.
- A `Babylon.Mesh` will be created for each object/group.
- The obj model should be exported with -Z axis forward and Y axis upward to be compatible with Babylon.js.

![Axis](/img/how_to/import-obj/axys.webp)

- By default, because the code is optimized for loading time, UV problems can appear, like this:

![Batman UVs problem](/img/how_to/import-obj/uv-issue.webp)

If you meet this problem, set the variable:

```javascript
BABYLON.OBJFileLoader.OPTIMIZE_WITH_UV = true;
```

Then, you'll get a better texture, but with a longer loading time.

![Batman UVs ok](/img/how_to/import-obj/uv-fixed.webp)

Depending on the modeling program you export your OBJ files from, textures may appear distorted or inverted. As a workaround, you can modify your imported model's UV coordinate scale via setting the variable:

```javascript
BABYLON.OBJFileLoader.UV_SCALE = new BABYLON.Vector2(xValue, yValue);
```

Although not part of the Wavefront OBJ file format, some OBJ files include vertex colors. If you are loading such a file and want vertices with colors, set the variable:

```javascript
BABYLON.OBJFileLoader.IMPORT_VERTEX_COLORS = true;
```

If you have an OBJ file without normals or wish to have them calculated for you, set the variable:

```javascript
BABYLON.OBJFileLoader.COMPUTE_NORMALS = true;
```

When using OPTIMIZE_WITH_UV = true you may experience some discontinuities in shading. Setting OPTIMIZE_NORMALS will help with this problem:

```javascript
BABYLON.OBJFileLoader.OPTIMIZE_NORMALS = true;
```

To have your imported model inverted on the y-axis, set the variable:

```javascript
BABYLON.OBJFileLoader.INVERT_Y = true;
```

To invert your imported textures on the y-axis, set the variable:

```javascript
BABYLON.OBJFileLoader.INVERT_TEXTURE_Y = true;
```

By default if an MTL file cannot be loaded (missing/error) it will silently fail. The model will still be loaded, but if you want to enforce a stricter loading of materials you can use onSuccess() and onError() callbacks accordingly. Set the variable:

```javascript
BABYLON.OBJFileLoader.MATERIAL_LOADING_FAILS_SILENTLY = false;
```

If an MTL is defined in your OBJ and you wish to have it ignored, set the variable:

```javascript
BABYLON.OBJFileLoader.SKIP_MATERIALS = true;
```

The OBJ-Loader's behavior has changed in this PR - [https://github.com/BabylonJS/Babylon.js/pull/14920](https://github.com/BabylonJS/Babylon.js/pull/14884) to support handedness correctly. If you have issues loading your OBJ after the change, but it had worked previously, you can set the following flag to fix it:

```javascript
OBJFileLoader.USE_LEGACY_BEHAVIOR = true;
```

## Supported

- Object/group
- Geometric vertex
  - colors
- Faces
  - triangles
  - quads
  - polygons
- Colors
  - diffuseColor
  - ambientColor
  - specularColor
  - specularPower
  - alpha
- Textures
  - ambientTexture
  - diffuseTexture
  - specularTexture
  - bumpTexture
  - opacityTexture
- Multimaterial
  - For each material defined in the same mesh, it creates a new BABYLON.Mesh.
  - The name of the created BABYLON.Mesh follows this syntax: meshName_mmX
  - X is the nth BABYLON.Mesh created with this method

## Not supported currently

- Smoothing groups (s parameter in OBJ file)
- Illumination (illum parameter in MTL file)
- The different options for loading textures in MTL file.
- A good description about MTL files and their options can be found here: http://paulbourke.net/dataformats/mtl/



## Overview

The OpenUSD file loader imports `.usd`, `.usda`, `.usdc`, and `.usdz` stages. A WebAssembly build of [OpenUSD](https://openusd.org/) composes and extracts the stage in a Web Worker, then Babylon.js creates the scene objects from transferable binary buffers. No intermediate glTF or `.babylon` file is created.

The loader supports:

- OpenUSD composition, including sublayers, references, and payloads, when all dependencies are supplied to the loader
- Transform hierarchies, stage units, up-axis conversion, and visibility
- Polygon meshes, normals, UVs, display colors, geometric subsets, and analytic cube, sphere, cylinder, and cone primitives
- `UsdPreviewSurface` materials and `UsdUVTexture` textures
- Native instances and `UsdGeomPointInstancer` batches backed by Babylon.js thin instances
- `UsdSkel` skeletons, skinning, and animation
- Blend shapes, in-between shapes, and animated morph influences

## Setup

The recommended setup for an NPM application is the dynamic loader registration function. It loads the USD implementation only when a USD file is first requested.

```typescript
import { registerBuiltInLoaders } from "@babylonjs/loaders/dynamic";

registerBuiltInLoaders();
```

You can instead register the USD loader statically:

```typescript
import "@babylonjs/loaders/USD/usdFileLoader";
```

For a script-based experiment, load the complete loader bundle after Babylon.js:

<Alert severity="warning" title="Warning" description="The Babylon.js CDN should not be used in production environments. Serve Babylon.js, the loader bundle, and the OpenUSD runtime assets from your own CDN when deploying an application." />

```html
<script src="https://cdn.babylonjs.com/babylon.js"></script>
<script src="https://cdn.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
```

The loader downloads its OpenUSD worker, WebAssembly module, JavaScript glue, and data bundle when it is first used. Browsers can cache those assets for subsequent imports.

## Loading a USD File

After registering the plugin, use any of the standard scene loader functions:

```typescript
await AppendSceneAsync("https://example.com/assets/model.usdz", scene);
```

Use `LoadAssetContainerAsync` when the imported objects should not be added to the scene immediately:

```typescript
const container = await LoadAssetContainerAsync("https://example.com/assets/model.usda", scene);
container.addAllToScene();
```

See a complete example here: <Playground id="#H0RPC8#0" title="Load an OpenUSD Stage" description="Load a public USDA stage with the Babylon.js OpenUSD file loader." isMain={true} category="Import" />

## Loading a Stage with Sublayers and References

OpenUSD stages often consist of a root layer plus other layers, payloads, and textures. The browser loader stages those files in a virtual filesystem before OpenUSD opens the root layer.

<Alert severity="info" title="Supply every dependency" description="Loading the root layer from a URL does not make its dependencies available automatically. Fetch each external layer, payload, and texture, then pass its bytes through pluginOptions.usd.files. A USDZ package that contains all of its dependencies normally needs only the package itself." />

Virtual paths must preserve the directory structure used by the authored asset paths. For example, assume the root layer is staged as `Package/Scenes/Main.usda`:

```text
Package/
|-- Scenes/
|   `-- Main.usda
|-- Layers/
|   `-- Geometry.usdc
`-- Looks/
    `-- Appearance.usda
```

If `Main.usda` contains:

```usda
#usda 1.0
(
    subLayers = [
        @../Layers/Geometry.usdc@,
        @../Looks/Appearance.usda@
    ]
)
```

load the root and supporting layers as follows:

```typescript
const assetRoot = "https://example.com/assets/Package";

const [geometryLayer, appearanceLayer] = await Promise.all([
    fetch(`${assetRoot}/Layers/Geometry.usdc`).then((response) => response.arrayBuffer()),
    fetch(`${assetRoot}/Looks/Appearance.usda`).then((response) => response.arrayBuffer()),
]);

await AppendSceneAsync(`${assetRoot}/Scenes/Main.usda`, scene, {
    pluginOptions: {
        usd: {
            rootFileName: "Package/Scenes/Main.usda",
            files: {
                "Package/Layers/Geometry.usdc": geometryLayer,
                "Package/Looks/Appearance.usda": appearanceLayer,
            },
        },
    },
});
```

The keys in `files` are virtual paths, not URLs. `rootFileName` gives the root layer its path in that same virtual filesystem, so OpenUSD can resolve each relative asset path exactly as authored.

See this composition working entirely from in-memory layers: <Playground id="#8VK7U1#0" title="Load Multiple OpenUSD Sublayers" description="Compose a root USDA layer with geometry and appearance sublayers supplied through the virtual file map." />

### Loading a Local Directory

For local assets, let the user select a directory and preserve each file's `webkitRelativePath`. If the directory contains multiple `.usd`, `.usda`, `.usdc`, or `.usdz` files, ask the user which one is the root layer.

```html
<input id="usdDirectory" type="file" webkitdirectory multiple />
```

```typescript
const input = document.getElementById("usdDirectory") as HTMLInputElement;
const selectedFiles = Array.from(input.files ?? []);
const rootFile = selectedFiles.find((file) => file.webkitRelativePath.endsWith("/Scenes/Main.usda"));

if (!rootFile) {
    throw new Error("The root USD layer was not selected.");
}

const entries = await Promise.all(
    selectedFiles
        .filter((file) => file !== rootFile)
        .map(async (file) => [file.webkitRelativePath, await file.arrayBuffer()] as const)
);

await AppendSceneAsync(rootFile, scene, {
    pluginOptions: {
        usd: {
            rootFileName: rootFile.webkitRelativePath,
            files: Object.fromEntries(entries),
        },
    },
});
```

### Absolute Asset Paths

`resolveByFileName` defaults to `true`. When an unresolved asset uses an absolute path authored on another computer, the loader can conservatively match one supplied virtual file with the same file name.

```typescript
pluginOptions: {
    usd: {
        rootFileName,
        files,
        resolveByFileName: true,
    },
}
```

This fallback only works when the file name is unambiguous. Preserve the authored directory layout whenever possible, especially when different directories contain files with the same name. Set `resolveByFileName` to `false` to require strict path resolution.

## Diagnostics

Use the loader callbacks to display progress, collect OpenUSD messages, and detect missing dependencies:

```typescript
await AppendSceneAsync(rootFile, scene, {
    pluginOptions: {
        usd: {
            rootFileName,
            files,
            onProgress: ({ phase, message }) => {
                console.log(phase, message);
            },
            onLog: (level, message) => {
                console.log(`[${level}] ${message}`);
            },
            onComplete: ({ timings, statistics, missingAssets }) => {
                console.table(timings);
                console.table(statistics);
                console.log("Missing assets:", missingAssets);
            },
        },
    },
});
```

`missingAssets` lists references that OpenUSD could not resolve from the root layer, a USDZ package, or the supplied virtual files.

## Hosting the OpenUSD Runtime

By default, the worker and OpenUSD runtime are downloaded from the Babylon.js CDN. To host them with your application, copy all four runtime files from the same protocol version and configure their URLs for each load:

```typescript
const importerRoot = "/runtime/babylonUsdImporter/";

await AppendSceneAsync("/assets/model.usdz", scene, {
    pluginOptions: {
        usd: {
            workerUrl: `${importerRoot}babylon-usd-importer.worker.js`,
            glueUrl: `${importerRoot}babylon-usd-importer.js`,
            wasmUrl: `${importerRoot}babylon-usd-importer.wasm`,
            dataUrl: `${importerRoot}babylon-usd-importer.data`,
        },
    },
});
```

Keep these four files together and use the protocol version associated with your `@babylonjs/loaders` version. Mixing runtime files or protocol versions is not supported.

## Current Limitations

- `UsdPreviewSurface` is supported; MaterialX and other surface shader networks currently use the default material.
- PNG, JPEG, BMP, and WebP textures are supported. Convert other texture formats before loading them in a browser.
- Animated point-instancer data is imported at its first authored frame as static thin instances.
- Nested point instancers are not currently supported.
- Mesh-name filtering is not currently supported; `ImportMeshAsync` imports the complete composed stage.


.stl File Loader Plugin