# AR Model Editor 1\. Download -------- ### 1.1 App Download Please click the below link to download the "Kivicube AR Model Editor" from **Google Drive**. **Google Drive:** #### **v1.2.1 version** **Update log:**\ • Updated the underlying model conversion middleware, with higher performance and compatibility;\ • When exporting the model, the texture quality and texture size can be set to original correspondingly;\ • When importing FBX and exporting in USDZ, Apple's native conversion capability is added, which has more flexible conversion compatibility; **v1.2.0 version** **Update log:**\ • Support DAE format with higher compatibility;\ • Added visual grid selection, convenient for users to adjust model materials intuitively;\ • When the material is adjusted, the texture and color can be set more conveniently;\ • Support changing the mesh name, material name and animation name;\ • Support the bottom center point of the model to the origin of the world coordinate system;\ • When you are previewing your model in real time, you can save the screenshot to your device or upload it to the Kivicube platform as a thumbnail;\ • Support more environment maps and background images, which is convenient for users to preview the model effect in real time;\ • Updated the underlying model conversion middleware, with higher performance and more compatibility;\ • During FBX import, users can customize the import settings;\ • Fixed the bugs about incorrect rotation or scaling of some models; **1.2 App Installation** **1.2.1 Unzip the downloaded zip file**
![](/files/-MEfSkizMP7q2WKN4TEa) #### 1.2.2 **Double-click the unzipped file** ![](/files/-MEfSyaaYfZHdVdnee9Q) #### 1.2.3 **Drag** **the "kivicube Model Editor.app" to "Dock"** ![](/files/-MEfT5f3wmUot9iAZjqQ) #### 1.2.4 **Problems during installation** #### 1.2.4.1 **"Kivicube Model Editor" is damaged and cannot be opened** Note: If the following prompt appears, please refer to this link:
![](/files/-MEfTM_I_DJZ4ipr7nY0) #### 1.2.4.2 **"Kivicube Model Editor" can not be opened because it is not downloaded from App Store** ![](/files/-MEfTnr-gp__0_pqKnQa) If the above picture appears, please choose Apple menu  in the upper left corner of the desktop, click "System Preferences"-"Security and Privacy"-"General", and finally click "Open anyway". ![](/files/-MEfUA1rkqpWItD-xBKK) #### 1.2.4.3 **Whether you would move the program to the "application" folder** ![](/files/-MEfYr65Zg9tT08z50Td) As shown in the picture above, if this pop-up prompt appears, please click *Move to the "Application" folder*. #### 1.2.4.4 **"Kivicube Model Editor.app" can't be opened because Apple cannot check** **it for malicious software** ![](/files/-MEfZ24EG7WYyb_QWp_I) If the above picture appears, please choose Apple menu  in the upper left corner of the desktop, click "System Preferences"-"Security and Privacy"-"General", and finally click "Open anyway".\
![](/files/-MEfZCQncGvgcO-NbL0P) ## 2. **Function Overview** With the development of the AR/VR/3D industry, traditional 3D model formats is no longer compatible with the latest trends. The glTF and USDZ models are launched out at this stage. Among them, glTF has been applied in Google Scene Viewer and USDZ has been applied in Apple AR Quick Look. In order to achieve a better 3D rendering effect, the Kivicube platform also uses the glTF format. **The user can first adjust the model through this tool, export in gltf or glb, and then upload it to the Kivicube.** This is where the AR Model Editor comes in and it is used to convert traditional models to AR models and it supports: * Importing .obj, .gltf, .glb, .fbx, .dae, .3ds and .dxf * Exporting .gltf, .glb and .usdz * Model material editor * Animation export * Set the position of the model * Set the orientation of the model * Set the size of the model * Set the copyright information of the model * Real-time modification and preview of the model, and supports adjustment of parameters during preview * View the attributes of the model * Simplified Chinese, Traditional Chinese, English * Uploading models to Kivicube material library * Shortcut key operation * Texture compression function, you can set appropriate texture quality and size ## 3. UI **Introduction** ### 3.1 **Model import interface** When dragging a FBX model into the editor, you can make some import settings. Normally please use the default settings.
| Setting item | Description | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Automatically calculate vertex normal |

  1. Never: Will not calculate vertex normal automaticallyc;
  2. Always: The vertex normal will be calculated automatically.
