# 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` (**F**ilm**b**o**x**): 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](https://en.wikipedia.org/wiki/Physically_based_rendering) 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](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos) * **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](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor) 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: ```typescript // 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 ```json { "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: ```typescript // 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 ```json { "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 `vrscene`s 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 `vrscene`s. 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 `vrscene`s 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 `glTF`s 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. ![](https://content.gitbook.com/content/efQOUWnh8WUpteoAKY9N/blobs/uRHr42unWN7JwTKOpRYs/ImportAssets_1.png) 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: ![](https://content.gitbook.com/content/efQOUWnh8WUpteoAKY9N/blobs/5beWrncx54P28B7sTxaj/ImportAssets_2.png) ### .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.