Category Archives: Uncategorized

TriLib – Asset Loader Options

TriLib accepts various options when loading your models.
Here are the options list contained in AssetLoaderOptions class:

  • General
    • Post Process Steps: Please refer to this link.
  • Meshes
    • DontLoadMeshes: Turn on this field to disable mesh loading.
    • CombineMeshes: Turn on this field to combine multiple meshes with the same material into a single instance.
    • Scale: Use this field to override object scale.
    • RotationAngles: Use this field to override object rotation angles.
    • Use32BitsIndexFormat: Turn on this field to enable 32-bits meshes index format (for loading high vertex-count models).
    • GenerateMeshColliders: Turn on this field to enable mesh collider generation (only valid for skinned meshes).
    • ConvexMeshColliders: Turn on this field to indicate that generated mesh colliders will be convex.
  • Materials
    • DontLoadMaterials: Turn on this field to disable animations loading.
    • ApplyAlphaMaterials: Turn on this field to force alpha material scanning when you’re not using TriLib builtin image loader (STB Image Library).
    • DisableAlphaMaterials: Turn on this field to don’t use alpha materials.
    • UseCutoutMaterials: Turn on this field to use cutout alpha materials.
    • UseStandardSpecularMaterial: Use this field to use Unity Standard Specular Material, if you get wrong specular results with the Standard Specular material, uncheck this field.
    • TextureCompression: Use this field to assign the loaded textures compression level.
    • GenerateMipMaps: Turn on this field to generate loaded textures mip-maps.
  • Animations
    • DontLoadAnimations: Turn on this field to disable animations loading.
    • AutoPlayAnimations: Turn on this field to automatically play the first loaded animation (only for legacy animations).
    • AnimationWrapMode: Use this field to change default animations wrap mode.
    • EnsureQuaternionContinuity: Turn on this field to realign quaternion keys to ensure shortest interpolation paths.
    • UseLegacyAnimations: Turn on this field to use legacy Unity Animation component.
    • AnimatorController: If you don´t wish to use legacy animations, use this field to specify a Unity Animation Controller.
  • Misc
    • AddAssetUnloader: Turn on this field to add the AssetUnloader class to your loaded object, which releases resources upon the GameObject destruction.
    • DontLoadCameras: Turn on this field to disable cameras loading.
    • DontLoadLights: Turn on this field to disable cameras loading.
  • Metadata
    • DontLoadMetadata: Turn on this field to disable metadata loading.
  • Advanced
    • AdvancedConfigs: You can manually add advanced configurations to this field by creating them with the AssetAdvancedConfig.CreateConfig method. Please refer to the AssetLoaderOptions.cs source to check the advanced configs usage.

TriLib – Basic usage/Troubleshooting

Basic usage

Synchronous model loading:

using (var assetLoader = new AssetLoader()) {
    var assetLoaderOptions = AssetLoaderOptions.CreateInstance();   //Creates the AssetLoaderOptions instance.
                                                                    //AssetLoaderOptions let you specify options to load your model.
                                                                    //(Optional) You can skip this object creation and it's parameter or pass null.
    
    //You can modify assetLoaderOptions before passing it to LoadFromFile method. You can check the AssetLoaderOptions API reference at:
    //https://ricardoreis.net/trilib/manual/html/class_tri_lib_1_1_asset_loader_options.html
    
    var wrapperGameObject = gameObject;                             //Sets the game object where your model will be loaded into.
                                                                    //(Optional) You can skip this object creation and it's parameter or pass null.

    var myGameObject = assetLoader.LoadFromFile("PATH TO MY FILE.FBX", assetLoaderOptions, wrapperGameObject); //Loads the model synchronously and stores the reference in myGameObject.
}

Asynchronous model loading:

using (var assetLoaderAsync = new AssetLoaderAsync()) {
    var assetLoaderOptions = AssetLoaderOptions.CreateInstance();   //Creates the AssetLoaderOptions instance.
                                                                    //AssetLoaderOptions let you specify options to load your model.
                                                                    //(Optional) You can skip this object creation and it's parameter or pass null.
    
    //You can modify assetLoaderOptions before passing it to LoadFromFile method. You can check the AssetLoaderOptions API reference at:
    //https://ricardoreis.net/trilib/manual/html/class_tri_lib_1_1_asset_loader_options.html
    
    var wrapperGameObject = gameObject;                             //Sets the game object where your model will be loaded into.
                                                                    //(Optional) You can skip this object creation and it's parameter or pass null.

    var thread = assetLoaderAsync.LoadFromFile("PATH TO MY FILE.FBX", assetLoaderOptions, wrapperGameObject, delegate(GameObject myGameObject) {
        //Here you can get the reference to the loaded model using myGameObject.
    }); //Loads the model asynchronously and returns the reference to the created Task/Thread.
}

