Xzero JS

https://github.com/xzeroent/xzero-js
Admin
Xzero JS is a modern, dependency-free JavaScript library for displaying 3D models, scenes, and 360°...
Tokens:3,266
Snippets:14
Trust Score:4.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install xzero-js with NPM

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Installs the xzero-js package into your project using the Node Package Manager (NPM).

```bash
npm i xzero-js
```

--------------------------------

### Import xzero-js from NPM

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Imports the entire xzero-js library as a namespace when installed via NPM.

```javascript
import * as XzeroJS from "xzero-js";
```

--------------------------------

### Enable Debugging Information for xzero-js

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Activates the display of 3D axes and helpful information for setup and development. It also logs object hierarchy and material information to the developer console.

```html
<xzero-js src="assets/model.fbx" debug zoomable></xzero-js>
```

--------------------------------

### Load xzero-js via CDN

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Includes the xzero-js library from a Content Delivery Network (CDN) using a script tag with `type='module'`.

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/xzero-js@1.2.1/xzero.min.js"></script>
```

--------------------------------

### xzero-js Component API Documentation

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Provides detailed API specifications for configuring the xzero-js component, including attributes for environment display, aspect ratio, autorotation, and debugging.

```APIDOC
xzero-js Component Attributes:

env-background
  - Description: Whether the environment map is displayed as panorama background.
  - Type: Boolean
  - Property: element.envBackground = true;
  - Usage Example: <xzero-js env-background ...>

ratio
  - Description: If the height of the <xzero-js> element is not set by CSS styles, the height is determined by its width and this aspect ratio.
  - Format: Number:Number (e.g., "3:2", "16:9")
  - Property: element.src = "3:2";
  - Usage Example: <xzero-js ratio="3:2" ...>

autorotate
  - Description: Whether the direction of view rotates over time.
  - Type: Boolean
  - Property: element.autorotate = true;
  - Usage Example: <xzero-js autorotate ...>

autorotate-delay
  - Description: Specifies the duration after which autorotate starts or resumes after an interruption.
  - Type: Number (duration in seconds)
  - Default: 0
  - Property: element.autorotateDelay = 4;
  - Usage Example: <xzero-js autorotate-delay="4" ...>

autorotate-speed
  - Description: Specifies the speed of the rotation. A negative factor reverses the rotation direction.
  - Type: Number (factor)
  - Default: 1
  - Property: element.autorotateSpeed = 1.8;
  - Usage Example: <xzero-js autorotate-speed="1.8" ...>

autorotate-elevation
  - Description: Specifies the elevation towards which the view rotates.
  - Type: Number (degree of range: -90 to 90)
  - Property: element.autorotateElevation = 0;
  - Usage Example: <xzero-js autorotate-elevation="0" ...>

debug
  - Description: Displays 3D axes and helpful information for setup and development. Logs information about the object hierarchy and materials in the developer console.
  - Type: Boolean
  - Property: element.debug = true;
  - Usage Example: <xzero-js debug ...>

Related Documentation:
  - For full documentation, visit: https://xzerojs.org
```

--------------------------------

### Configure xzero-js Attributes/Properties

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

API documentation for the `<xzero-js>` element, detailing common attributes and their corresponding JavaScript properties for configuring 3D models.

```APIDOC
xzero-js Element Attributes/Properties:

src (source):
  Description: The source URL of the 3D file. All resources (like textures) should be in the same directory unless you specify a resource-path.
  Supported Types: GLTF/GLB, FBX, OBJ, STL.
  Attribute: `<xzero-js src="file.fbx" ...>`
  Property: `element.src = "file.fbx";`

resource-path:
  Description: Defines a path from which all resources (like textures) are loaded.
  Attribute: `<xzero-js resource-path="https://www.example.com/3d/assets/" ...>`
  Property: `element.resourcePath = "https://www.example.com/3d/assets/";`

draco-path:
  Description: This setting only affects Draco-compressed GLTF files. The Draco decoder files are loaded from this path.
  Note: If draco-path is not set, the "draco" directory should be in the same directory as the 3D model.
  Attribute: `<xzero-js draco-path="https://www.example.com/draco-decoder/" ...>`
  Property: `element.dracoPath = "https://www.example.com/draco-decoder/";`

env (environment):
  Description: URL to an environment map for material reflectivity or use as panorama background. The image must be in equirectangular projection and dimensions should be a power of two (e.g., 512x256). If src is not set, the image is displayed as panorama background.
  Attribute: `<xzero-js env="example.jpg" ...>`
  Property: `element.env = "example.jpg";`
```

--------------------------------

### Import xzero-js Plugins

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Imports specific plugins or core modules from the xzero-js library for extended functionality.

```javascript
import { Animations } from "./core/Animations.js";
import { AutoRotation } from "./core/AutoRotation.js";
import { ElementObserver } from "./core/ElementObserver.js";
import { ModelLoader } from "./core/ModelLoader.js";
import { Overlays } from "./core/Overlays.js";
import { SoftReflection } from './core/SoftReflection.js';
import { SoftShadow } from './core/SoftShadow.js';
import { OrbitControls } from "./three/OrbitControls.mod.js";
```

--------------------------------

### Import xzero-js ES6 Module

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Imports the xzero-js library as a namespace from a local ES6 module file.

```javascript
import * as XzeroJS from "./xzero.min.js";
```

--------------------------------

### Change Model Source Dynamically

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Demonstrates how to change the 3D model source of an `<xzero-js>` element using JavaScript after it has been initialized.

```html
<xzero-js id="example" src="assets/model.fbx"></xzero-js>
					
<button onclick="document.getElementById('example').src='assets/origami.stl';">
	Change src
</button>
```

--------------------------------

### Display 3D Model with xzero-js Element

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Basic usage of the `<xzero-js>` custom HTML element to display a 3D model. The `src` attribute specifies the model file, and `loading` can be set to `lazy` for deferred loading.

```html
<xzero-js src="model.gltf" loading="lazy"></xzero-js>
```

--------------------------------

### Configure Environment Background for xzero-js

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Controls whether the environment map is displayed as a panorama background. If the 'src' attribute is not set, the image specified in 'env' is used as the panorama background.

```html
<xzero-js src="assets/model.fbx" env="assets/environment.jpg" env-background elevation-limit="-90 90" autorotate></xzero-js>
```

--------------------------------

### Dynamically Import xzero-js

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Conditionally imports the xzero-js module only if a `<xzero-js>` element is present on the page.

```javascript
if ( document.querySelector('xzero-js') ) {
	import( './xzero.min.js' );
}
```

--------------------------------

### Configure Aspect Ratio for xzero-js

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Determines the height of the <xzero-js> element when not explicitly set by CSS. The height is calculated based on its width and the specified aspect ratio.

```html
<xzero-js style="display:inline-block" src="assets/model.fbx" ratio="3:2"></xzero-js>
<xzero-js style="display:inline-block" src="assets/model.fbx" ratio="16:9"></xzero-js>
```

--------------------------------

### Enable/Disable Autorotation for xzero-js

Source: https://github.com/xzeroent/xzero-js/blob/main/README.md

Enables or disables the automatic rotation of the view over time. This attribute works in conjunction with other autorotate-related attributes to control the rotation behavior.

```html
<xzero-js src="assets/model.fbx" elevation="45" autorotate autorotate-delay="1" autorotate-speed="1.5" autorotate-elevation="0"></xzero-js>
```
Tokens:
Raw