Area Learning

Area Learning区域学习

How it works它是如何工作的

With Motion Tracking alone, the device tracks its movement and orientation through 3D space and tells you where it is and which way it’s facing, but it retains no memory of what it sees. Area Learning gives the device the ability to see and remember the key visual features of a physical space—the edges, corners, other unique features—so it can recognize that area again later. To do this, it stores a mathematical description of the visual features it has identified inside a searchable index on the device. This allows the device to quickly match what it currently sees against what it has seen before without any cloud services.

如果只有Motion Tracking运动追踪，设备可以在3D空间中穿行时追踪它的运动和方向，并告诉你它所在的位置和它面向的是哪条路。但是它仍然对它所看到的无法保存记忆。区域学习赋予设备看的能力，并记住一个物理空间的关键视觉特征——边缘、角和其他特殊的特征，所以它能在以后识别出那个区域。要做到这一点，它存储了它设备搜索索引内部识别的视觉特征的一个数学描述。这允许设备得以快速匹配它当前所看到的和它之前所看到的，而不需要任何云服务。

When a Tango device has learned an area, there are two key things it can do to improve upon the information provided by Motion Tracking alone:

当一个Tango设备已经学了一个区域，有两个它可做的关键的东西用以提高Motion Tracking所提供的信息：

1. Improve the accuracy of the trajectory by performing "drift corrections." 通过执行“漂移校正”提高轨迹精度。

2. Orient and position itself within a previously learned area by performing "localization." 通过执行“本地化”在一个之前学习过的区域定向和定位。

Improving the trajectory提高轨迹

As mentioned on the Motion Tracking Overview page, motion estimates become less accurate over time. The device corrects for some errors by orienting itself to gravity, but errors in other aspects of its pose cannot be detected through Motion Tracking alone.

正如运动追踪页面中提到的，运动估计随着时间推移将变得越来越不精确。虽然设备通过对重力的定向（定向重力）来纠正某些误差，但仅通过运动跟踪无法检测到其姿态的其它方面的误差。

With Area Learning turned on, the Tango device remembers the visual features of the area it has visited and uses them to correct errors in its understanding of its position, orientation, and movement. This memory allows the system to perform drift corrections (also called loop closures). When the device sees a place it knows it has seen earlier in your session, it realizes it has traveled in a loop and adjusts its path to be more consistent with its previous observations. These corrections can be used to adjust the device's position and trajectory within your application.

打开区域学习功能，Tango设备可以记得它访问过的区域的视觉特征，并用它们来校正它在位置、方向和运动理解上的误差。这份记忆将允许系统执行漂移校正（也称为回环检测）。当设备看到一个它之前看到过的地方时，它会认识到它已经进行了一个回环，从而调整其路径，使其与先前的观察结果更为一致。这些校正可以用于调整应用中设备的位置和轨迹。

The illustration below shows an example of drift correction. As you begin walking through an area, there are actually two different trajectories occurring simultaneously—the path you are walking (the "real trajectory") and the path the device estimates that you are walking (the "estimated trajectory"). The green line is the real trajectory that the device is traveling; the red line shows how, over time, the estimated trajectory has drifted away from the real trajectory. When the device returns to the origin and realizes it has seen the origin before, it corrects the drift errors and adjusts the estimated trajectory to better match the real trajectory.

下面的插图展示了一个漂移校正的例子。当你开始在一片区域走路时，实际上有两个不同的轨迹同时发生——在你行走的路径上（“真实轨迹”）和设备估计你行走的路径（“估计—迹”）。绿线是设备运动的真实轨迹；红线显示了预测轨迹如何随着时间漂移真实轨迹的。当设备回到原点并且意识到它看到了之前的原点，那么它会校正漂移误差并调整预测轨迹以匹配真实轨迹。

Without drift correction, a game or application using a virtual 3D space aligned with the real world may encounter inaccuracies in Motion Tracking after extended use. For example, if a door in a game world corresponds with a door frame in the real world, drift errors can cause the game door to appear in the middle of the real-world wall instead of in the door frame.

