platform sdk maps

About maps

In Security Center, a Map entity displays a floor plan, a site layout, or a georeferenced map in two dimensions. It shows the position of cameras, doors, areas, and other entities for operators in Security Desk. Each item placed on a map is a MapObject linked either to a Security Center entity or rendered as a custom shape, image, or text label. The Platform SDK reads and writes the map's contents through the Map entity:

Map map = engine.GetEntity<Map>(mapGuid);
ReadOnlyCollection<MapObject> existingObjects = map.MapObjects;

Map.MapObjects is read-only. Add, modify, or delete map objects through Map.Add, Map.Update, and Map.Remove.

Map object types

Map object types that you can create are defined in Genetec.Sdk.Entities.Maps, derive from MapObject, and have a public parameterless constructor. The available types are:

• Entity-linked: CameraMapObject, DoorMapObject, AccessControlUnitMapObject, LprUnitMapObject, DeviceMapObject, ZoneMapObject, IntrusionAreaMapObject, AreaMapObject, MacroMapObject, MapMapObject, CustomEntityMapObject, AlarmMapObject, TilePluginMapObject, SequenceMapObject.
• Shapes: EllipseMapObject, RectangleMapObject, LineMapObject, PolygonMapObject.
• Image and text: ImageMapObject, TextBlockMapObject.

Most types derive from MapRelativeObject, which adds RelativeWidth and RelativeHeight for sizing. The base MapObject exposes the properties common to all types: Id, LinkedEntity, Latitude, Longitude, Rotation, LayerId, and ZIndex.

LayerId identifies the map layer that contains the object. CameraMapObject, DoorMapObject, and AreaMapObject use fixed layers. Assigning a different GUID to their LayerId property does not change the layer ID returned by the object.

Adding a map object

Construct a concrete map object, set its properties, and call Map.Add. For entity-linked types, set the target entity's Guid on LinkedEntity:

var camera = new CameraMapObject
{
    LinkedEntity = cameraGuid,
    Latitude = 45.5,
    Longitude = -73.6,
    Rotation = 90.0,
    AngleOfView = 75.0,
    MaxDistance = 50.0,
};

map.Add(camera);

For decorative types, populate the type-specific properties:

var label = new TextBlockMapObject
{
    Text = "Lobby",
    Latitude = 45.5,
    Longitude = -73.6,
    FontSize = 14,
    FontIsBold = true,
};

map.Add(label);

Updating a map object

Modify an existing map object retrieved from Map.MapObjects and call Map.Update:

CameraMapObject camera = map.MapObjects
    .OfType<CameraMapObject>()
    .FirstOrDefault(o => o.LinkedEntity == cameraGuid);

if (camera != null)
{
    camera.Rotation = 180.0;
    camera.AngleOfView = 90.0;
    map.Update(camera);
}

Map.RefreshMapObject(mapObject) discards unsaved local changes on a map object and restores the values it last received from Security Center. It updates the instance you pass and returns that same instance. Pass an object you obtained from Map.MapObjects; a map object you constructed yourself has nothing to restore. To read the current state of a map, read Map.MapObjects again.

Removing a map object

Pass the map object's Id to Map.Remove:

CameraMapObject toRemove = map.MapObjects
    .OfType<CameraMapObject>()
    .FirstOrDefault(o => o.LinkedEntity == cameraGuid);

if (toRemove != null)
{
    map.Remove(toRemove.Id);
}

Id is the Guid that identifies the map object within the map. It is independent of the linked entity's Guid, so always pass Id, not LinkedEntity, to Remove.

Coordinates on georeferenced and non-georeferenced maps

Map.IsGeoReferenced indicates whether the map's coordinate system represents real geographic positions. On a georeferenced map, MapObject.Latitude and MapObject.Longitude are real coordinates and are validated when you call Add or Update. On a non-georeferenced map (a floor plan or schematic), the same properties are pixel-relative numbers within the image and are not validated.