How-to: Unity Plugin Quickstart
To publish 3D content to your account it is necessary to make use of the Unity PlugIn for Unity 5.6.5f1. The PlugIn is free and it can be connected directly to your account and you are able to publish your 3D models directly to the CMS.
Download the PlugIn
You can download the latest version of PlugIn here. Download and open the Zip file. If you do not have downloaded and installed Unity 5.6.5f1 already please do so. You can download the correct Unity version here in the Unity 5.x tab. While installing Unity you should also install “iOS Build Support”. More on that in the next step.
It is necessary for the PlugIn to run properly to install iOS build support. Open the “File” menu and click on Buildsettings “Build Settings…” Select iOS in the Platform window. If you have iOS support already installed everything is fine and the PlugIn is able to work properly if not click on “Open Download Page” and install the file that was downloaded.
Now you can copy and paste the “Vuframe” folder from the Zip-file into your Asset folder by using the Explorer or Finder, depending if you are on Windows or MacOS. Or you can simply drag and drop the folder into the Project window in Unity. Note: If you are working within an existing Unity project you always should start of in a copy of your project to prevent data loss. Now, after importing the new Files, Unity will ask you to update your Project Settings, confirm and the Project Wizard will set up your project so the PlugIn will work as expected.
Connect the Unity PlugIn with your Vuframe Account
If you want to upload your 3D scenes directly to the CMS you need to connect the PlugIn to your Vuframe account. Click on “Window” in the top menu, search for the entry “Vuframe” and choose “Publishing” after the sub-menu unfolds. A new window will appear that will show you all your projects, SmartViews and folders after you have logged in. Click on Login and a browser window will open automatically. If you are already logged in on this browser the CMS will show you the following dialog.
If not the Vuframe CMS will ask you to log in first. When you are logged click on “Grant Access” and on the next page the CMS will present you an “Authentication Token”. Copy that token (select it and press the right mouse button and choose “Copy” or use cmd/ctrl + c) and switch back to Unity. In the Publishing window there is now a Textfield called “Auth Token” paste you token into that field (with right-click “Paste” or cmd/ctrl + v). Click on “Save Auth Token” to continue. You should see your Teams and Projects your account is connected to.
Import your Objects
Unity has a extensive list of supported 3D file formats, such as .fbx, .dae (Collada), .obj, and many more. The full list of compatible file formats is available here in the Unity documentation. On top of this Unity supports the import of most major proprietary file formats and converts those formats automatically into a compatible file format. Those 3D applications are listed in the Unity documentation as well.
To import your 3D files, drag and drop the files and supporting assets, such as textures, from your file browser into the “Project” tab in Unity. The import will start automatically and after the processing is done your models are available in your “Assets”.
Note 1: The import of 3D model files can take a while, depending on there complexity.
Note 2: It is good practice to create a folder in the “Assets” folder depending on single products or projects to keep your Unity project nice and tidy. A folder should contain all prefabs, textures, materials and 3D files of the product or project.
When selecting the 3D file in your asset you can see the import options in the “inspector” tab. It can be necessary to tweak the “Scale Factor” of the 3D file to have life size AR work properly. One Unity unit is one meter in real life / AR projection (more on that later).
Create a Prefab
Note: Unity stores all data, describing an object, not as you might be used to from your 3D application in a scene file but in a Prefab. A Prefab contains information as material assignments, object hierarchy, added components, Transform data and much more. It is vital for the Unity PlugIn to work correctly to store your data in that way.
After the import of your 3d model is done you can drag and drop the 3D file from your Assets folder into an empty scene, in the “Hierarchy” tab.
Drag and drop your object back to the “Assets” folder or the folder you want to store your data in and Unity creates a Prefab out of the object. If you do changes to your model, such as material assignments, changes in hierarchy and so on you need to press the “Apply” button in the Inspector tab to safe your changes.
Add and setup the Vuframe Scene Component
There are two ways to add a “Vuframe Scene” Component. You can add a “Empty Game Object” that has the Scene component already attached or you select the Object that you already created a prefab of and click on the “Add Component” button in the Inspector tab. The Vuframe Scene Component must be applied to the parent object of your prefab. All objects of that child object are exported to the CMS later on.
Select the object as shown in the screenshot above, go to the “Inspector” tab and click on the “Add Component” button. I little dialog box will pop up and you can use the text search to find the Scene Component more quickly. Type in Scene as shown and hit the Enter key or double-click on the item named “Scene”.
The Vuframe Scene or short “VF Scene” has been added to the object. To save the changes to your Prefab click on the “Apply” button, shown in the upper right part of the screenshot.
A different approach, if you don’t start with an already created Prefab, is to use the top menu and create the Vuframe Scene as an empty game object. Open the menu item “GameObject” and click onto “Create Vuframe Scene”. This will create a new object in your Unity scene and you need to create a Prefab from this object as well and as mentioned above. Again if you make any changes in one of the Components setting or the hierarchy in the prefab, press the Apply button to safe your changes.
Vuframe Scene Settings
The Scene component is somewhat of the heart of our Unity PlugIn. Most of the Basic Settings are in this component and even the Publishing to the CMS is managed within this component. The VF Scene will also add a second component automatically that is called “VF Render Settings” which manages aspects of your scene like ambient light when the scene is displayed on your device.
Note: You can and should always check the settings you have made by starting the Play mode of Unity to verify the scene will look as intended. Play with the various parameters to get a hold of what each of them does and how it will affect your scene.
For the Quickstart Guide we will concentrate on the most basic settings and cover the more advanced options in later guides and articles in a more detailed manner.
Touch Camera settings
The Touch Camera is usually the camera your scene is starting in when it is loaded on a device. It allows you to navigate in the scene by using rotation of the camera around the model, zooming in and panning, using your fingers. Lets hop through the most important settings top to bottom.
- Bounds: Are calculated automatically when the VF Scene is added to a prefab that already contains 3D objects as childs. If you want to add new 3D objects later you can restart this calculation by unfolding the “Dimensions” menu and click on the “Update Bounds” button.
- Field of View: Sets the Field of View of your camera as an angle in degree.
- Center: Sets the center of rotation of the camera.
- Look at: Sets an offset of the point the camera will look at from the “Center” in X, Y and Z direction.
- Distance: Sets the minimum, starting and maximum distance between the “Center” and the camera.
- Pitch: Sets the minimum, starting and maximum angle the camera rotates up and down around the “Center”.
- Yaw: Sets the starting rotation value around the objects in degree. Choose a flattering angle to show your object from its best side.
- Limits: If necessary you can set limits to the “Yaw” value the user of the SmartView is able to rotate around the object.
- Disable Interaction: If necessary you can disable the camera interaction (rotate, move up/down and zoom in and out). You should really check before using this option, a disabled interaction usually gives a bad User Experience.
- Enable Fly-In: Enables or disables a camera animation on scene start.
- Enable Autospin: Enables or disables the camera rotation around the object in the scene automatically. The speed of the rotation and the automatic time of resume after the user has interacted with the model can be set with the two text fields.
- Navigation Mode: Panning enables the camera to be moved around in a certain area. You can enable 3 different modes of panning. single and dual axis for vertical panning and dual axis panning in the horizontal plane.
This settings allow you to set up the default scale and rotation of your model in onTable AR. You can scale the model to fit the size on an image-ar-marker.
Preview, Publishing & Settings
- Publish to: If you already connected the Unity PlugIn to your CMS account you can choose the target project, folder or SmartView the scene gets published to.
- Name: Set the name that is displayed in the CMS later when the scene is published.
- GUID: This unique ID identifies the scene in the CMS, as long as the ID and Publishing stays unchanged the CMS will recognize the new upload as an update.
There are two different kinds of messages that are displayed as Validation Results, “Warnings” and “Errors”. Warnings are recommendations and do not disable the publishing. If the validation displays an Error the Scene component prevents the user from publishing the scene from being exported and published.
After you have fixed the errors, displayed in the validation results apply you changes to the Prefab. To select the object in your project click on the “Go to Prefab to Publish” button on the bottom of the VF Scene Component or the “Select” button on the top of the Inspector tab.
Centering and scaling Objects
It can cause problems if your objects are not centered around the coordinate origin of the scene (x, y, z = 0) or are not scaled correctly. For an example, the placement in AR completely wrong if the objects are not roughly centered, or the objects are to small or to big in Life-Size AR. If the parent object of your scene is not centered around the VF Scene component will prevent you from publishing to the CMS.
To performing an automatic centering of the objects around the origin we have added a little script that will help you. Select the Prefab with your content in the Hierarchy tab open the “Dimensions” menu and click on Update Bounds.
If there are Issues with the centering of your scene, there are warnings displayed inside the “Scene” tab. Note that there are two different kind of Warnings that can be displayed here. If your scene is not centered in the X and Z dimension and if your scene extends below Y = 0. From time to time it can be useful to have your scene extend below 0, so you can ignore the second warning in the screenshot below if this was on purpose.
Click on either one or both “Fix now” buttons and the issues will be fixed automatically.
Since the the PlugIn cannot know what real world scale your objects have the scaling has to be done by hand. You always should check the object scale after importing the 3D meshes to Unity, using a standard cube (GameObjects / 3D Object / Cube) as a reference. However it happens that it is necessary to scale objects and groups after you set up your scene and Prefab.
Select your Prefab in the “Hierarchy” window and select “GameObject” on the top menu and click on “Create Empty Child”. Select all the mesh objects in from your prefab and drag and drop them so they become Child objects of the new Empty Game Object. Do not scale the parent object of the prefab that contains the VF Scene component but the new object with the mesh objects as children, otherwise the Validator will prevent you from publishing your scene.
As described above use the standard cube as a reference, the cube is 1 x 1 x 1 Unity unit which equals 1 x 1 x 1 meter in Life-Size. If you have smaller or bigger objects use a multiplicator like 0.1 or 10 or enter the exact measurements in meters of your objects as scale reference in the scale values of the cube.
Setup basic lighting
You are not able to publish your scene to the CMS without adding at least a very simple light setup, the scene component will prevent you from doing so without activating the option “Skip Lighting” in the “Lighting & Lightmaps” group of the VF Scene component.
You can achieve a very basic lighting by adding a Directional Light from the top menu. Navigate to GameObjects / Light and click on “Directional Light” This will create a simple infinit light source that lights your object from a set angle. You can rotate the light source so it suits your object. Drag and drop the Directional Light source so it is a child object of your prefab, select the object with the VF Scene component and click the Apply button to save your changes.
Publish to the CMS
After you have setup the Prefab correctly and have no error message that are preventing your scene to be published to the CMS. The last step is to select the Prefab in the “Project” tab. You can do so by selecting the object with the VF Scene component in the Unity scene you are working in and click on select or you scroll down to the bottom of the VF Scene component and click on the green “Go to Prefab to Publish” button.
Either way you will be presented again with the Publishing settings alike the ones you found in the last settings group of the scene component. If everything is set up correctly the “Export & Publish” button is green. Otherwise refresh the scene validation by click the “Validate” button on the the bottom of the component and inspect if there are still issues in the “Validation Results”.
After you clicked “Export only” or “Export & Publish” there will be a dialog box poping up, press Ok to confirm the Export and Upload. If there are some minor warning is the scene validation, you will presented with a second dialog asking if you want to despite of the warnings. Click Yes if you want to continue or cancel if you want to do changes to get rid of the warnings before publishing.
If you clicked on “Export only” the scene will be exported only locally to the “Deployed Scenes” folder on the topmost level of your Unity Project (the one above the Assets folder”. You can upload those exported .vf3d files to the CMS by hand with your browser later (e.g. if you are working offline).
If you chose to “Export & Publish” the upload to the CMS will start automatically and after the Upload is done one last dialog box will pop up pointing you directly to the project, folder or SmartView you uploaded your scene, if you click on “View Online”.
Done! You can now start to make your settings in the CMS.