Energy Loss Monitoring

Energy loss reports will be sent by MDM to PlanetGIS' API, once per day at 07:00 containing data for the previous day. Energy loss will be visualized in the GIS by polygons generated by a convex hull algorithm, which is the smallest convex polygon containing all point locations of both master and slave meters referenced in each energy loss report.

Energy loss zones

Energy loss will be visualized as zones which are automatically created polygons with a unique zone name. Each zone will receive a daily report with energy loss values. The polygons can then be coloured according to parameters as desired, e.g. the percentage of loss or the change in loss values from an average, etc.

Polygon generation

The algorithm selected by the client for the generation of zone polygons is the Convex Hull algorithm. A convex hull is a simple polygon that is the smallest possible polygon that includes a set of points, but such that there are no concave shapes formed along the edge. If one were to walk along the edge of the polygon, in a counter-clockwise direction (the standard orientation for polygons in most GIS systems), you would never make a turn to your right.

The points used to generate each polygon are the locations of both the slave meters (meters installed at points of consumption) and master meters (meters placed somewhere between consumers and the main source of electricity supply).

When an energy loss report is received by the API, it looks for a polygon with the same zone name (the ZoneName attribute). If no such polygon exists, it is created with the convex hull algorithm and the locations of all meters in the MasterMeters attribute plus the locations of all meters referenced in the SlaveMeters attribute. If a polygon is found with the same zone name, the API will update the polygon's geometry based on the locations of the meters as specified.

Additionally, the loss information is stored in a separate table, linked to the polygon.

Identifying zone polygons

The ZoneName attribute was chosen as a unique identifier for the polygon features, in keeping with the rest of the API that does not require knowledge of PlanetGIS' internal Ids. Should this be a problem, i.e. if inadvertent duplication of zone names cannot be avoided, the API can be changed to use the FeatureId instead.

Zone polygon attributes

The Energy loss zones feature class currently has the following attributes:

Energy loss reports

Energy loss reports, like alerts, will be stored as PlanetGIS actions, which is a typical way to store temporal information connected to features (or other types of entities) via a parent-child relationship.

Each new report will be a new action, in order to collect data over time for graphing and analysis. PlanetGIS displays the most recent action in the Attributes tab for a selected feature.

Report attributes

To discuss: The specification currently additionally includes an Alert bit flag attribute, which is understood to simply be the result of the expression LossPercent >= PercentForAlert. It might be better to use an expression whenever this flag is needed. The same might apply to LossKWh and LossPercent which presumably can be calculated from MasterConsumption and SlaveConsumption

The Energy loss reports action class currently has the following attributes:

Report attachments

Graphs showing energy loss over time can be attached to zone polygons via the API, replacing previous graphs so that the polygon only has the latest attached. Alternatively, a graph can be attached to each energy loss report. See Attachments in the previous chapter for a description of the API available for this.

In a future version, such graphs can be generated by using JavaScript, from the collected temporal information in the PlanetGIS database. This would be preferable to the accumulation of attachments that will increase storage requirements over time.

API description

Energy loss reports accumulate over time and therefore the API does not have the ability to delete or modify them, though a loss report with the same ZoneName and Date (exact date and time) will be replaced. (Deletions and modifications to loss reports can be done in PlanetGIS.) An entire zone polygon and all it's loss reports ever received, can be deleted through the API (see below).

Uploading loss reports

To send new energy loss reports to PlanetGIS, the following endpoint is available:

/MDM/Loss/Update

A whole day's (or multiple days of) data can be sent in a single request or broken up, depending on preference. Two JSON schemas are used to process loss reports because the data needs to be split between two tables in PlanetGIS. The first is an attribute table for the Energy loss zones feature class and the second is an attribute table for the Energy loss reports action class, as described above. The schemas are as follows:

/MDM/Loss/Update/Schema1

/MDM/Loss/Update/Schema2

Here is an example of uploading a single loss report:

[
  {
    ZoneName: "Loss zone 1",
    MasterMeters: [2, 8],
    SlaveMeters: [5, 6, 4, 3, 7],
    Date: "2024-06-14T07:00:00",
    MasterConsumption: 100,
    SlaveConsumption: 80,
    LossKWh: 20,
    LossPercent: 20,
    PercentForAlert: 10
  }
]

The response to the above, before the polygon was created, is:

{
  "Request": "Update energy loss",
  "$Updates": [
    {
      "Loss zone 1": "created"
    },
    {
      "2024-06-14 07:00:00": "created"
    }
  ]
}

The $Updates array contains a mix of information about changes to the zone polygon and loss reports. Additional uploads with the same ZoneName and exact same Date will replace the loss report and the response will show unchanged for the zone polygon and changed or unchanged for the loss report, depending on whether any of the other attributes have changed.

The combined values of SlaveMeters and MasterMeters, of the last report received, will determine the shape of the zone polygon. A zone polygon (or any changes to it) will be visibile in the GIS, after about 10 seconds since submitting the data.

Deleting loss zones

To delete an energy loss zone, together with all loss reports for that zone ever received, the following endpoint is available:

/MDM/Loss/Delete

Multiple zones can be deleted with one request. Each zone must be uniquely identified with the ZoneName attribute. The update schema is:

/MDM/Loss/Delete/Schema

Here is an example of deleting a single loss zone:

[
  {
    "ZoneName": "Loss zone 1"
  }
]

An example response is:

{
  "Request": "Delete loss zones",
  "$Updates": [
    {
      "Loss zone 1": "deleted, including 1 child"
    }
  ]
}

The response indicates that one loss report was deleted as well as the feature, because the loss report is a child of the feature. Attachments to either the zone polygon or the loss reports will also be deleted, but only if such attachments are not linked to any other entities (in which case they will just be unlinked).