没有漂移校正，使用与真实世界匹配的虚拟3D空间游戏或应用可能在扩展使用中运动追踪时会遇到不准确。例如，如果一个游戏世界的门和现实世界中的门框相对应，而漂移误差会导致游戏门出现在现实世界的墙中间，而不是在门框中。

Area descriptions and localization空间描述和本地化

After you have walked through an area with Area Learning turned on, you can save what the device has seen in an Area Description File (ADF). Learning an area and loading it as an ADF has a number of advantages; for example, you can use it to intentionally align the device's coordinate frame with a pre-existing coordinate frame so that content in a game or app always appears in the same physical location.

当你打开区域学习之后走过一个区域，你可以将设备看到的保存到一个区域描述文件（ADF）。学习一个区域并将它作为一个ADF加载有一些优点。例如，你可以用它来有意将设备的坐标框架与之前存在的坐标框架对齐，从而游戏或者app中的内容总是出现在同样的物理位置处。

There are two ways to create an ADF. You can use any application that can save area descriptions, including Tango Area Learning sample projects (see more information about sample projects for C, Java, or Unity). Your second choice is to use the Tango APIs to handle the learning, saving, and loading all within your application.

有两种创建ADF文件的方式。你可以使用任何能保存区域描述的应用，包括Tango区域学习的样例项目（看更多样例项目信息：有C，Java或者Unity）。

If you want to create a consistent experience within the same mapped space, such as having virtual objects appear in the same location as the last time the user visited an area, you must perform localization. This is a two-step process:

如果你想在同样的地图空间中创建一个一致体验，比如让虚拟物体出现在用户上一次访问的某个区域同样的位置，你必须执行定位操作。这是一个两步的过程：

1. bLoad a previously saved ADF.加载一个之前保存的ADF。

2. Move the device into the area that was saved in the ADF.将设备移动到曾保存的ADF区域。

When the device "sees" that it is in the area covered by the ADF, it instantly knows where it is relative to the origin in the file (that is, the point where original learning started in the saved area)—this is localization. Without localizing to an area description, a device's starting point is lost every time you end the session.

当设备“看到”它是在由ADF覆盖的区域中时，它立即知道它相对于文件中的原点的位置（原点是指保存的原始学习文件开始的地方）——这就是指本地化。如果不对区域描述进行本地化，那么每当你结束一个进程时设备的起始点将丢失。

Usability tips使用提示

• Tango devices depend on the visual diversity of the area to localize. If you are in an area with many identical rooms or in a completely empty room with blank walls, it is difficult to localize.Tango设备利用区域的视觉复杂性来定位。如果你在一个有很多相似房间或者一个有很多白墙的全空房间，那将很难定位。

• An environment can look quite different from different angles and positions, and can change over time (furniture can be moved around, lighting will be different depending on the time of day). Localization is more likely to succeed if the conditions at the time you localize are similar to the conditions that existed when the ADF was created.环境从不同的角度和位置看起来非常不同，并且可以随着时间改变（家具是可能移动的，灯光会因时间不同而不同）。如果你定位时的条件跟你创建ADF时的条件相似，那么定位更有可能成功。

• Because environments can and do change, you might create multiple ADFs for a single physical location under different conditions. This gives your users the option to select a file that most closely matches their current conditions. You could also append multiple sessions onto the same ADF to capture visual descriptions of the environment from every position and angle and under every variation of lighting or environmental change.因为环境可能而且确实会改变，你可能对不同条件下的同一个物理位置创建多个ADF文件。这给你的用户选择一个最可能符合他们当前条件的文件的选项。你还可以将多个线程附加到同样的ADF文件中，以从每个位置、角度和光照以及环境变化下捕捉该环境的视觉描述。

Our UX Best Practices page has additional tips on creating ADFs and using Area Learning.

我们的UX最佳实践页面有关于创建ADF文件和使用区域学习的额外提示。

Common use cases一般使用例子

Multi-player experiences: Two or more users in the same physical location share an ADF through a cloud service and then localize to the same coordinate frame. This allows multiple people to interact in the same physical space where all of their relative positions are known. The Tango APIs do not natively support data sharing in the cloud, but you can implement this through Google Cloud Storage and the Google Play Games API.

