Importing Assets

By default, importing an asset will check for existing assets with the same name in the current folder on the platform, and update that asset if it already exists. It will only create a new asset if no other assets exist in the current folder with that file name.

This update will behave similar to the current asset merge feature. The update will retain all mesh operators and material assignments, as long as the individual node names and hierarchy matches. All attributes and rules will also be retained. Also of note, all child nodes must be uniquely named. Attempting to update an asset that has like-named child nodes will fail.

For FBX and OBJ file imports, if the new asset being imported contains materials that have the same name as materials already in that Asset folder, then the materials on the platform and their current settings will be retained. The import will ignore these materials from the FBX or the OBJ file. If the FBX or OBJ file has materials that do not exist on the platform in the current asset folder, new material assets will be created.

The glTF, USDZ, and VRSCENE file imports will overwrite the materials on the platform that have the same name.

Import Formats

Threekit supports the following import formats:

• .dxf

• .fbx

• .gltf/.gltfzip

• .glb

• .iges/.igs

• .obj/.objzip

• .pbrtex

• .pbrmat

• .pbrzip

• .stl

• .step/.stp

• .svg

• .usdz

• .usda

• .usdc

• .vccglb

• .vrscene/.vrscenezip

• *limited support: .zip

Images

• .exr

• .gif (first frame only)

• .hdr

• .jpg

• .png

• .svg

Fonts

• .otf

• .ttf

Importers

CAD

File Extensions

• stl

• step/stp: Standard for the Exchange of Product model data

• iges/igs: Initial Graphics Exchange Specification

Supported Features

• Materials (color only)

• Meshes

Unsupported Features

• Level of Detail

• Lines (wire and edge)

• Vertices

Modifications

Meshes

PolyMeshes are created from face, shell, and solid shape types. Those shapes are triangulated to be usable in WebGL.

Nulls

Nulls are created from compound and compsolid shape types. They reflect the hierarchy inside the CAD file.

FBX

File Extensions

• fbx (Filmbox): supports both ASCII and binary versions

• obj/objzip: Wavefront OBJ file, objzip is to package the materials (mtl) and images needed

• dxf: Drawing Exchange Format

Supported Features

• Cameras:

  • Orthographic

  • Projective

• Lights:

  • Area

  • Directional

  • Point

  • Spot

• Materials:

  • Bump factor

  • Diffuse color and factor

  • Emissive color and factor

  • Normal map

  • Opacity Mode (transparency vs opacity)

  • Opactiy factor

  • Specular color and factor

  • Shininess

• Meshes:

  • Colors

  • Creases

  • Normals

  • Multiple UVs

  • Smoothing groups

  • Tangents

Unsupported Features

• Animations

• Bones

• Meshes:

  • Blend Shapes

  • Negative indices for face materials

  • Skinning

• Perfect material representation:

  • Threekit uses PBR materials that cannot be represented in FBX.

• Transform:

  • Inherit types other than RSrs

  • Geometric Translation

Modifications

Cameras

• Add a post rotation of 90 degrees around the Y-axis to be oriented along the negative Z-axis (for FBX only).

Lights

• Add a post rotation of 90 degrees around the X-axis to be oriented along the negative Z-axis (for FBX only).

• Unknown light colors are set to white.

• Unknown light intensities are set to 1.

Material

• shininess (s) is converted to roughness (r) using r = sqrt(2.0 / (s + 2.0)).

