Plugin Introduction

This introduction and whole documentation applies to the EasyAR Sense Unity Plugin which comes with EasyAR Sense 4.3 and above.

For versions between 3.1 and 4.2, please read EasyAR Sense Unity Plugin 4.2 Document. For older versions, you should read the documents released together with EasyAR Sense, for EasyAR Sense 1.0 or EasyAR Sense 2.0.

EasyAR Sense Unity Plugin is a very thin wrapper build above EasyAR Sense C# API to expose EasyAR Sense features into Unity. It is always a good practice to read EasyAR Sense Documentation to understand how EasyAR Sense works.

How to Use

EasyAR Sense Unity Plugin now require Unity 2019.4 or later. Support for Unity 5, Unity 2017, Unity 2018 has ended from 4.3 release.

The plugin use Unity’s package to organize itself. It is distributed as a tarball file, you can use Unity’s Package Manager window to install the plugin from a local tarball file.

../_images/image_s0_1.png

Choose the com.easyar.sense-*.tgz file in the popup dialogue.

NOTE: The tgz file cannot be deleted or moved to another place after import, so it is always a good practice to find a suitable place for the file before import. If you want to share the project with others, you can put the file inside the project and your version control system.

Versioning

EasyAR Sense Unity Plugin is designed to work with only the same version of EasyAR Sense, so the plugin uses the same version rule as EasyAR Sense.

NOTICE: EasyAR does not follow semantic versioning required by Unity package. The major difference in general, is the minor version change may introduce breaking changes, but not always.

Inside the Plugin

EasyAR Sense

Release packages of the plugin has EasyAR Sense libraries inside, so a separate EasyAR Sense package is not required when using the plugin.

The EasyAR Sense binaries inside the plugin are always the same with the EasyAR Sense in the same version. In case when you are trying to make the plugin work on a different EasyAR Sense version, you must make sure the csapi comes together with the libraries.

Scripts

The plugin is designed to be a thin Unity wrapper of EasyAR Sense, so most scripts are controllers of EasyAR Sense components in the 3D scene providing a few extensions in the Unity environment. It helps to organize and connect EasyAR Sense components.

The plugin use as much Unity features as possible, like start/stop in OnEnable/OnDisable, most EasyAR Sense features can work without writing scripts. The plugin does not wrap all functions from EasyAR Sense, all functionalities are exposed to Unity directly through C# API, which is accessible from MonoBehaviours.

The plugin also implements one typical assemble strategy for all EasyAR Sense components in ARAssembly and controls data flow from ARSession. But that is not all of EasyAR Sense. You can always rewrite these two scripts to make a customized AR workflow to use the powerful flexibility of EasyAR Sense API.

The plugin is open sourced. All public types and members are documented in the scripts in both English and Chinese. You are free to change the scripts to extend rendering pipeline support or make custom workflows.

You can use the plugin directly to create AR experience within short time. You can also reference the source code to create more custom usages of EasyAR Sense or even a Unity Plugin of your own.

Editors

The plugin provides a few editor features to help development, including

  • Script input parameters before start on the Inspector

  • Runtime control like CenterMode and HorizontalFlipMode

  • Menu entry for license key and cloud service configurations

  • Gizmos for image targets

  • Tools for image target data generation

Prefabs

Prefabs are provided to help fast AR scene build. They are not necessary if you manually arrange scripts in the scene, but it is always a good start to use prefabs when you are new to EasyAR Sense.

Prefabs are classified into two parts,

  • Primitive, is empty node with a script for one component from EasyAR Sense in most case, useful when you are building a customized AR scene.

  • Composite, is combination of primitives to hold general usages, useful for beginners who are not familiar with the assemble system.

Samples

The plugin release comes with a few samples to demonstrate features and combination of different algorithms from EasyAR Sense.

The samples are distributed within the plugin package. You can import samples into your project using Unity’s Package Manager window. See How to Use Samples for more details.

Samples has a launcher; you can start most samples from the launcher. To use the launcher, you must add the launcher scene and all other scenes referenced by the launcher into the build settings.

Samples are designed to be straight forward of showing how API can be used and how EasyAR Sense work. Feel free to build your application on top of the sample or copy sample code for your projects, but remember the sample is NOT the plugin itself, and all codes in the sample are not guaranteed to be reusable in any condition without change.

EasyAR Sense and the plugin has rich APIs. Although important features and usages are demonstrated, the samples still would not cover all API callings and feature usages. If you find the sample do not satisfy the needs of your project, try look for interfaces in the MonoBehaviours and the corresponding EasyAR Sense components first.

Start with samples, they will help you understand how EasyAR Sense and the Unity Plugin work.