多玩家经验：两个或多个用户通过云服务在同一个物理位置共享同一个ADF。然后定位到相同的坐标框架。这允许多个用户在同一个物理空间交互，其中他们的相对位置是已知的。Tango API本身不支持云端数据共享，但是你可以通过Google云存储和Google Play Games API实现这一点。

Location-aware shopping or other activities: A retail store manager makes an ADF of their store and then makes the ADF publicly available. Customers load the ADF, localize, and then use the device to navigate directly to products they are interested in.

位置感知的购物或其他活动：零售店经理制作他们商店的ADF文件，然后让这个ADF公开可用。用户加载该ADF，定位，然后使用该设备直接导航到自己的感兴趣的商品。

Important: While saved area descriptions do not directly record images or video, the data can be reconstructed into viewable images. Therefore, to protect the user's privacy, you must ask for permission before saving any of their learned areas to the cloud or sharing areas between users just as you would with any other images or video.

重要：当保存的区域描述不直接记录图片或视频，但是数据可以重建为可视图像。因此，为了保护用户的隐私，你必须在保存任何他们的学习区域到点云或者在用户之间分享之前请求许可，就像你拍照或录像之前需要取得许可一样。

Area Learning and using area descriptions are powerful features, and we’re excited to see how developers use them to offer new user experiences.

区域学习和使用区域描述是很强大的功能，我们很高兴能看到开发人员使用它们来提供新的用户体验。

Using learning mode and loaded ADFs使用学习模式和加载ADF

The behavior of some aspects of the Tango APIs will vary depending on your settings for learning mode or whether you loaded an ADF.

Tango API的某些方面的行为将会根据你的学习模式的设置以及是否加载ADF而发生改变。

In the table below, the two left columns specify whether you have learning mode on and whether you have loaded a previously stored ADF. You may or may not be able to save an ADF depending on the status of those two things. For example, if you don't have learning mode on, you cannot save an ADF. If you have learning mode on and have loaded an ADF, you can only save again after you have localized against the loaded ADF.

在下面的表格中，左边两列指定了你是否打开学习模式以及你是否加载了一个之前存储的ADF。根据这两种情况的状态你可能会或者可能不会保存ADF。例如，如果你不打开学习模式，那么你将不能保存ADF。如果你打开学习模式并且加载了一个ADF，那么你在在ADF定位之后只能再次保存。

Also, if you aren't in learning mode and don't have an ADF loaded, you cannot get pose data using the TANGO_COORDINATE_FRAME_AREA_DESCRIPTION frame of reference. If you have an ADF loaded, you can get pose data from that frame of reference after the device localizes to the loaded ADF.

而且，如果你不在学习模式而且没有加载一个ADF文件的话，你将不能使用TANGO_COORDINATE_FRAME_AREA_DESCRIPTION参考框架得到位姿数据。如果你已经加载了一个ADF，那么你可以在设备定位到了加载的ADF之后获取参考框架的姿态数据。

Is learning mode on?打开学习模式？	Is there an ADF loaded?有没有加载ADF？	Is pose data available for this frame of reference pair?是否参考框架对的姿态数据可用？			Can you save an ADF?能否保存ADF？
		Start of service to device开始服务到设备	Area description to device区域描述到设备	Area description to start of service区域描述到服务开始
False否	False否	Available at start开始可用	Not available不可用	Not available不可用	Cannot save area description.不能保存区域描述
True是	False否	Available at start开始可用	Available at start*开始可用	Available at start*开始可用	Current area description saved with new UUID.当前区域描述保存在新的UUID
False否	True是	Available at start开始可用	Available after localized定位后可用	Available after localized定位后可用	Cannot save area description.不能保存区域描述
True是	True是	Available at start开始可用	Available after localized定位后可用	Available after localized定位后可用	You cannot save the area description until after you have localized against the loaded ADF. 你不能保存区域描述直到你已经在加载的ADF中定位了之后 When you save, it will create a new file with a new UUID.当你保存时，它将会以新的UUID保存。