*Note: Async loader is meant to be used per loading request, so you should create a new AssetLoaderAssync for each model you want to load, or just re-use an AssetLoaderAsync instance when it has finished processing.

Retrieving unit scale factor from FBX models:

using (var assetLoader = new AssetLoader()) {
    var unitScaleFactor = 100f; //Sets scale factor default value.
    assetLoader.OnMetadataProcessed += delegate (AssimpMetadataType metadataType, uint metadataIndex, string metadataKey, object metadataValue) {
        //Checks if the metadata key is "UnitScaleFactor", which is the scale factor metadata used in FBX files.
        if (metadataKey == "UnitScaleFactor")
        {
            unitScaleFactor = (float)metadataValue; //Sets the scale factor value.
        }
    }; //Sets a callback to process model metadata.
    var myGameObject = assetLoader.LoadFromFile("PATH TO MY FILE.FBX"); //Loads the model synchronously and stores the reference in myGameObject.
    myGameObject.transform.localScale = Vector3.one * (unitScaleFactor / 100f); //Uses the scale factor on the loaded model.
}

Troubleshooting

-I’m getting the message “Please enable TriLib ZIP loading” when trying to load models from Zip files

In order to process Zip files contents, you  must check “Enable Zip loading” menu item on TriLib menu:

*As the menu item says, loading textures from files besides Unity default PNGs and JPEGs won’t work on iOS due to a license a DevIL Image Library license issue. We are working to fix this issue on next versions by replacing DevIL Image Library with another alternative.

TriLib – Update Troubleshooting

Hi!

If you’re having issues updating your TriLib version from Unity Editor, here are some steps to ensure you’ll update it successfully.

  1. First, close any Unity Editor instance open.
  2. Then, navigate to your project “Assets” folder and find “TriLib” main folder.
  3. Navigate to “TriLib/Plugins” folder.
  4. Delete all the “Plugins” folder content.
  5. Open your project in Unity Editor.
  6. You will be asked to restart Unity (maybe several times) as native plugins could not be found, just click “I will do it manually”.
  7. Import TriLib package from Asset Store window.
  8. You can tick the main folder (or click “All”) to include all files when importing.
  9. You will be asked to restart Unity again, but click “Ask to save changes and restart” this time.

Done!
You should have the latest TriLib update imported.

If you still have issues updating TriLib, contact us at:
contato@ricardoreis.net

TriLib – License

TriLib is governed by the Asset Store EULA;
https://unity3d.com/legal/as_terms

The following components are governed by the licenses indicated below:

A. Assimp
3-Clause BSD License
Copyright (c) 2006-2015 assimp team. All rights reserved.

B. Developer’s Image Library (DevIL)
GNU Lesser General Public License v2.1

C. Unity Toolbag
MIT License (MIT)
Copyright (c) 2017, Nick Gravelyn.

D. SharpZipLib
MIT License (MIT)
Copyright (c) 2000-2016 SharpZipLib Contributors

E. Roboto Font
Apache License
Copyright (c) 2012 Google.

F. ZLIB
ZLIB License
Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler

G. MiniZip
ZLIB License
Copyright (C) Various contributors.

TriLib – Known Issues/Limitations

  • All platforms:
    • We highly recommend you to download our test application to test your models before adquiring the package.
    • Lights will be enabled on a future release.
    • Old FBX-DOM formats are not supported.
    • Newer FBX versions (2016+) are not fully supported (work in progress).
    • Inverse kinematics are not supported.
    • Vertex animation is not supported .
  • Windows:
    • TriLib uses the Visual C++ 2017 Redistributable on Windows platform. It’s already included on the package.
    • If you prefer to use the system Visual C++ 2017 Redistributable version, you should remove all Visual C++ Redistributable files from “TriLib/Plugins/Windows/x86” and “TriLib/Plugins/Windows/x86_64” folders (keeping only “assimp.dll” and “stbimage.dll” on these folders).
    • Visual C++ 2017 Redistributable download links:
    • Visual C++ 2017 Redistributable (x86)
    • Visual C++ 2017 Redistributable (x86_64)
  • Android:
    • Android device with API 21 is required for Arm64 architectures.
    • Android device with API 14 is required for remaining architectures.
  • iOS:
    • iPhone: At least an iPhone 5s with iOS 11.2.
    • iPad: At least an iPad Air with iOS 11.2.
    • Bitcode compilation is disabled.
  • MacOS:
    • MacOS El Captain (32 bits or 64 bits) minimum required.
  • Windows Store:
    • There are no way  to load additional data files on Windows Store platform besides Ziping model files.
    • You can let user select their files calling the “Windows.Storage.Pickers.FileOpenPicker” method as seen on “FileOpenDialog.cs” inside the package.
  • WebGL (Experimental):
    • IFC and Q3BSP files are not supported at the moment.

