|
| 1 | +# Using Unity Sentis Models from Hugging Face |
| 2 | +[Unity 3D](https://unity.com/) is one of the most popular game engines in the world. [Unity Sentis](https://unity.com/products/sentis) is the inference engine that runs on Unity 2023 or above. It is an API that allows you to easily integrate and run neural network models in your game or application making use of hardware acceleration. Because Unity can export to many different form factors including PC, mobile and consoles, it means that this is an easy way to run neural network models on many different types of hardware. |
| 3 | + |
| 4 | +## Exploring Sentis Models in the Hub |
| 5 | +You will find `unity-sentis` models by filtering at the left of the [models page](https://huggingface.co/models?library=unity-sentis). |
| 6 | + |
| 7 | +All the Sentis models in the Hub come with code and instructions to easily get you started using the model in Unity. All Sentis models under the `unity` namespace (for example, [unity/sentis-yolotinyv7](https://huggingface.co/unity/sentis-yolotinyv7)` have been validated to work, so you can be sure they will run in Unity. |
| 8 | + |
| 9 | +To get more details about using Sentis, you can read its [documentation](https://docs.unity3d.com/Packages/com.unity.sentis@latest). To get help from others using Sentis, you can ask in its [discussion forum](https://discussions.unity.com/c/ai-beta/sentis) |
| 10 | + |
| 11 | + |
| 12 | +## Types of files |
| 13 | +Each repository will contain several types of files: |
| 14 | + |
| 15 | +* ``sentis`` files: These are the main model files that contain the neural networks that run on Unity. |
| 16 | +* ``ONNX`` files: This is an alternative format you can include in addition to, or instead of, the Sentis files. It can be useful for visualization with third party tools such as [Netron](https://github.com/lutzroeder/netron). |
| 17 | +* ``cs`` file: These are C# files that contain the code to run the model on Unity. |
| 18 | +* ``info.json``: This file contains information about the files in the repository. |
| 19 | +* Data files. These are other files that are needed to run the model. They could include vocabulary files, lists of class names etc. Some typical files will have extensions ``json`` or ``txt``. |
| 20 | +* ``README``. This is the model card. It contains instructions on how to use the model and other relevant information. |
| 21 | + |
| 22 | +## Running the model |
| 23 | +Always refer to the instructions on the model card. It is expected that you have some knowledge of Unity and some basic knowledge of C#. |
| 24 | + |
| 25 | +1. Open Unity 2023 or above and create a new scene. |
| 26 | + |
| 27 | +2. Install the ``com.unity.sentis`` package from the [package manager](https://docs.unity3d.com/Manual/upm-ui-quick.html). |
| 28 | + |
| 29 | +3. Download your model files (``*.sentis``) and data files and put them in the StreamingAssets folder which is a subfolder inside the Assets folder. (If this folder does not exist you can create it). |
| 30 | + |
| 31 | +4. Place your C# file on an object in the scene such as the Main Camera. |
| 32 | + |
| 33 | +5. Refer to the model card to see if there are any other objects you need to create in the scene. |
| 34 | + |
| 35 | +In most cases, we only provide the basic implementation to get you up and running. It is up to you to find creative uses. For example, you may want to combine two or more models to do interesting things. |
| 36 | + |
| 37 | +## Sharing your own Sentis models |
| 38 | +We encourage you to share your own Sentis models on Hugging Face. These may be models you trained yourself or models you have converted to the [Sentis format](https://docs.unity3d.com/Packages/com.unity.sentis@1.3/manual/serialize-a-model.html) and have tested to run in Unity. |
| 39 | + |
| 40 | +Please provide the models in the Sentis format for each repository you upload. This provides an extra check that they will run in Unity and is also the preferred format for large models. You can also include the original ONNX versions of the model files. |
| 41 | + |
| 42 | +Provide a C# file with a minimal implementation. For example, an image processing model should have code that shows how to prepare the image for the input and construct the image from the output. Alternatively, you can link to some external sample code. This will make it easy for others to download and use the model in Unity. |
| 43 | + |
| 44 | +Provide any data files needed to run the model. For example, vocabulary files. |
| 45 | + |
| 46 | +Finally, please provide an ``info.json`` file, which lists your project's files. This helps in counting the downloads. Some examples of the contents of ``info.json`` are: |
| 47 | + |
| 48 | +``` |
| 49 | +{ |
| 50 | + code: [ “mycode.cs”], |
| 51 | + models: [ “model1.sentis”, “model2.sentis”], |
| 52 | + data: [ “vocab.txt” ] |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +Or if your code sample is external: |
| 57 | + |
| 58 | +``` |
| 59 | +{ |
| 60 | + sampleURL: [ “http://sampleunityproject”], |
| 61 | + models: [ “model1.sentis”, “model2.sentis”] |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +## Additional Information |
| 66 | +We also have some full [sample projects](https://github.com/Unity-Technologies/sentis-samples) to help you get started using Sentis. |
| 67 | + |
0 commit comments