*If tracking is lost, these frame of reference pairs will no longer be available. After service reset, the session functions as if learning mode is True and an ADF was loaded, where the area descriptions are those that were learned up to the loss of tracking. To continue using the area description frame of reference, you must localize against what you learned before the loss of tracking. You must also localize to include what you learned before tracking was lost when saving an ADF.

*如果追踪丢失了，这些参考框架对将不再可用。在服务重置后，会话运行的将如同学习模式是真而且ADF加载一样，其中区域描述是追踪丢失后学习的。要继续使用区域描述参考框架，你必须在追踪丢失之前在你学习的中定位。当保存ADF时，你还必须定位，以便在追踪丢失之前包含你学习的东西。

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

上次更新日期：一月 5, 2017

• The Tango Community

Java API Area Learning TutorialJava API的区域学习教程

Configuration配置信息

There are two configuration options that are relevant to area learning.

有两个跟区域学习相关的配置选项。

Loading area descriptions加载区域描述

To load an area description file, your TangoConfig must have KEY_STRING_AREADESCRIPTION set to the UUID of the ADF you wish to load. When the TangoService starts, it loads this area description.要加载一个区域描述文件，你的TangoConfig必须将KEY_STRING_AREADESCRIPTION设置为你希望加载的ADF的UUID。当TangoService启动时，它将加载该区域描述。

 

try {
    mConfig.putString(TangoConfig.KEY_STRING_AREADESCRIPTION, uuid);
} catch (TangoErrorException e) {
    // handle exception
}

Here is an example of how you could load the latest saved area description file. It retrieves a list of all area description files and takes the last one in the list, which would be the most recent:

这里是一个关于如何加载最近保存的区域描述文件的例子。它检索所有区域描述文件的列表，然后抽出最新的一个：

 

ArrayList<String> fullUUIDList = new ArrayList<String>();
// Returns a list of ADFs with their UUIDs
fullUUIDList = mTango.listAreaDescriptions();

// Load the latest ADF if ADFs are found.
if (fullUUIDList.size() > 0) {
     mConfig.putString(TangoConfig.KEY_STRING_AREADESCRIPTION,
                       fullUUIDList.get(fullUUIDList.size() - 1));
}

Learning mode学习模式

In order to use area learning, your TangoConfig must have KEY_BOOLEAN_LEARNINGMODE set to true. In the default TangoConfig, KEY_BOOLEAN_LEARNINGMODE is set to false.

要想使用区域学习，你的TangoConfig必须将KEY_BOOLEAN_LEARNINGMODE设置为真。在默认的TangoConfig，KEY_BOOLEAN_LEARNINGMODE是设为否。

 

try {
    TangoConfig mConfig = mTango.getConfig(TangoConfig.CONFIG_TYPE_CURRENT);
    mConfig.putBoolean(TangoConfig.KEY_BOOLEAN_LEARNINGMODE, true);
} catch (TangoErrorException e) {
    // handle exception
}

You can save an ADF by calling Tango.saveAreaDescription(). This call can be long-running, so don't call it on the UI thread..

你可以通过调用Tango.saveAreaDescription()保存一个ADF文件。这个调用可能是很长时间的，所以不要在UI线程中调用它。

Learning mode with a loaded area description带有区域描述的学习模式

If both options are used, an area description of the current session will be built. If localization occurs against the loaded ADF and Tango.saveAreaDescription() is called, a new ADF will be saved containing the combination of both.

如果两个选项都使用的话，则将构建当前会话的区域描述。如果本地化发生在加载的ADF，并且Tango.saveAreaDescription()调用了，那么一个包含两者的新的ADF将会保存。

Note: You cannot save an area description in this way until you have localized against the loaded ADF. See Area Learning Mode and Loaded Area Description Files for more information.

注意：你不能以这种方式保存区域描述，直到你在加载的ADF中进行了本地化为止。查看区域学习模式和加载的区域描述文件以获取更多信息。

Motion tracking with area learning带有区域学习的运动追踪

In general, using motion tracking with area learning is very similar to basic motion tracking. You need to define the coordinate pairs you are interested in, then use either callbacks or polling to get data.

