Salta ai contenuti
Seleziona lingua:Italiano
Questa pagina è disponibile solo in inglese.

Spatial entities

Aggiornato il 3 min di lettura

To work with the GiPStech MDK, it is essential to understand the following concepts:

  • Tile: The world is divided into a grid of tiles.
  • Region: A geographic area that intersects one or more tiles.
  • Building: A physical structure.
  • Floor: A specific level within a building.

Additionally, there are two distinct logical levels related to buildings:

  • BuildingInfo: Represents the building data as stored in the GiPStech Cloud Service.
  • Building: Represents a compiled version of a building, ready for use within the system.

The main difference between the two is that BuildingInfo is the object retrieved from queries to the GiPStech database, while Building is its compiled version, which can be used to initiate localization. The two entities may not be aligned, for example, if a floor is added to a building but the building has not been recompiled afterward.

Similarly, the classes FloorInfo and Floor exist, representing the database entity and the data contained in the compiled building file, respectively.

These spatial entities can be retrieved from the GiPStech Server through the SpatialManager class. This class provides three types of functions:

  1. Functions starting with request:

    • These functions retrieve data from the GiPStech Server.
    • They include an additional parameter, fallback, which allows loading cached data when an internet connection is unavailable.
  2. Functions starting with load:

    • These functions exclusively load cached data without making network requests.
  3. Functions starting with query:

The localization process can be initiated directly from instances of classes that inherit from the Place class, such as Building and Region.

The MDK can retrieve additional data — beyond what is required for pure localization — packaged in auxiliary files, represented by the AuxiliaryFile class. Each auxiliary file has a specific purpose, defined by the AuxiliaryFile.Purpose enum.

When downloading building and region data, the MDK automatically retrieves the auxiliary files associated with them. Starting from version 3.2.0, however, only auxiliary files with the Internal purpose are retrieved by default. To include auxiliary files with other purposes, you must register them using SpatialManager.addAuxPurpose.

After making the requests, you can retrieve the automatically downloaded auxiliary files associated with a given place by using Place.findAuxiliaryFiles and specifying the required purpose.

Auxiliary files that are not configured for automatic download can be managed explicitly through AuxiliaryFileHandle. First, obtain the available handles for the required purpose using getAuxiliaryFileHandles. The returned list can then be used to inspect the overall status of the associated files by calling requestSummary.

The returned summary provides:

  • areAllAvailable, which indicates whether all files are already available locally.
  • totalLocalSize, which reports the total size of the files currently available locally.
  • areAllUpdated, which indicates whether all local files are up to date. It is null when the remote status cannot be determined.
  • totalUpdateSize, which reports the total size of the required downloads, allowing the application, for example, to ask the user for confirmation before downloading an update.

Based on this information, the application can decide whether to use the files already available locally or retrieve the latest version. Use findAuxiliaryFiles to access the currently available local files without performing a download, or requestAuxiliaryFiles to download the required files and return the resulting local files. Individual handles can also be inspected and managed separately through AuxiliaryFileHandle.requestStatus, AuxiliaryFileHandle.findAuxiliaryFiles, and AuxiliaryFileHandle.requestAuxiliaryFiles when finer-grained control is required.

The following code obtains the current location from the operating system, retrieves a list of nearby buildings within a 1000-meter radius, and then fetches the corresponding Building object, which can later be used to initiate localization.

val location = SpatialManager.getLocationFromOS()
if (location != null) {
val list = SpatialManager.queryBuildingsNearby(location, 1000.0)
val buildingInfo = list.minByOrNull {
location.distanceTo(it.longitude, it.latitude)
}
if (buildingInfo != null) {
val building = SpatialManager.requestBuilding(buildingInfo.id)
print("Building: ${building.name}")
}
}

The following code demonstrates how to request a region 1 Km wide around the current location. The parameter fallback is set to true, allowing cached data to be used when no internet connection is available.

val location = SpatialManager.getLocationFromOS()
if (location != null) {
val (sw, ne) = location.getBoundingBox(1000.0)
var region = SpatialManager.requestRegion(
southWest = sw,
northEast = ne,
fallback = true,
)
}

Later the area can be elarged like in the following code.

region.requestAdditionalArea(
southWest = sw,
northEast = ne,
fallback = true
)