Back to contents pageHow to get/set/remove an object's position using the API

How to get/set/remove an object's position using the API

Summary

This article shows different ways to get, set or remove an object's position using a CellData schema or a Multicell object. The sample application has an interface to get an object's position from a cached schema and modify the selected object's position in the server.

Prerequisites

None. You can use this article on its own.

Example material

Save this link to get a zip file of the example material

Guide

Before you start

The Location Cell Manager Service updates the Ubisense.ULocation.CellData.Location relation of its Location Cell with the most up-to-date information on the objects that are being located by the Location Engine Cells (Sensor Cells) under it.

There are two classes we can use to get, set or remove objects' locations in an application; the Ubisense.ULocation.CellData.Schema class or Ubisense.ULocation.MultiCell class. Each of these classes can provide a ReadTransaction object to find an object's location or a schema with different remote operations to directly access the Location relation at the server. Now consider how these methods communicate with the server.

Synchronous remote operations

The majority of the remote operations are synchronous. They will wait for a response from the server and will confirm the persistence of the data committed.

Asynchronous remote operations

These methods will only send the request to the server and will not wait for a response from it; for this reason these methods can be called at a high rate. They don't guarantee that the results are persistent, but if used in a scenario where you need to constantly modify the location of an object, the possible failure of a remote operation call shouldn't make a great impact in your application since a new call is coming shortly after.

Using a CellData schema

1) Prepare the schema

We need to instantiate a CellData schema and connect it to the cell whose location data we want to access.

    // Instantiating the cellDataSchema object
    Ubisense.ULocation.CellData.Schema cellDataSchema = new
        Ubisense.ULocation.CellData.Schema(false);

    // Connect the cellDataSchema
    cellDataSchema.ConnectAsClient(cell.Id.ToString());

Note: To connect to cellDataSchema, you need to provide the Id of a Ubisense.ULocation.Cell in your system. See How to connect as a client to schema services
for instructions on how to do this.

2) Get an object's location from a cached Schema

We can iterate over the contents of the Location relation of the object you decided to use (CellData or Multicell). If there is a specific object of interest, locatedObject, we can get a cursor to the row containing its location information.

    using (Ubisense.ULocation.CellData.ReadTransaction xact =
        cellDataSchema.ReadTransaction())
    {
        foreach (Ubisense.ULocation.CellData.Location.RowType row
            in Ubisense.ULocation.CellData.Location.object_(xact,locatedObject))
        {
            DoSomethingWith(row);
            // row.position_.P.X;
            // row.position_.P.Y;
            // row.position_.P.Z;
        }
    }

3) Get an object's location with a remote operation (Synchronously)

The CellData.Schema provides a remote operation to get an object's location. Remember that querying a cached schema is recommended over remote operations as these are are executed at the server. This method is synchronous (waits for a response from the server) and is used like this:

    // Create a container for the result of the query
    Ubisense.ULocation.CellData.Location.RowType row = new
        Ubisense.ULocation.CellData.Location.RowType();

    // Get the location data
    cellDataSchema.get_object(locatedObject, out row);

    // Manipulate the data as desired
    DoSomethingWith(row);

4) Set an object's location (Synchronously)

    // Fill an event object with the desired parameters
    Ubisense.ULocation.LocationEvent singleEvent =
        new Ubisense.ULocation.LocationEvent
        (
            objectToMove,// the object to move
            false,       // remove flag, leave as false
            newPosition, // the new Position
            time,        // specify the time of the event
            accuracy     // specify the accuracy of the position
        );

    // Apply the event
    cellDataSchema.apply_event(singleEvent);

    // Create a list of events
    List<Ubisense.ULocation.LocationEvent> events = new
        List<Ubisense.ULocation.LocationEvent>();

    // Add the events to the list
    events.Add(firstEvent);
    events.Add(secondEvent);
    .
    .
    .

    // Commit the events in the list
    cellDataSchema.apply_events(eventsList);

5) Set an object's location (Asynchronously)

6) Remove an object's location (Synchronously and Asynchronously)

You can use the previous methods to remove an object's position by simply modifying the remove_ flag when creating the event to commit.

    // Fill an event object with the desired parameters
    Ubisense.ULocation.LocationEvent singleEvent =
        new Ubisense.ULocation.LocationEvent
        (
            objectToRemove,// the object to remove
            true,          // SET THIS TO TRUE TO REMOVE AN OBJECT'S POSITION
            newPosition,   // the new Position
            time,          // specify the time of the event
            accuracy       // specify the accuracy of the position
        );

    // Commit the event with one of the previous methods
    // a) Synchronous
    cellDataSchema.apply_event(singleEvent);

    // If is part of a list...
    // b) Synchronous
    cellDataSchema.locate_objects(eventsList);

    // Or...
    // c) Asynchronous
    cellDataSchema.apply_eventa(eventsList);

Using a Multicell object

Another way to get object locations is using a Multicell object. The Ubisense.ULocation.Multicell class is a client for loading multiple cells at once. The client merges events from the cells into a single ULocation.CellData.Schema. With it we can query location data and also insert location events into the platform.

1) Prepare the schema

First we need instantiate the Multicell object and to load the cells whose locations we want to access

    // Instantiate the MultiCell object
    Ubisense.ULocation.MultiCell multicell = new Ubisense.ULocation.MultiCell();

    // load all the available cells
    foreach (KeyValuePair<string, Ubisense.ULocation.Cell> cell
        in multicell.GetAvailableCells())
    {
        multicell.LoadCell(cell.Value, true);
    }

2) Get an object's location from a cached Schema

In this case the ReadTransaction is provided by the Multicell.Schema

    // MultiCell.Schema is of the same type as CellData.Schema
    using (Ubisense.ULocation.CellData.ReadTransaction xact =
        multicell.Schema.ReadTransaction())
    {
        foreach (Ubisense.ULocation.CellData.Location.RowType row
            in Ubisense.ULocation.CellData.Location.object_(xact, locatedObject))
        {
            DoSomethingWith(row);
        }
    }

3) Set an object's location (Synchronously)

The Multicell methods to set an object's position only require the new position.

// Set a persistent object location within one of the subscribed cells
multicell.SetObjectLocation(objectToMove, newPosition)

4) Set an object's location (Asynchronously)

    // A location cell is chosen, from those currently loaded, that best contains the
    // position. If the position is contained in more than one cell, the smallest
    // cell is chosen.
    multicell.InjectObjectLocation(objectToMove, newPosition);

5) Remove an object's location (Synchronously)

multicell.RemoveObjectLocation(objectToRemove);

The sample application

1) What it does

Gets all the entries from the Naming schema and displays them in a listview control.
When the user selects an item from the listview control, the application sets the selectedObj.
The Get Position button, searches for the selected item in the Location relation and when it founds it, it updates the x,y,z labels.
The Set Position button sets the selected item's position to x,y,z values in the textboxes.
Finally the Remove Position button removes the object and its location from the Location relation.

2) Using the application

Create some objects and place them using the Site Manager tool.
Run the application and verify that the created objects appear in the listview. Select an object and click the Get Position button to see the object's current position. Try moving the objects in Site Manager to get different results.
When you open a visualization like Site Manager->Area, or the one in Map you can see that your changes reflect the position of objects.
Try modifying the source code to use the remote operations of the CellData.Schema (connecting it to one of your installation's cells) or create your own application that uses the asynchronous methods.