一般来说，使用区域学习的运动跟踪与基本运动跟踪非常相似。你需要定义你感兴趣的坐标对，然后使用回调或者直接查询来获取数据。

There are two coordinate frame pairs for area learning. The TangoCoordinateFramePair

with baseFrame == TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION and targetFrame == TangoPoseData.COORDINATE_FRAME_DEVICE gets you the pose of the device from the area description's origin, including drift corrections. If an ADF was loaded, pose data is only available after you have localized to the ADF and the origin will be the same as the ADF. If learning mode enabled without loading an ADF, pose data will be available immediately after initialization and the origin will be the same as the start of service.

对区域学习来说有两种坐标框架对。带有baseFrame==TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION和targetFrame==TangoPoseData.COORDINATE_FRAME_DEVICE的Tango坐标框架对(TangoCoordinateFramePair)会带给你基于区域描述原点的当前设备坐标位姿，包含了漂移校正。如果ADF文件已加载，那么姿态数据只有在你已经定位到ADF之后可用，并且原点和ADF相同。如果没有加载ADF而且打开了学习模式，那么姿态数据将会在初始化之后很快就可用，并且原点跟开始服务时的相同。

The frame pair with baseFrame == TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION and targetFrame == TangoPoseData.COORDINATE_FRAME_START_OF_SERVICE provides the offset between the area description and start of service at the requested time. This pair updates only when a localization occurs.

而baseFrame==TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION和targetFrame==TangoPoseData.COORDINATE_FRAME_START_OF_SERVICE框架对提供了区域描述与开始服务之间的偏移。这对只有在本地化的时候才更新。

Applications should use TangoPoseData.COORDINATE_FRAME_DEVICE with respect toTangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION for tracking a device's motion, and use TangoPoseData.COORDINATE_FRAME_START_OF_SERVICE with respect to TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION only as a localization signal.

应用程序应该使用TangoPoseData.COORDINATE_FRAME_DEVICE和TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION来追踪设备的运动，然后使用TangoPoseData.COORDINATE_FRAME_START_OF_SERVICE和TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION作为本地化信号。

 