• color (c) and factor (f) pairs are combined to create a new color (c') using c' = c*f + (1-f).

Meshes

• Flat normals are computed for missing normals.

• Maps using reference and mapping modes (like normals and tangents) are converted to an indexing method matching Threekit.

• Smoothing groups are used to alter the normals and are discarded.

glTF

File Extensions

• gltf: JSON representation for glTF

• glb: binary representation for glTF

• gltfzip/zip: packaging a gltf/glb with the textures and external binary buffers

Versions

• 2.0

Supported Features

• Default Material

• Materials:

  • Alpha modes opaque and blend

  • Double sided

  • Emissive factor and texture

  • Normal texture

  • Occlusion texture

  • PBR metallic/roughness:

    • Base color and texture (opacity included here)

    • Metallic factor

    • Metallic/roughness texture

    • Roughness factor

• Meshes:

  • Instances

  • Missing indices

  • Multiple UV channels

  • Normals

• Node Hierarchy

• Sparse Accessors

• Textures

Extensions

• KHR_draco_mesh_compression: Mesh compression using Draco.

Unsupported Features

• Animations

• Cameras

• Line Sets

• Materials:

  • Alpha modes mask

• Mesh tangent space

• Morph targets

• Multiple scenes

• Point Clouds

• Skeleton / Bones

• Skinning

• Version 1.0

Khronos Extensions

• KHR_lights_punctual: Defines lights

• KHR_materials_clearcoat: Adds a clear coat layer over a PBR metallic/roughness material

• KHR_materials_pbrSpecularGlossiness: Alternative to PBR metallic/roughness

• KHR_materials_unlit: Material that won't receive lights/cast shadows

• KHR_mesh_quantization: Allow vertex attributes to be stored using 8- or 16-bit storage

• KHR_techniques_webgl: Can define custom shaders using JSON and GLSL

• KHR_texture_transform: Express tiling and offset properties for textures

Vendor Extensions

There's no plan current to support any of these extensions. They're likely specific for another tool and might not behave well in a WebGL context.

Modifications

Meshes

• Mesh compressed with the Draco extension are decompressed to be used directly in WebGL.

• Flat normals are computed for missing normals.

• UV's v values are flipped to match the WebGL definition.

Images

• Large images are reduced to have a maximum size of 4096x4096.

Images

File Extensions

• exr

• gif (grab the first frame only)

• hdr

• jpg

• png

• svg

Unsupported File Extensions

The image importer is based on the MIME type. A lot of file extensions have a MIME type of the form image/*, but that doesn't mean they can be imported.

Modifications

• HDR and EXR files are converted to PNG to be used in WebGL.

• Images larger than 4096x4096 or not power of two sizes are resized to fit the closest power of two rectangle matching the aspect ratio (ex.:: an image 720x400 is resized to 1024x512).

PBR

This is a custom format designed to match as closely as possible the data structures used by Threekit to represent materials and images.

The PBR import consists of three file formats:

• .pbrtex: a JSON file that describes a texture

• .pbrmat: a JSON file that describes a material

• .pbrzip: a zip archive that contains all the needed files

Zip Archive

A .pbrzip file is created just like any other zip archive, but with a different extension. The archive is expected to contain every material (.pbrmat), texture (.pbrtex), and image file needed.

For now, it's only possible to import the PBR definition as a .pbrzip.

Texture

Properties

The JSON structure inside a .pbrtex adheres to the following Typescript definition:

// image file expected to be in the '.pbrzip'
type File = string;

// how the texture is sampled,
type Filter =
  | 'linear'
  | 'linearMipMapLinear'
  | 'linearMipMapNearest'
  | 'nearest'
  | 'nearestMipMapLinear'
  | 'nearestMipMapNearest';

// how the texture is wrapped
type Wrap = 'none' | 'repeat' | 'mirror';

// how to resize the image if needed, must be a power of two for WebGL
type Resize = 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096;

// the content of the '.pbrtex'
interface PbrTex {
  image: File;

  // texture sampling
  magFilter?: Filter = 'linear';
  minFilter?: Filter = 'linearMipMapLinear';

  // texture wrapping
  wrapU?: Wrap = 'repeat';
  wrapV?: Wrap = 'repeat';

  // texture optimization for WebGL
  optimizeImage?: boolean = true;
  resizeImage?: boolean = false;
  resizeWidth?: Resize = 512;
  resizeHeight?: Resize = 512;

  // texture transform
  uOffset?: number = 0.0;
  vOffset?: number = 0.0;
  uTile?: number = 1.0;
  vTile?: number = 1.0;
  rotation?: number = 0.0; // rotation is in degrees

  // misc.
  invert?: boolean = false;
  gainPivot?: number = 0.0;
  gain?: number = 1.0;
  brightness?: number = 0.0;
  generateMipMaps?: boolean = true;

  // for normals and anisotropy maps only
  redFlip?: boolean = false;
  greenFlip?: boolean = false;
  swapRG?: boolean = false;
}

TypeScriptCopy

Any missing parameters are filled in by the default values.

Note

If an image used by a texture file is not listed in the .pbrzip, the import is going to fail.

Example

{
  "image": "myImage.png",
  "magFilter": "linear",
  "wrapU": "repeat",
  "vTile": 0.5,
  "invert": true
}

JSONCopy

Material

Properties

The JSON structure inside a .pbrmat adheres to the following Typescript definition:

// refers to a '.pbrtex'
type PbrTexFile = string;

interface Color {
  r: number;
  g: number;
  b: number;
}

const BLACK: Color = { r: 0, g: 0, b: 0 };

interface PbrMat {
  // anisotropy is being worked on

  aoFactor?: number = 1.0;
  aoMap?: PbrTexFile;

  baseColor?: Color = { r: 0.94, g: 0.94, b: 0.94 };
  baseMap?: PbrTexFile;
  baseMapTransparent?: boolean = false;

  bumpFactor?: number = 1.0;
  bumpMap?: PbrTexFile;

  clearCoat?: number = 0.0;
  clearCoatNormalFactor?: number = 1.0;
  clearCoatNormalMap?: PbrTexFile;
  clearCoatRoughness?: number = 0.25;

  emissiveColor?: Color = BLACK;
  emissiveMap?: PbrTexFile;
  emissiveScale?: number = 1.0;

  ior?: number = 1.6;

  lightColor?: Color = BLACK;
  lightMap?: PbrTexFile;

  metallicFactor?: number = 0.0;
  metallicMap?: PbrTexFile;

  normalFactor?: number = 1.0;
  normalMap?: PbrTexFile;

  opacityFactor?: number = 1.0;
  opacityMap?: PbrTexFile;

  roughnessFactor?: number = 0.25;
  roughnessMap?: PbrTexFile;

  sheenFactor?: number = 0.0;

  specularColor?: Color = { r: 1, g: 1, b: 1 };
  specularMap?: PbrTexFile;

  transparencyFactor?: number = 0.0;
  transparencyMap?: PbrTexFile;
}

TypeScriptCopy

Any missing parameters are filled in by the default values.

Note

If a map refers to a missing .pbrtex file, the map is considered unassigned and the import continues.

Example

{
  "baseMap": "base.pbrtex",
  "baseColor": { "r": 1.0, "g": 0.0, "b": 0.5 },
  "metallicMap": "metal.pbrtex",
  "opacityFactor": 0.9
}

USD

Notes

This is more a USD importer. It supports everything from the USDZ format used for augmented reality and more.

File Extensions

• usdz: format for AR

• usda: ASCII USD scene

• usdc: binary USD scene

Supported Features

• Coordinate System

• Materials:

  • Clear coat

  • Diffuse

  • Emissive

  • Metallic

  • Normal

  • Occlusion

  • Opacity

  • Roughness (not adjusted to match AR Kit)

  • Specular

• Meshes:

  • Interpolation modes constant, vertex, varying, and uniform

  • Multiple materials, assumes:

    • elementType is set to face

    • familyName is set to materialBind

  • Multiple UVs:

    • Only two primvars are supported, Texture_uv and st.

  • Normals

• Node Hierarchy

• Textures

Unsupported Features

• Animations

• Cameras

• Classes

• Instancing

• Layers

• List Editing

• Materials:

  • Displacement texture and output

  • Index of refraction (IOR)

  • Opacity threshold

  • Specular/Glossiness material workflow

    • It just sets the metallic factor to zero.

  • UsdTransform2d for texture tiling and offsets

• Native Geometry Classes (like Cube or Sphere)

• Overs

• Render Settings

Modifications

Meshes

• Flat normals are computed for missing normals.

Vrscene

Note

A vrscene is a scene description that can be rendered in V-Ray. It contains a camera, lights, geometries, materials, and settings.

File Extensions

• vrscene

• vrscenezip/zip: a zip archive with at least one vrscene and images

Import modes

There are three import modes for vrscene. The right one can be selected when importing from the Asset page.

Scene Asset

This is the default behavior. The created scene asset also contains the proper logic (attributes and rules) to be used as a stage.

The import produces the following hierarchy:

• V-Ray Axis System: A null with, if necessary, a pre-rotation of -90 degrees around the X-axis to convert the Z-up axis system of the vrscenes into the Y-up axis system of Threekit. If more than one vrscene defines a SettingsUnitsInfo, the first found is selected and the others are discarded.

  • Cameras (optional): The cameras extracted from the vrscenes. Maximum one per vrscene. If physical camera settings are also defined, an extra operator, containing some of these settings, is added with the camera. The first camera found is set to be the scene asset's camera.

  • Vrscene Nodes: One node per vrscene. Each vrscene node can be disabled if needed. It can be moved around just like any other transformable node. When rendering, all the transformable objects in this specific vrscene are moved accordingly.

• For Models: A null node scaled to match the main vrscene's units (as mentioned in V-Ray Axis System). This is needed to get the lights to work perfectly with any nodes placed under this one.

  • Model: A model node already configured with a rule through the Asset attribute.

Model Asset

Imports just like the Scene mode without the camera and the logic to add an asset.

Template Materials

Template materials are materials extracted from vrscenes to be imported as material assets. These materials cannot be used directly in WebGL, but can be assigned to any polymesh node and rendered in V-Ray.

The template part comes from analysing the material and creating exposed properties that can be modified like any other material properties in the editor or through the attributes. Changing any of these properties overrides the default behavior defined by the material.

When creating a V-Ray material to be imported as a template in a tool like Maya, the exposed properties must have the prefix TK_ in their names. Only textures and user-defined properties can be exposed.

It's not possible to create template materials from the following V-Ray plugins:

• MtlGLSL

• MtlMaterialID

• MtlMDL

• MtlMulti

• MtlOSL

• MtlOverride

• MtlRenderStats

• MtlSelectRE

• MtlVRmat

Vector

File Extensions

• svg

Note

Vector assets can be used in same places are texture assets (images). The vector assets are treated differently than texture assets because the data can also be used to create shapes.

Zip

Notes

Imports a zip file containing at least one supported import format.

File Extensions

• zip

Constraints

Images

In the case of a zip file filled with image files only, every image is imported as a texture asset. These are the supported image formats:

• .png

• .jpg

• .svg

• .hdr

• .exr

Multiple files

Other file types, with exception of vrscene and pbrmat, are restricted to only one file that can be imported. For example, if the zip file contains:

1. one glTF, one binary buffer (bin), and images: The glTF file is imported and uses the binary buffer and images.

2. two glTFs and images: The import fails, only one glTF is allowed.

3. one glb, one FBX, and images: The import fails, don't know which file (the glb or FBX) should be the primary import.

4. multiple vrscene and images: The import follows the vrscene specifications.

5. one vrscene and one pbrmat: The import fails; even if both file types are allowed multiple times, they're not compatible.

Font

File Extensions

• otf: OpenType/CFF Font

• ttf: TrueType Font

VFB Presets

Note

A vccglb is a preset applied at the end of a V-ray render to modify the final image. Common use cases are for color correction or adding a background image.

On import, it creates a Preset asset. This asset can be specified in a Scene asset's main node in the V-ray Preset Asset property.

File Extensions

• vccglb

• vccglbzip: a zip archive with a vccglb file and its dependencies

vccglbzip

Some vccglb files have dependencies, like a *.cube file for color correction or an image as background. That data is specified outside of the file and is require for accurate renders.

To work with these dependencies, we have two constraints:

1. The background image file must be specified with its name only

   • When creating the vccglb file, you might specify a background image with the full path (ex.: C:\MyData\Test.png or /home/user/MyData/Test.png), this is fine to do local tests

   • A full path directory cannot be used on other system and vccglb files cannot be modified inside our system

   • Before saving the vccglb file, changing value to Test.png allows this to work inside Threekit

2. All dependencies, and their dependencies (.ocio files might require extra files) must all be packaged together in a zip archive and have the file extension changed to .vccglbzip

We also recommend to bake in the LUT file.

Those steps must be respected and once imported in Threekit, there's no way to verify that a vccglb file works perfect other than using it. Missing data doesn't cause any problems or crashes; if a dependency cannot be found, it's simply ignored.

Video

File Extensions

• mp4: MPEG-4

Modifications

No modifications yet.

LUT

File Extensions

• CUBE: Cube LUT

DWG

File Extensions

• dwg

Supported Features

• 3D Drawing

• Meshes

• Simple Materials

Unsupported Features

• Lines

• Points

• Materials with diffuse textures

Modifications

Names

The element ID is used as name of the node. In case of duplicated names, a numbered suffix is added.

API options

• fallbackUnitScale: unit scales are not always specified in DWG and when missing, the model is treat as being in meter. fallbackUnitScale can be used to apply a scaling factor to convert the imported to model to meters. (ex.: foot: 0.3048, millimeter: 0.001)

Common

Import

When importing a new file, assets that represent the import data are created. Asset names match the file name, stripped of its extension.

Generally, there will be only one model or scene asset create per file imported, where the geometric objects are placed. Multiple material and texture assets can be created. The texture assets are usually used by material assets and the material assets are used by the model or scene asset.

Update

An update happens when importing (or reimporting) a file and there are already assets with similar names (if there are multiple instances, the most recent one is used). In this case, the existing assets are updated with the new version of the file. Missing assets are created. Note that two files with the same name, but different extensions, say Helmet.gltf and Helmet.fbx, will trigger an update of the Helmet asset.

On update, the operators that were added are preserved under one condition; namely, if their position, in the operator stack, is not defined by the update process. Before the update, suppose a PolyMesh node MyMesh contains in its PolyMesh plug the operators Mesh, UV Map, and Normals. Then the update creates the PolyMesh node MyMesh, with operators Mesh and Tesselate, and the final updated node would have the operators Mesh, Tesselate, and Normals. After the update, if any preserved operators are causing problems, it's the artist's job to fix those.

There are three options related to updates:

• Update Materials: whether or not to update the material assets. Missing assets are created.

• Update Textures: whether or not to update texture assets. Missing assets are created.

• Preserve Updated Nodes: in updated model assets, to preserve nodes that are not in the updated version.

Import Asset Dialog - Bulk Importing Options

Asset Imports can be controlled at scale or individually with the new Asset Import dialog options.

You can import multiple assets at once and either set their type as a group or override them individually.

You can also import materials and textures (for model assets) or skip them and just import the models.

If the assets already exist in the folder you're importing into, you will be warned and be able to decide how to handle the import: update the existing assets, create a new version, or skip the duplicate:

.Zip Files

ZIP file limitations:

• Uploading ZIP files will not show an import dialog box. The contents will get automatically uploaded to ThreeKit.

• In case of duplicate assets with the same name, the uploader will create new copies with an incremental number, instead of updating the existing assets

• ZIP files are not allowed to contain multiple 3D model files (FBX, glTF, etc.). Only one single 3D model file is allowed per ZIP, along with supporting textures

These limitations are only specifically for files that end with the .zip extension. They do not apply to files like .vrscenezip, .pbrzip, etc.