Using System Coordinates

System Coordinates

Adsum Projector is used to convert position between all coordinate system used in Adsum Web Map:

• Global Positioning System (GPS)
• Adsum 3D system, used by the 3D engine.
• Universal Transverse Mercator (UTM)

GPS

See Global Positioning System (GPS)

UTM

UTM is an intermediate system between GPS and Adsum 3D system:

• Is a Cartesian coordinate system contrary to GPS.
• Consists of 3 axes (E, N, alt) with E matching pointing to the East, N to the North and alt to the sky.
• Unit is in meter

See Universal Transverse Mercator (UTM)

Adsum 3D System

The Adsum 3D System is the one used by the 3D engine:

• Consists of 3 axes (x, y, z) with z pointing to the sky. (x, y) axes are arbitrary oriented, contrary to UTM.
• Unit is arbitrary, ie there is no special meaning contrary to UTM one.

Adsum 3D Engine manage the data using a Scene Graph. To summarize, data is organized using a tree data structure which can be represented as:

├── Site
│   ├── Building#01
│       ├── Floor#01
│           ├── Space#01
│           ├── Space#02
│       ├── Floor#02
│           ├── Space#01
│           ├── Space#02
│               ├── Label#01
│       ├── Floor#03
│           ├── Label#02
│       ├── Label#03
│   ├── Building#02
│       ├── Floor#04

Every object position is relative to it's parent. For example, if Label#01 is positioned at (1, 2, 3) (using for example LabelObject#moveTo) the position is (1, 2, 3) is the Space#02 Local Adsum 3D System.

If we apply this rule recursively, up to the root we arrived to the World Adsum 3D System.

What you need to understandf is that every object is has 2 Adsum 3D Position, the local one (relative to parent) and the world one (absolute). This can be compare to relative/absolute positioning in CSS.

Using Adsum Projector

Adsum projector is the class responsible for coordinate system conversion.

Convert GPS from/to UTM

Converting GPS from/to UTM is pretty straightforward using AdsumProjector.gpsToUtm and AdsumProjector.utmToGps.

Convert Adsum Distance from/to Meters

As we said previously, Adsum 3D System unit is arbitrary. So if you want to convert it to meter simply use AdsumProjector.meterToAdsumDistance and AdsumProjector.adsumDistanceToMeter.

GPS/UTM from/to Adsum 3D System

The conversion to Adsum 3D System is a little bit tricky as we have in fact 2 intrepretation of the Adsum 3D System: World & Local.

To convert to World Adsum 3D System simply do:

// Convert to World Adsum 3D System
projector.gpsToAdsum(gps);
projector.utmToAdsum(utm);

But if you want to have the position relative to the SiteObject or a FloorObject you need to pass it as a second argument.

// Convert to Site's Local Adsum 3D System 
projector.gpsToAdsum(gps, site);
projector.utmToAdsum(utm, site);

// Convert to Floor's Local Adsum 3D System 
projector.gpsToAdsum(gps, floor);
projector.utmToAdsum(utm, floor);

In the same way, you can do:

// Convert World Adsum 3D System to GPS/UTM
projector.adsumToGps(position);
projector.adsumToUtm(position);

// Convert Site's Local Adsum 3D System to GPS/UTM
projector.adsumToGps(position, site);
projector.adsumToUtm(position, site);

// Convert Floor's Local Adsum 3D System to GPS/UTM 
projector.adsumToGps(position, floor);
projector.adsumToUtm(position, floor);

AdsumLocation from/to GPS/UTM/Adsum 3D System

AdsumLocation can be seen as reference to a position. They are used by Path to reference a potentially moving position as an User.

Using LocationRepository.userLocation will always reference the real user location updated using WayfindingManager.setUserGpsPosition, WayfindingManager.setUserUtmPosition or WayfindingManager.setUserAdsumPosition.

You can convert an AdsumLocation to GPS/UTM using:

// Convert AdsumLocation to GPS/UTM
projector.adsumLocationToGps(position);
projector.adsumLocationToUtm(position);

Keep in mind that AdsumLocation are dynamic, so the retrieved position may be outdated if the referenced position has been updated.