@Override
public void onPoseAvailable(TangoPoseData pose) {

if (pose.baseFrame == TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION
        && pose.targetFrame == TangoPoseData.COORDINATE_FRAME_DEVICE) {
    // Process new ADF to device pose data.
}
else if (pose.baseFrame == TangoPoseData.COORDINATE_FRAME_AREA_DESCRIPTION
        && pose.targetFrame == TangoPoseData.COORDINATE_FRAME_START_OF_SERVICE) {
    // Process new localization.
}

Working with ADFs带ADF的工作

Using metadata

ADFs have metadata you can use, so you don't have to work with UUID alone. The metadata consists of key-value pairs; for a list of supported keys see the constant values for TangoAreaDescriptionMetaData.

ADF有元数据可以使用，所以你不需要只使用UUID。元数据包括值键对；对于支持的值键对，请看TangoAreaDescriptionMetaData的constant values(常数值)。

Get the name field for the ADF identified by uuid:

得到uuid识别的ADF的名称字段：

 

public String getName(String uuid) {

    TangoAreaDescriptionMetaData metadata = new TangoAreaDescriptionMetaData();
    metadata = mTango.loadAreaDescriptionMetaData(uuid); //通过uuid获取区域描述元数据
    byte[] nameBytes = metadata.get(TangoAreaDescriptionMetaData.KEY_NAME); //获取区域描述元数据的KEY_NAME
    if (nameBytes != null) {
        String name = new String(nameBytes);
        return name;
    } // Do something if null
}

Set the name field to name, for the ADF identified by uuid:

将uuid识别的ADF设置名称字段为name：

 

public void setName(String name, String uuid) {

    TangoAreaDescriptionMetaData metadata = new TangoAreaDescriptionMetaData();
    metadata = mTango.loadAreaDescriptionMetaData(uuid);
    metadata.set(TangoAreaDescriptionMetaData.KEY_NAME, name.getBytes());
    mTango.saveAreaDescriptionMetadata(uuid, metadata);
}

Listing all the UUIDs of currently accessible ADFs:

列出当前可获取的ADF的所有UUID：

 

ArrayList<String> mFullUUIDList;
try {
    mFullUUIDList = mTango.listAreaDescriptions();
} catch(TangoErrorException e) {
    // handle the errors
}
if (mFullUUIDList.size() == 0) {
    // handle the fact that there's no ADFs stored
}

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

上次更新日期：八月 25, 2016

• The Tango Community

How do I share a single ADF localization file to multiple google tango tablets?

How would I easily share a single ADF localization file to multiple google tango tablets? Can it be done all at once for example?

android google-project-tango

shareimprove this question

edited Jan 28 '16 at 16:54

asked Jan 28 '16 at 16:26 Veronica So 61

What you mean by sharing the ADF to multiple devices? you mean through the cloud or just want to use Bluetooth or other methods in real time? one classical offline way is exporting the ADF to sdcard. and pushing to other devices. – Lu sandy Jan 28 '16 at 23:38

The situation is that we have several tangos and just want to do area learning (make the ADF localization file) for the room once. We are developing on a MAC and not sure how to easily browse for the ADF file and copy it over to other Tango devices. Are there any existing tango utility apps that I can share the same ADF file with all devices? Can it be loaded onto the Tango via something like gmail or bluetooth connection? – Veronica So Jan 28 '16 at 23:57

add a comment

1 Answer

activeoldestvotes

up vote1down vote

Currently, there is not such utility apps handle what your want. but all the component are there: Import/Export ADF function in AreaLearning sample code and Bluetooth on android.

you can write them together. Basically the workflow is: Record ADF. save it. Export ADF to sdcard. Bluetooth connect other devices. share the ADF to them. on received devices, import the received ADF.

Classical way for doing Import/Export, can be done through example in Java,C and Unity. since you used Unity. Let's use Unity as a example.

Following the step in developer side: https://developers.google.com/project-tango/apis/unity/unity-codelab-area-learning

and function: https://developers.google.com/project-tango/apis/unity/reference/class/tango/area-description?hl=pt-BR

Build and run the Unity Examples. in Unity Examples.

1. Export ADF

Start "AreaDescriptionManagment";granted the "ADF permission". It will list all the ADF in the Tango API workspace.

Select the ADF you want to export. It will bring you to the new popup.

Click "Export". Grant the Export Permission.It will show where you want to export.default is "/sdcard/"; click Done. it will export ADF to "/sdcard/"

Use adb shell ls /sdcard/ you will find the UUID of the ADF.

like de305d54-75b4-431b-adb2-eb6b9e546014

using adb pull /sdcard/de305d54-75b4-431b-adb2-eb6b9e546014 pull the ADF to your linux box or windows folder using adb push UUUID /sdcard/ push the ADF back to your device.

1. Import ADF

same step to "AreaDescriptionManagment".

Click "Import Area Description" input add uuid to the path.

like: /sdcard/de305d54-75b4-431b-adb2-eb6b9e546014 grant the import permission.

The ADF should be in new device's Tango API workspace.

shareimprove this answer

edited Jan 31 '16 at 1:09

answered Jan 29 '16 at 1:53 Lu sandy 52638

I'm not sure what location on the tango to import the ADF file to. is it a hidden directory? again, i'm new to android and very new to the tango. From the sample unity code for arealearning, as i understand it, there is a very specific place where all the ADF files are read from in order for unity to use it. is this correct? or is there a way to have the unity app successfully read an ADF file located anywhere on the tango device (for example, downloads folder)? – Veronica So Jan 30 '16 at 21:28

unity can not directly read any ADF in the tango device.you have to first import those ADF into the API workspace. by using the method I mentioned above. – Lu sandy Jan 31 '16 at 1:03

I found my ADF in /sdcard/Maps/ – FrickeFresh Jun 3 at 8:52

如何查看ADF文件？

ADF文件被保存到什么地方？

ADF文件数据结构是怎样的    内容到底是什么