| | Animation frame rate | If the model is animated, it can be converted to the set frame rate. | | FBX lighting |

After checking, the lighting information in the FBX file will be converted to the glTF file;

Please note: Kivicube does not support glTF light extension, please do not check this item; if it is used in other places, it can be checked.

| | Blend Shape Normals | Keep Blend Shape Normals after checking | | Blend Shape Tangents | Keep Blend Shape Tangents after checking | ### 3.2 **Grid** **Name** ![](/files/-MEfad16FLI_5FL3aw91) When a certain mesh of the model is selected, the selected mesh (red part) is previewed in real time on the right window, and the material name below will display one or more materials correspondingly to this mesh. ### 3.3 **Material Name** * After dragging a model, the program will automatically analyze the material names contained in the model, and then you can edit and set different materials accordingly; * If no material is set for the model mesh, the program will automatically preset a material for each mesh; * There will be various materials in a model, so please be sure to set all the materials. ### 3.4 **Export Format** * gltf: .glTF format containing .gltf, .bin and texture files, supports two PBR materials (**metal roughness and specular gloss**) and one non-illuminated material, supports no animation, a period of animation and animation animation export; * glb: Binary format that combines .gltf, .bin and texture files into one file, supports two PBR materials (**metal roughness and specular gloss**) and one non-lighting material, supports no animation, one animation, multiple animations and all Animation export; * usdz: currently only supports one kind of PBR material (**metal roughness**), supports no animation, a segment of animation export, and compatible with iOS12 and iOS13. ### 3.5 **Material Editor** | **Material type** | **Setting item** | **Description** | | :---------------------------------------------: | :-----------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | |


Metal/Roughness

|


Base Color

|

  1. Export gltf/glb model: setting texture and color will take effect in the same time; the setting transparency only takes effect when the "transparency" setting item below is set to "transparent BLEND";
  2. Export the usdz model: When setting the texture and the color, only the texture will take effect; setting the transparency is not supported, please note that if you need the model to be transparent, you need to set the "opacity".
| | |


Opacity

|

  1. Export gltf/glb model: this item is not supported;
  2. Export the usdz model: Please note that if you need the model to be transparent, you need to set this, you can set the map or directly set the opacity.
| | |


Roughness

| | | |


Metallic

| | | |


Clear Coat

| Export gltf/glb model: this item is not supported | | |


Clear Coat Roughness

| Export gltf/glb model: this item is not supported | | |


Emission

|

  1. Export gltf/glb model: the set texture and the set color will take effect at the same time;
  2. Export the usdz model: when setting the texture and color, only the texture will take effect;
  3. When usdz simulates the unlit material, the basic color texture and emission texture can be set to basic color in the same time to do the simulation and cancel all the other options for the other textures.
| | |


Occlusion

| | | |


Normal

| | |


Specular/Glossiness

|


Diffuse

|

  1. Export gltf/glb model: setting texture and the color will take effect in the same time; the set transparency only takes effect when the "transparency" setting item below is set to "transparent BLEND";
  2. Export usdz model: not supported
| | |


Specular

| Export usdz model: not supported | | |


Glossiness

| Export usdz model: not supported | | |


Emission

|

  1. Export gltf/glb model: setting texture and the color will take effect in the same time;
  2. Export usdz model: not supported
| | |


Occlusion

| | | |


Normal

| | |


Unlit

|


Base Color

|

  1. Export gltf/glb model: setting texture and the color will take effect in the same time; the set transparency only takes effect when the "transparency" setting item below is set to "transparent BLEND";
  2. Export usdz model: not supported
| | **General** | Transparency | Export usdz model: this item is not available, if you need transparency, please set the "opacity" item separately | | | Show |

  1. Export gltf/glb model: please set it to "transparent BLEND" if you need transparent material, otherwise please set it to "opaque OPAQUE"
  2. Export usdz model: this item is not available