Note: TriLib is based on Assimp (http://www.assimp.org), an open-source project. We are always updating TriLib with the latest Assimp branch, to guarantee the most recent bug-fixes. We cannot guarantee your model to partially or fully load with TriLib.

TriLib – Post Processor Options

Description of the Asset Loader post processor options:

  • Nothing: No post-processor steps will be applied, we don´t recommend enabling this item as it can decrease performance and leave model issues unfixed.
  • Everything: All post-processor steps will be applied, we don´t recommend enabling this item as it´s almost always unecessary to enable all post processor steps.
  • Calc Tangent Space: Calculates the tangents and bitangents for the imported meshes.
  • Join Identical Vertices: Identifies and joins identical vertex data sets within all imported meshes.
  • Make Left Handed: Converts all the imported data to a left-handed coordinate space (Enabled by default).
  • Remove Component: Removes some parts of the data structure (animations, materials, light sources, cameras, textures, vertex components).
  • Gen Normals: Generates normals for all faces of all meshes.
  • Gen Smooth Normals: Generates smooth normals for all vertices in the mesh.
  • Split Large Meshes: Splits large meshes into smaller sub-meshes.
  • Pre Transform Vertices: Removes the node graph and pre-transforms all vertices with the local transformation matrices of their node.
  • Limit Bone Weights: Limits the number of bones simultaneously affecting a single vertex to a maximum value.
  • Validate Data Structure: Validates the imported scene data structure. This makes sure that all indices are valid, all animations and bones are linked correctly, all material references are correct…etc (Enabled by default).
  • Improve Cache Locability: Reorders triangles for better vertex cache locality.
  • Remove Redundant Materials: Searches for redundant/unreferenced materials and removes them
  • Fix Infancing Normals: This step tries to determine which meshes have normal vectors that are facing inwards and inverts them.
  • Sort By P Type: This step splits meshes with more than one primitive type in homogeneous sub-meshes.
  • Find Degenerates: This step searches all meshes for degenerate primitives and converts them to proper lines or points.
  • Find Invalid Data: This step searches all meshes for invalid data, such as zeroed normal vectors or invalid UV coords and removes/fixes them. This is intended to get rid of some common exporter errors.
  • Gen Uv Coords: This step converts non-UV mappings (such as spherical or cylindrical mapping) to proper texture coordinate channels.
  • Transform Uv Coords: This step applies per-texture UV transformations and bakes them into stand-alone vtexture coordinate channels.
  • Find Instances: This step searches for duplicate meshes and replaces them with references to the first mesh (Enabled by default).
  • Optmize Mesh: A postprocessing step to reduce the number of meshes (Enabled by default).
  • Optimize Graph: A postprocessing step to optimize the scene hierarchy.
  • Flip UVs: This step flips all UV coordinates along the y-axis and adjusts material settings and bitangents accordingly.
  • Flip Winding Order: This step adjusts the output face winding order to be CW (Enabled by default).
  • Split By Bone Count: This step splits meshes with many bones into sub-meshes so that each sub-mesh has fewer or as many bones as a given limit.
  • Debone: This step removes bones losslessly or according to some threshold.

TriLib – Tutorial : Enabling DevIL image library

TriLib includes DevIL image library.

What is DevIL image library?

Developer’s Image Library (DevIL) is a programmer’s library to develop applications with very powerful image loading capabilities, yet is easy for a developer to learn and use. Ultimate control of images is left to the developer, so unnecessary conversions, etc. are not performed. DevIL utilizes a simple, yet powerful, syntax. DevIL can load, save, convert, manipulate, filter and display a wide variety of image formats.

Currently, DevIL can load .bmp, .cut, .dds, .doom, .exr, .hdr, .gif, .ico, .jp2, .jpg,.lbm, .mdl, .mng, .pal, .pbm, .pcd, .pcx, .pgm, .pic, .png, .ppm, .psd, .psp, .raw, .sgi, .tga and .tif files.
Formats supported for saving include .bmp, .dds, .h, .jpg, .pal, .pbm, .pcx, .pgm, .png, .ppm, .raw, .sgi, .tga and .tif.

Unity only allows you to load .PNG and .JPG external image formats.
Devil allows TriLib to load all above image formats.

To enable DevIL on your project, first, ensure you have checked these files when importing your TriLib package:

A menu item called “TriLib” will appear on your Unity menu bar.

To enable DevIL, check the “Enable DevIL Image Library”

That´s it.
Now your TriLib models textures will be loaded using DevIL image library instead Unity internal image loader.

DevIL is not available for iOS target due to license requirements incompatibilities.