| > Note: When setting textures for materials, only .jpg, .jpeg and .png format images are supported. ### 3.6 **Export animation** | **Export Format** | Expected Result | Setting item | | ----------------- | ----------------------------------------------- | ------------------------------------ | | **gltf/glb** | Static model or do not want to export animation | No animation | | | Export only a certain animation | Choose the name of this animation | | | Export multiple animations | Choose the names of these animations | | | Export all animations | Choose the names of all animations | | **usdz** | Static model or do not want to export animation | No animation | | | Export only a certain animation | Choose the name of this animation | | | Export multiple animations | Not support | | | Export all animations | Not support | ### 3.7 Position ![](/files/-MEfdL-utWl9VulHQ6vn) The program will automatically calculate the position of the model dragged into the editor and display the positional relationship between the bottom center point of the model and the origin of the coordinate system. Click the button in the preview window to return the bottom center of the model to the coordinate origin. ### 3.8 **Export Direction** When the actual model is displayed, sometime it is found that the direction of the model does not meet expectations, you can set the direction of the model here.
### 3.9 **Export Zoom** When the actual model is displayed, sometimes it is found that the model is too large or too small, you can set the zoom of the model here. Please note: When exporting usdz, a folder will be generated containing two files, such as xxx-iOS12.usdz and xxx.usdz. For AR Quick Look on iOS12, please use xxx-iOS12.usdz, iOS13 and above Please use xxx.usdz. ### 3.10 **Texture Quality** * If it is set to the "compression" option, you can continue to set the "compression ratio", the default is 80%, if the exported model is obviously found that the texture definition is seriously lost, we recommend you to increase this parameter; * If it is set to the "Original" option, the "Compression Ratio" and "Texture Size" options can not be used, and the model editor will use the original model texture material. ### 3.11 **Texture Size** * Standard definition (1024px): means that the long side of all textures of the current model will be scaled to 1024px, and the short side will be scaled proportionally; if the long side of the texture does not exceed 1024px, it will stay with its original resolution; * HD (2048px): means that the long side of all textures of the current model will be scaled to 2048px, and the short side will be scaled proportionally; if the long side of the texture does not exceed 2048px, it will stay with its original resolution; * Original: means that all textures of the current model are the original texture size. ### 3.12 **Copyright Information** You can type in your copyright information here. ### 3.13 Preview Once click the Preview, a new page will open and display the current model in real time. #### 3.13. **Preview gesture operation** | Equipment/ Control | Move (translation) | Zoom | Rotation (circular) | | ------------------ | ----------------------------------------------- | ------------------- | ----------------------------------- | | Mouse | Click right and long press to move | Mouse wheel sliding | Click left and long press to move | | Trackpad | Long press with two fingers to move | Two finger to zoom | Long press with two fingers to move | | Keyboard | Keyboard up, down, left and right click to move | not support | not support | #### 3.13.2 **Model attribute** ![](/files/-MEffE8C0Zd9c5nuR4fi) It is axiomatic that 3D rendering requires enormous performance, especially on the mobile terminal. This requires that the attributes of the model uploaded by the user should be reasonable. | Attribute Type | Attribute Item | Reference | Recommendation | | -------------- | ------------------------- | -------------------------------------------- | ------------------------------------------- | | Grid | Number of grids | Single model ≤10; entire scene ≤50 | Single model ≤5; entire scene ≤10 | | | Number of triangles | Single model ≤50,000; entire scene ≤200,000 | Single model ≤30,000; entire scene ≤60,000 | | | Number of vertices | Single model ≤100,000; entire scene ≤400,000 | Single model ≤60,000; entire scene ≤120,000 | | Material | Number of materials | Single model ≤10; entire scene ≤40 | Single model ≤5; entire scene ≤10 | | Texture | Number of textures | Single model ≤10; entire scene ≤40 | Single model ≤5; entire scene ≤10 | | Animation | Animation number | Single model ≤10; entire scene ≤40 | Single model ≤5; entire scene ≤10 | | | Number of bones | Single model ≤80; entire scene ≤160 | Single model ≤60; entire scene ≤120 | | | Number of transformations | Single model ≤50; entire scene ≤100 | Single model ≤30; entire scene ≤60 | \ On the other hand, it is also recommended to follow such indicators:\ Single model gltf entire folder or glb file ≤ 5M; \ The entire gltf entire folder or glb file ≤ 20M; #### 3.13.3 Model Size The size here is: when using Google Scene Viewer or Apple AR Quick Look, the size of the model displayed in the environment is the size of the gltf or usdz model.
#### 3.13.4 **Preview Scene Setting** ![](/files/-MEfgTpV_y9i--Ob44C8) | **Type** | Item | Description | | -------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Display** | Background | Show background picture | | | Model mesh | The display of the meshed model is helpful to analyze which parts of the current model have too many triangles. | | | Skeleton | Show bones | | | Coordinate grid | Display reference grid, 50cm per grid | | | Automatic rotation | Automatically rotate around the Y axis of the model center | | | Screen space shift | Check and uncheck gestures are different | | | Central background color | When the background is not displayed, the background of the scene is composed of a pure color gradient from the center to the surroundings. | | | Surrounding background color | When the background is not displayed, the background of the scene is composed of a pure color gradient from the center to the surroundings. | | **Light** | Color space | Please keep the default setting. | | | Gamma correction | Please keep the default setting. | | | Environment map | Switch between different environment maps to view different reflections of the model. | | | Exposure | Set the exposure color of the scene, generally please keep 1 | | | Add light | Please keep the default setting. | | | Ambient light intensity | Adjust the overall light intensity effect of the model. | | | Ambient light color | Adjust the overall lighting color effect of the model. | | | Parallel light intensity | Adjust the parallel light intensity effect of the model. | | | Parallel light color | Adjust the parallel light intensity effect of the model. | | **Animation** | Play speed | Generally, please keep the default 1 | | | Play all | After clicking, the model can play multiple animations in the same time | | **Capability** | FPS | The frame rate of the model on the current device. Generally, the performance of macOS is much higher than that of mobile devices, **so it should be kept at 60 here. If it is lower than 60, the current model needs to be optimized.** | | | Time consuming | Time-consuming of model rendering is divided by 1000 to get the frame rate. | #### 3.13.5 **Reset Button** Click to restore the model to the initial preview state. #### 3.13.6 **Model at the center point button** After clicking, you can return the center point of the bottom of the model to the origin of the coordinate system. At this time, you will see that the position parameters in the program are all reset to zero:\ ![](/files/-MEficHPNlxbtI_EJNzZ) #### 3.13.7 **Screenshot Button** Click the screenshot to save the screenshot of the current preview window, and you can modify the preview scene settings to achieve a satisfactory screenshot. #### 3.13.8 **usdz Model Preview** （1）After uploading to Kivicube AR Quick Look, you can preview it on the webpage; click to view details\ （2）After exporting, select the file and click the space preview (macOS10.14 and above);\ （3）Open USDZ file preview through Xcode after exporting (Xcode10 and above); \ （4）After exporting, open the preview through Reality Converter; click to download \ （5）After exporting, send it to the iPhone or iPad via Airdrop, open and preview it on "File" APP; (iOS11 and above). ### 3.14 Upload Upload the current model to the Kivicube material library. We recommend uploading after setting the export format in .glb. Please note that uploading will not be supported when you set the export format in usdz. ### 3.15 Export Export the corresponding model file according to the selected export format. ### 3.16 **Conversion Method** After importing the FBX model in the AR model editor, you can choose the conversion method when exporting the USDZ model. * glTF to USDZ: the default conversion method of the AR model editor; * FBX to USDZ: Using Apple's native FBX to USDZ plug-in, if there is a problem with the model transferred from the "glTF to USDZ" method, the "FBX to USDZ" method can be used. * While using the "FBX to USDZ" method, "Position" and "Export Direction" will not be available; * While using the "FBX to USDZ" method, you need to pay attention to the new rules of "size setting": The unit of the size is "m/unit"; it means that, for example, you create a cube model with 5 units of side length in the Autodesk® Maya® then set the unit as "1m/unit" in the editor, the result of the exported model will be a 5m cube. ## 4. Using Model ### 4.1 **Use on the Kivicube platform** You can upload gltf/glb models directly on Kivicube, please refer to: ### 4.2 **Use on the Kivicube AR Quick Look** If it's just a 3D/AR experience of a single model, you can quickly upload the model in Kivicube AR Quick Look to generate an experience link: Upload address and experience case:
### 4.3 **More using scene** Click the link below to learn more about usage scenarios and use cases: --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-en.kivicube.com/manual-old/resources-specification/3d-model/kivicube-ar-model-editor.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.