Relative Location Representation
draft-thomson-geopriv-relative-location-00

Abstract

This document defines an extension to PIDF-LO (RFC4119) for the expression of location information that is defined relative to a reference point. The reference point may be expressed as a geodetic or civic location, and the relative offset may be one of several shapes. Optionally, a reference to a secondary document (such as a map image) can be included, along with the relationship of the map coordinate system to the reference/offset coordinate system to allow display of the map with the reference point and the relative offset. Also included in this document is a Type/Length/Value (TLV) representation of the relative location for use in other protocols that use TLVs.

Status of This Memo

This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on August 30, 2010.

Copyright Notice

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the BSD License.

Table of Contents

1.  Introduction
2.  Conventions used in this document
3.  Overview
4.  Binary Format
5.  Relative Location
    5.1.  Orientation of Relative Offset Coordinate Reference System
6.  Shape Encoding
    6.1.  Units of Measure
    6.2.  Coordinates
    6.3.  On Uncertainty and Encoding
7.  Shapes
    7.1.  Point
        7.1.1.  XML encoding
        7.1.2.  TLV encoding
    7.2.  Circle or Sphere Shape
        7.2.1.  XML encoding
        7.2.2.  TLV encoding
    7.3.  Ellipse or Ellipsoid Shape
        7.3.1.  XML encoding
        7.3.2.  TLV encoding
    7.4.  Polygon or Prism Shape
        7.4.1.  XML Encoding
        7.4.2.  Arc-Band Shape
8.  Secondary Map Metadata
    8.1.  Map URL
    8.2.  Map Coordinate Reference System
        8.2.1.  Map Reference Point Offset
        8.2.2.  Map Orientation
        8.2.3.  Map Scale
9.  Examples
    9.1.  Civic PIDF with Polygon Offset
    9.2.  Geo PIDF with Circle Offset
    9.3.  Civic TLV with Point Offset
10.  Schema Definition
11.  Security Considerations
12.  IANA Considerations
    12.1.  Relative Location Registry
    12.2.  URN Sub-Namespace Registration for urn:ietf:params:xml:ns:pidf:????
13.  Acknowledgements
14.  References
    14.1.  Normative References
    14.2.  Informative References

1.  Introduction

This document describes a format for the expression of relative location information.

The location is given relative to a reference, which is expressed with a civic or geodetic representation, with the relative offset as described in this document. The offset is expressed in meters, and a directional vector is either implied to be earth North/East or supplied explicitly. Also defined is an optional URI to a document that can contain a map/floorplan/illustration ('map') upon which the relative location can be plotted as well as an optional angle, offset and scale defining the Coordinate Reference System (CRS) of the map.

Two formats are included: an XML form that is intended for use in PIDF-LO [RFC4119] (Peterson, J., “A Presence-based GEOPRIV Location Object Format,” December 2005.) and a TLV format for use in other protocols such as those that already convey binary representation of location information defined in [RFC4776] (Schulzrinne, H., “Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information,” November 2006.).

2.  Conventions used in this document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

Numeric values in this scheme are all represented using floating point values [IEEE.754] (IEEE, “IEEE Standard for Binary Floating-Point Arithmetic,” January 2003.). Single precision values are 32-bit values with a sign bit, 8 exponent bits and 23 fractional bits. Double precision values are 64-bit values with a sign bit, 11 exponent bits and 52 fractional bits.

3.  Overview

This document describes an update to PIDF-LO [RFC4119] (Peterson, J., “A Presence-based GEOPRIV Location Object Format,” December 2005.) as updated by [RFC5139] (Thomson, M. and J. Winterbottom, “Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO),” February 2008.) and [RFC5491] (Winterbottom, J., Thomson, M., and H. Tschofenig, “GEOPRIV Presence Information Data Format Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations,” March 2009.), to allow the expression of a location relative to a reference. The reference is described by using existing elements, and the offset is additional data to the tuple.

The reference point is defined either as a geodetic location (Thomson, M. and C. Reed, “GML 3.1.1 PIDF-LO Shape Application Schema for use by the Internet Engineering Task Force (IETF),” April 2007.) [OGC.GeoShape] or a civic address (Schulzrinne, H., “Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information,” November 2006.) [RFC4776].

The relative location can be expressed using a point (2- or 3-dimensional), or a shape that includes uncertainty: circle, sphere, ellipse, ellipsoid, polygon, prism or arc-band. Descriptions of these shapes can be found in [RFC5491] (Winterbottom, J., Thomson, M., and H. Tschofenig, “GEOPRIV Presence Information Data Format Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations,” March 2009.).

Optionally, a reference to a 'map' document can be provided. The reference is a URI. The document could be an image or dataset that represents a map, floorplan or other form. The type of document the URI points to is described as a mime type. Metadata in the relative location can include the location of the reference point in the map as well as an orientation (angle from North) and scale to align the document CRS with the WGS-84 CRS. The document is assumed to be useable by the application receiving the PIDF with the relative location to locate the reference point in the map. This document does not describe any mechanisms for displaying or manipulating the document other than providing the reference location, orientation and scale.

As an example, consider a relative location expressed as a point, relative to a civic location:

    <presence xmlns="urn:ietf:params:xml:ns:pidf"
              xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
              xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
              xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
              xmlns:gml="http://www.opengis.net/gml"
              xmlns:gs="http://www.opengis.net/pidflo/1.0"
              entity="pres:ness@example.com">
      <dm:device id="nesspc-1">
        <gp:geopriv>
          <gp:location-info>
            <ca:civicAddress xml:lang="en-AU">
              <ca:country>AU</ca:country>
              <ca:A1>NSW</ca:A1>
              <ca:A3>Wollongong</ca:A3>
              <ca:A4>North Wollongong</ca:A4>
              <ca:RD>Flinders</ca:RD>
              <ca:STS>Street</ca:STS>
              <ca:HNO>123</ca:HNO>
              <ca:INT N="Door" R="A">Front</ca:INT>
            </ca:civicAddress>
            <gp:relative-location>
              <gp:shape>
                <gml:Point xmlns:gml="http://www.opengis.net/gml"
                    srsName="--TBD--">
                    <gml:pos>100 50</gml:pos>
                </gml:Point>
             </gp:shape>
            </gp:relative-location>
          </gp:location-info>
          <gp:usage-rules/>
          <gp:method>GPS</gp:method>
        </gp:geopriv>
        <dm:deviceID>mac:1234567890ab</dm:deviceID>
        <dm:timestamp>2007-06-22T20:57:29Z</dm:timestamp>
      </dm:device>
    </presence>

4.  Binary Format

This document describes a way to encode the relative location in a binary TLV form for use in other protocols that use TLVs to represent location.

A type-length-value encoding is used.

+------+------+------+------+------+------+------+------+
| Type |   Length    |  Value                         ...
+------+------+------+------+------+------+------+------+
|  X   |      N      |  Value label                   ...
+------+------+------+------+------+------+------+------+

Type field (X) is defined as a single byte. The type codes used are registered an IANA managed 'RLtypes' registry defined by this document, and restricted to not include the values defined by the CAtypes registry. This restriction permits a location reference and offset to be coded with unique TLVs.

The Length field (N) is defined as an unsigned integer that is two bytes in length. This field can encode values from 0 to 65535. The length field describes the number of bytes in the Value. Length does not count the bytes used for the Type or Length. Note that the length field of a TLVs using the CAtypes registry (such as those defined in [RFC5139] (Thomson, M. and J. Winterbottom, “Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO),” February 2008.) are one byte. Since the type codes defined here are restricted to be different from the CAtypes, the difference in the length field can be accommodated.

The value field is defined explicitly for each shape in this document.

5.  Relative Location

Relative location is a shape (point, circle, ellipse…). The shape is defined with a CRS that has a datum defined as the reference (which appears as a civicLoc or gml-location in the tuple), and the shape coordinates as meter offsets North/East of the datum measured in meters (with an optional Z offset relative to datum altitude). An optional angle allows the reference CRS be to rotated with respect to North.

A 2-dimensional reference MUST have a 2-dimensional relative offset, and a 3-dimensional reference MUST have a 3-dimensional offset. This makes the selection of 2-D or 3-D CRS defined by the reference.

The offset is contained in a <relative-offset> element extending the <geopriv> element of a PIDF-LO. Within <relative-offset> the <shape> element contains the shape encoded as described in Section 6 (Shape Encoding).

Ed. Note, the authors are not unanimous in defining the reference location as the civic or geo location-info currently defined in a PIDF-LO with the additional <relative-offset> element. Some authors point out that an implementation that encounters the <relative-offset> but does not implement it would ignore it, and treat the reference as the actual location of the target, which is incorrect, especially considering that the offset could potentially be very large, and thus the actual location could differ from the reference by a considerable distance. The remaining authors believe that such uses are very rare, the document should contain a warning about the possibility of error, and that the very best possible location that could be provided in the case that the implementation does not implement this extension is the reference. They believe that the reference is a better location than no location. If the work group decides that the reference should not be understood as the location if an implementation does not understand <relative-offset>, then this document would define <relative-location> as a <location-info> and within that, define a <reference> element containing a gml or civicLoc element plus an <offset> element. An implementation encountering the <relative-location> would ignore the entire element, including the reference that is within it.

The individual elements of the relative location have unique TLV assignments. A relative location encoded in TLV would have the location reference TLDs followed by the relative offset, and optional map TLDs described in this document.

More than one relative shape MUST NOT be included in either a PIDF-LO or TLV encoding of location for a given reference point. Any error in the reference point transfers to the location described by the relative location. Any errors arising from an implementation not supporting or understanding elements of the reference point directly increases the error (or uncertainty) in the resulting location.

5.1.  Orientation of Relative Offset Coordinate Reference System

The relative location element may contain an optional angle relative to North that defines the CRS of the offset. The offset CRS scale is always meters, and the datum is the reference. The angle is encoded as a single precision floating point degrees, with 0.0 representing North. In xml, the angle is contained in an <ro-angle> element, example <ro-angle>50.0</ro-angle>. In TLV encoding:

+------+------+------+------+------+------+------+
|  115 |   Length    |  Angle                    |
+------+------+------+------+------+------+------+

6.  Shape Encoding

Shape data is used to represent regions of uncertainty in the relative CRS.

The description of each shape type includes a description of how that type is encoded in Geography Markup Language (GML) (Cox, S., Daisey, P., Lake, R., Portele, C., and A. Whiteside, “Geographic information - Geography Markup Language (GML),” April 2004.) [OGC.GML‑3.1.1], consistent with the rules in [RFC5491] (Winterbottom, J., Thomson, M., and H. Tschofenig, “GEOPRIV Presence Information Data Format Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations,” March 2009.), but with a relative CRS. The CRS is identified by a distinguished urn --tbd-- defined by this document.

6.1.  Units of Measure

All distance measures used in shapes are expressed in meters using single precision floating point values.

All orientation angles used in shapes are expressed in degrees using single precision floating point values. Orientation angles are measured from WGS84 Northing to Easting with zero at Northing. Orientation angles in the relative coordinate system start from the second coordinate axis (y or Northing) and increase toward the first axis (x or Easting).

6.2.  Coordinates

Coordinates are a sequence of numeric values. These are encoded as a sequence of double precision floating point numbers.

Coordinates are represented using a single precision floating point value as described in IEEE 754 (IEEE, “IEEE Standard for Binary Floating-Point Arithmetic,” January 2003.) [IEEE.754].

Every CRS MUST define how many values are present in each set of coordinates, the axes that each value applies to, the order of axes, and the units that are used for each axis.

For the two-dimensional CRS, coordinates are made of two values. The first value corresponds to latitude (Easting). The second value corresponds to longitude (Northing). Both axis are rotated relative to North by the ro-angle, if present.

For the three-dimensional CRS, coordinates are made of three values, the first two of which are the same as for the two-dimensional CRS. The third value corresponds to the altitude above the plane of the horizontal at the reference location and is measured in meters.

6.3.  On Uncertainty and Encoding

Binary-encoded coordinate values are considered to be a single value without uncertainty. When encoding a value that cannot be exactly represented, the best approximation is chosen according to [Clinger1990] (Clinger, W., “How to Read Floating Point Numbers Accurately,” 1990.).

7.  Shapes

Nine shape type codes are defined.

7.1.  Point

A point "shape" describes a single point with unknown uncertainty. It consists of a single set of coordinates.

In a two-dimensional CRS, the coordinate includes two values; in a three-dimensional CRS, the coordinate includes three values.

7.1.1.  XML encoding

A point is represented in GML using the following template:

  <gml:Point xmlns:gml="http://www.opengis.net/gml"
             srsName="$CRS-URN$">
    <gml:pos>$Coordinate-1 $Coordinate-2$ $Coordinate-3$</gml:pos>
  </gml:Point>

Where $CRS-URN$ is replaced by a URN identifying the CRS and $Coordinate-3$ is omitted if the CRS is two-dimensional.

7.1.2.  TLV encoding

The point shape is introduced by a TLV of 116 for a 2D point and 117 for a 3D point.

+------+-------------+
| 116/7|    Length   |
+------+------+------+------+
|  Coordinate-1             |
+------+------+------+------+
|  Coordinate-2             |
+------+------+------+------+
|  (3D-only) Coordinate-3   |
+------+------+------+------+

7.2.  Circle or Sphere Shape

A circle or sphere describes a single point with a single uncertainty value in meters.

In a two-dimensional CRS, the coordinate includes two values and the resulting shape forms a circle. In a three-dimensional CRS, the coordinate includes three values and the resulting shape forms a sphere. The uncertainty radius is specified as a single precision floating point value (32 bits: 1 sign bit, 8 exponent bits, 23 fractional bits in binary).

The circle size is defined as a radius in meters encoded as single precision floating point value

7.2.1.  XML encoding

A circle is represented in and converted from GML using the following template:

  <gs:Circle xmlns:gml="http://www.opengis.net/gml"
             xmlns:gs="http://www.opengis.net/pidflo/1.0"
             srsName="$CRS-URN$">
    <gml:pos>$Coordinate-1 $Coordinate-2$</gml:pos>
    <gs:radius uom="urn:ogc:def:uom:EPSG::9001">
      $Radius$
    </gs:radius>
  </gs:Circle>

A sphere is represented in and converted from GML using the following template:

  <gs:Sphere xmlns:gml="http://www.opengis.net/gml"
             xmlns:gml="http://www.opengis.net/pidflo/1.0"
             srsName="$CRS-URN$">
    <gml:pos>$Coordinate-1 $Coordinate-2$ $Coordinate-3$</gml:pos>
    <gs:radius uom="urn:ogc:def:uom:EPSG::9001">
      $Radius$
    </gs:radius>
  </gs:Sphere>

7.2.2.  TLV encoding

A circular shape is introduced by a type code of 120. A spherical shape is introduced by a type code of 121.

+------+-------------+
| 120/1|    Length   |
+------+------+------+------+
|  Coordinate-1             |
+------+------+------+------+
|  Coordinate-2             |
+------+------+------+------+
|  (3D-only) Coordinate-3   |
+------+------+------+------+
|  Radius                   |
+------+------+------+------+

7.3.  Ellipse or Ellipsoid Shape

A ellipse or ellipsoid describes a point with an elliptical or ellipsoidal uncertainty region.

In a two-dimensional CRS, the coordinate includes two values, plus a semi-major axis, a semi-minor axis, a semi-major axis orientation (clockwise from North). In a three-dimensional CRS, the coordinate includes three values and in addition to the two-dimensional values, an altitude uncertainty (semi-vertical) is added.

Distance and angular measures are defined in meters and degrees respectively. Both are encoded as single precision floating point values.

7.3.1.  XML encoding

An ellipse is represented in and converted from GML using the following template:

  <gs:Ellipse xmlns:gml="http://www.opengis.net/gml"
              xmlns:gs="http://www.opengis.net/pidflo/1.0"
              srsName="$CRS-URN$">
    <gml:pos>$Coordinate-1 $Coordinate-2$</gml:pos>
    <gs:semiMajorAxis uom="urn:ogc:def:uom:EPSG::9001">
      $Semi-Major$
    </gs:semiMajorAxis>
    <gs:semiMinorAxis uom="urn:ogc:def:uom:EPSG::9001">
      $Semi-Minor$
    </gs:semiMinorAxis>
    <gs:orientation uom="urn:ogc:def:uom:EPSG::9102">
      $Orientation$
    </gs:orientation>
  </gs:Ellipse>

An ellipsoid is represented in and converted from GML using the following template:

  <gs:Ellipsoid xmlns:gml="http://www.opengis.net/gml"
                xmlns:gs="http://www.opengis.net/pidflo/1.0"
                srsName="$CRS-URN$">
    <gml:pos>$Coordinate-1 $Coordinate-2$ $Coordinate-3$</gml:pos>
    <gs:semiMajorAxis uom="urn:ogc:def:uom:EPSG::9001">
      $Semi-Major$
    </gs:semiMajorAxis>
    <gs:semiMinorAxis uom="urn:ogc:def:uom:EPSG::9001">
      $Semi-Minor$
    </gs:semiMinorAxis>
    <gs:verticalAxis uom="urn:ogc:def:uom:EPSG::9001">
      $Semi-Vertical$
    </gs:verticalAxis>
    <gs:orientation uom="urn:ogc:def:uom:EPSG::9102">
      $Orientation$
    </gs:orientation>
  </gs:Ellipsoid>

7.3.2.  TLV encoding

An ellipse is introduced by a type code of 118 and an ellipsoid is introduced by a type code of 119.

+------+-------------+
| 118/9|    Length   |
+------+------+------+------+
|  Coordinate-1             |
+------+------+------+------+
|  Coordinate-2             |
+------+------+------+------+
|  (3D-only) Coordinate-3   |
+------+------+------+------+------+------+------+------+
|  Semi-Major Axis          |  Semi-Minor Axis          |
+------+------+------+------+------+------+------+------+
|  Orientation              |  (3D) Semi-Vertical Axis  |
+------+------+------+------+------+------+------+------+

7.4.  Polygon or Prism Shape

A polygon or prism include a number of points that describe the outer boundary of an uncertainty region. A prism also includes an altitude and prism height.

At least 3 points MUST be included in a polygon. In order to interoperate with existing systems, an encoding SHOULD include 15 or fewer points, unless the recipient is known to support larger numbers.

The height of the prism is encoded as a single precision floating point value.

7.4.1.  XML Encoding

A polygon is represented in and converted from GML using the following template:

  <gml:Polygon xmlns:gml="http://www.opengis.net/gml"
               srsName="$CRS-URN$">
    <gml:exterior>
      <gml:LinearRing>
        <gml:posList>
          $Coordinate1-1$ $Coordinate1-2$
          $Coordinate2-1$ $Coordinate2-2$
          $Coordinate3-1$ ...
          ...
          $CoordinateN-1$ $CoordinateN-2$
          $Coordinate1-1$ $Coordinate1-2$
        </gml:posList>
      </gml:LinearRing>
    </gml:exterior>
  </gml:Polygon>

Alternatively, a series of pos elements can be used in place of the single posList. Each pos element contains two coordinate values.

Note that the first point is repeated at the end of the sequence of coordinates and no explicit count of the number of points is provided.

A GML polygon that includes altitude cannot be represented completely in binary. When converting to the binary representation, a two dimensional CRS is used and altitude is removed from each coordinate.

7.4.1.1.  XML encoding

A prism is represented in and converted from GML using the following template:

  <gs:Prism xmlns:gml="http://www.opengis.net/gml"
            xmlns:gs="http://www.opengis.net/pidflo/1.0"
            srsName="$CRS-URN$">
    <gs:base>
      <gml:Polygon>
        <gml:exterior>
          <gml:LinearRing>
            <gml:posList>
              $Coordinate1-1$ $Coordinate1-2$ $Coordinate1-3$
              $Coordinate2-1$ $Coordinate2-2$ $Coordinate2-3$
              $Coordinate2-1$ ... ...
              ...
              $CoordinateN-1$ $CoordinateN-2$ $CoordinateN-3$
              $Coordinate1-1$ $Coordinate1-2$ $Coordinate1-3$
            </gml:posList>
          </gml:LinearRing>
        </gml:exterior>
      </gml:Polygon>
    </gs:base>
    <gs:height uom="urn:ogc:def:uom:EPSG::9001">
      $Height$
    </gs:height>
  </gs:Prism>

Alternatively, a series of pos elements can be used in place of the single posList. Each pos element contains three coordinate values.

7.4.1.2.  TLV Encoding

A polygon is introduced with a type code of 120. A prism is introduced with a type code of 121.

+------+-------------+
| 120/1|    Length   |
+------+------+------+------+------+------+
|  Count      |  (3D-only) Height         |
+------+------+------+------+------+------+
|  Coordinate1-1            |
+------+------+------+------+
|  Coordinate1-2            |
+------+------+------+------+
|  (3D-only) Coordinate1-3  |
+------+------+------+------+
|  Coordinate2-1            |
+------+------+------+------+
 ...
+------+------+------+------+
|  CoordinateN-1            |
+------+------+------+------+
|  CoordinateN-2            |
+------+------+------+------+
|  (3D-only) CoordinateN-3  |
+------+------+------+------+

Note that unlike the polygon representation in GML, the first and last points are not required to be the same in the TLV representation. an explicit count of the number of points is provided in 'Count'.

7.4.2.  Arc-Band Shape

A arc-band describes a region constrained by a range of angles and distances from a predetermined point. This shape can only be provided for a two-dimensional CRS.

Distance and angular measures are defined in meters and degrees respectively. Both are encoded as single precision floating point values.

7.4.2.1.  XML encoding

An arc-band is represented in and converted from GML using the following template:

  <gs:ArcBand xmlns:gml="http://www.opengis.net/gml"
              xmlns:gs="http://www.opengis.net/pidflo/1.0"
              srsName="$CRS-URN$">
    <gml:pos>$Coordinate-1 $Coordinate-2$</gml:pos>
    <gs:innerRadius uom="urn:ogc:def:uom:EPSG::9001">
      $Inner-Radius$
    </gs:innerRadius>
    <gs:outerRadius uom="urn:ogc:def:uom:EPSG::9001">
      $Inner-Radius$
    </gs:outerRadius>
    <gs:startAngle uom="urn:ogc:def:uom:EPSG::9102">
     $Start-Angle$
    </gs:startAngle>
    <gs:openingAngle uom="urn:ogc:def:uom:EPSG::9102">
      $Opening-Angle$
    </gs:openingAngle>
  </gs:Ellipsoid>

7.4.2.2.  TLV Encoding

An arc-band is introduced by a type code of 122.

+------+-------------+
| 122  |    Length   |
+------+------+------+------+
|  Coordinate               |
+------+------+------+------+
|  Coordinate               |
+------+------+------+------+------+------+------+------+
|  Inner Radius             |  Outer Radius             |
+------+------+------+------+------+------+------+------+
|  Start Angle              |  Opening Angle            |
+------+------+------+------+------+------+------+------+

8.  Secondary Map Metadata

The optional "map" URL can be used to provide a user of relative location with a visual reference for the location information. This document does not describe how the recipient uses the map nor how it locates the reference or offset within the map. Maps can be simple images, vector files, 2-D or 3-D geospatial databases, or any other form of representation understood by both the sender and recipient.

8.1.  Map URL

In XML, the map is a <map> element defined within <relative-location> and contains the URL. The URL is encoded as a UTF-8 encoded string. An http: or https: URL MUST be used unless the entity creating the PIDF-LO is able to ensure that authorized recipients of this data are able to use other URI schemes. A "map-type" attribute MUST be present and specifies the kind of map the URL points to. Map types are specified as mime media types as recorded in the IANA Media Types registry. For example <map map-type="image/png">https://www.example.com/floorplans/123South/floor-2</map>. In binary, the maptype has a length (maplen) included in the overall TLV length:

+------+------+------+------+------+------+--  --+------+
|  123 |   Length    |maplen|   maptype       …  | Map Image URL   ...
+------+------+------+------+------+------+--  --+------+

8.2.  Map Coordinate Reference System

The CRS used by the map depends on the type of map. For example, a map described by a 3-D geometric model of the building may contain a complete CRS description in it. For some kinds of maps, typically described as images, the CRS used within the map must define the following:

• The CRS origin
• The CRS axes used and their orientation
• The unit of measure used

This document provides elements that allow for a mapping between the local coordinate reference system used for the relative location and the coordinate reference system used for the map where they are not the same.

8.2.1.  Map Reference Point Offset

This optional element identifies the coordinates of the reference point as it appears in the map. This value is measured in a map-type dependent manner, using the coordinate system of the map.

For image maps, coordinates start from the upper left corner and coordinates are first counted by column with positive values to the right; then rows are counted with positive values toward the bottom of the image. For such an image, the first item is columns, the second rows and any third value applies to any third dimension used in the image coordinate space.

The <map-offset> element contains 2 (or 3) coordinates similar to a GML pos, For example:

     <map-offset> 2670.0 1124.0 1022.0</map-offset>

   +------+-------------+
   | 124  |    Length   |
   +------+------+------+------+
   |  Coordinate-1             |
   +------+------+------+------+
   |  Coordinate-2             |
   +------+------+------+------+
   |  (3D-only) Coordinate-3   |
   +------+------+------+------+

The encoding for coordinates is described in Section 6.2 (Coordinates).

If omitted, a value containing all zeros is assumed. If the coordinates provided contain fewer values than are needed, the first value from the set is applied in place of any missing values.

8.2.2.  Map Orientation

The map orientation includes the orientation of the map direction ('UP') in relation to the Earth. Map orientation is expressed relative to the orientation of the relative coordinate system.  This means that map orientation with respect to WGS84 North is the sum of the two orientation fields.  Both values default to zero if no value is specified.

This type uses a single precision floating point value of degrees relative to North.

In XML, the <orientation> element contains a single floating point value, example <orientation>67.00</orientation>. In TLV form:

+------+------+------+------+------+------+------+
|  125 |   Length    |  Angle                    |
+------+------+------+------+------+------+------+

8.2.3.  Map Scale

The optional map scale describes the relationship between the units of measure used in the map, relative to the meters unit used in the relative coordinate system.

This type uses a sequence of IEEE 754 (IEEE, “IEEE Standard for Binary Floating-Point Arithmetic,” January 2003.) [IEEE.754] single precision floating point values to represent scale as a sequence of numeric values. The units of these values is map-type dependent, and could for example be pixels per meter in image map-types.

A scaling factor is provided for each axis in the coordinate system. For a two-dimensional coordinate system, two values are included to allow for different scaling along the x and y axes independently. For a three-dimensional coordinate system, three values are specified for the x, y and z axes.

Alternatively, a single scaling value MAY be used to apply the same scaling factor to all coordinate components.

Images that use a rows/columns coordinate system often use a left-handed coordinate system. A negative value for the y/rows-axis scaling value can be used to account for any change in direction between the y-axis used in the relative coordinate system and the rows axis of the image coordinate system.

In XML, the <scale> element may contain the single scale value, or may contain 2 (or 3) values similar to a GML pos with separate scale values. In TLV form:

+------+------+------+------+------+------+
|  126 |   Length    |  Scales       ...
+------+------+------+------+------+------+

9.  Examples

9.1.  Civic PIDF with Polygon Offset

    <presence xmlns="urn:ietf:params:xml:ns:pidf"
              xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
              xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
              xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
              xmlns:gml="http://www.opengis.net/gml"
              xmlns:gs="http://www.opengis.net/pidflo/1.0"
              entity="pres:ness@example.com">
      <dm:device id="nesspc-1">
        <gp:geopriv>
          <gp:location-info>
            <ca:civicAddress xml:lang="en-AU">
              <ca:country>AU</ca:country>
              <ca:A1>NSW</ca:A1>
              <ca:A3>Wollongong</ca:A3>
              <ca:A4>North Wollongong</ca:A4>
              <ca:RD>Flinders</ca:RD>
              <ca:STS>Street</ca:STS>
              <ca:HNO>123</ca:HNO>
              <ca:INT N="Building">A</ca:INT>
              <ca:INT N="Level">I</ca:INT>
              <ca:INT N="Suite">113</ca:INT>
              <ca:INT N="Door" R="A">Front</ca:INT>
            </ca:civicAddress>
            <gp:relative-location>
              <gp:shape>
                  <gml:Polygon srsName="helpme">
                   <gml:exterior>
                     <gml:LinearRing>
                       <gml:pos>433.0 -734.0</gml:pos> <!--A-->
                       <gml:pos>431.0 -733.0</gml:pos> <!--F-->
                       <gml:pos>431.0 -732.0</gml:pos> <!--E-->
                       <gml:pos>433.0 -731.0</gml:pos> <!--D-->
                       <gml:pos>434.0 -732.0</gml:pos> <!--C-->
                       <gml:pos>434.0 -733.0</gml:pos> <!--B-->
                       <gml:pos>433.0 -734.0</gml:pos> <!--A-->
                     </gml:LinearRing>
                   </gml:exterior>
                 </gml:Polygon>
              </gp:shape>
            </gp:relative-location>
          </gp:location-info>
         <gp:usage-rules/>
          <gp:method>GPS</gp:method>
        </gp:geopriv>
        <dm:deviceID>mac:1234567890ab</dm:deviceID>
        <dm:timestamp>2007-06-22T20:57:29Z</dm:timestamp>
      </dm:device>
    </presence>

9.2.  Geo PIDF with Circle Offset

<?xml version="1.0" encoding="UTF-8"?>
    <presence xmlns="urn:ietf:params:xml:ns:pidf"
              xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
              xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
              xmlns:cl="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
              xmlns:gml="http://www.opengis.net/gml"
              entity="pres:point2d@example.com">
      <dm:device id="point2d">
        <gp:geopriv>
          <gp:location-info>
            <gml:Point srsName="urn:ogc:def:crs:EPSG::4326">
              <gml:pos>-34.407 150.883</gml:pos>
            </gml:Point>
            <gp:relative-location>
              <gp:shape>
                <gs:Circle srsName="$helpme$">
                  <gml:pos>500.0 750.0</gml:pos>
                  <gs:radius uom="urn:ogc:def:uom:EPSG::9001">
                     5.0
                   </gs:radius>
                </gs:Circle>
              </gp:shape>
            </gp:relative-location>
            <gp:map>
              <gp:urltype="image/png">
                https://www.example.com/flrpln/123South/flr-2</gp:url>
              <gp:offset> 2670.0 1124.0 1022.0</gp:offset>
              <gp:orientation>67.00</gp:orientation>
              <gp:scale>10</gp:scale>
            </gp:map>
          </gp:location-info>
          <gp:usage-rules/>
          <gp:method>Wiremap</gp:method>
        </gp:geopriv>
        <dm:deviceID>mac:1234567890ab</dm:deviceID>
        <dm:timestamp>2007-06-22T20:57:29Z</dm:timestamp>
      </dm:device>
     </gp:geopriv>
    </status>
    <timestamp>2003-06-22T20:57:29Z</timestamp>
   </tuple>
  </presence>

9.3.  Civic TLV with Point Offset

        +--------+-------------------------------------------------+
        | Type   | Value                                           |
        +--------+-------------------------------------------------+
        | 0      | en                                              |
        |        |                                                 |
        | 1      | IL                                              |
        |        |                                                 |
        | 3      | Chicago                                         |
        |        |                                                 |
        | 34     | Wacker                                          |
        |        |                                                 |
        | 18     | Drive                                           |
        |        |                                                 |
        | 19     | 3400                                            |
        |        |                                                 |
        | 40     | BBuilding|A                                     |
        |        |                                                 |
        | 40     | AFloor|6th                                      |
        |        |                                                 |
        | 40     | BSuite|213                                      |
        |        |                                                 |
        | 40     | ADoor|Front                                     |
        |        |                                                 |
        | 116    | 100 70                                         |
        |        |                                                 |
        | 123    | image/png|http://maps.example.com/3400Wacker/A6 |
        |        |                                                 |
        | 124    | 0.0 4120.0                                      |
        |        |                                                 |
        | 125    | 113.0                                           |
        |        |                                                 |
        | 126    | 10.6                                            |
        +--------+-------------------------------------------------+

10.  Schema Definition

     --- TBD ----

11.  Security Considerations

This document describes a data format. To a large extent, security properties of this depend on how this data is used.

Privacy for location data is typically important. Adding relative location may increase the precision of the location, but does not otherwise alter its privacy considerations, which are discussed in [RFC4119] (Peterson, J., “A Presence-based GEOPRIV Location Object Format,” December 2005.)

[[Not that interesting, but it could be relevant ?]] The fractional bits in IEEE 754 (IEEE, “IEEE Standard for Binary Floating-Point Arithmetic,” January 2003.) [IEEE.754] floating point values can be used as a covert channel. For values of either zero or infinity, non-zero fraction bits could be used to convey information. If the presence of covert channels is not desired then the fractional bits MUST be set to zero. There is no need to represent NaN (not a number) in this encoding.

12.  IANA Considerations

12.1.  Relative Location Registry

This document creates a new registry called 'RLtypes'. As defined in [RFC5226] (Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” May 2008.), this registry operates under "IETF Consensus" rules.

The content of this registry includes:

RLtype: Numeric identifier, assigned by IANA.

Brief description: Short description identifying the meaning of the element.

Reference to published specification: A stable reference to an RFC which describes the value in sufficient detail so that interoperability between independent implementations is possible.

IANA is requested to not permit values to be assigned into this registry which conflict with values assigned in the CAtypes registry or to permit values to be assigned into the CAtypes registry which conflict with values assigned to to this registry unless the IANA considerations section for the new value explicitly overrides this prohibition, and the document defining the value describes how conflicting TLV codes will be interpreted by implementations

The values defined are:

   +--------+----------------------------------------+-----------+
   | RLtype | description                            | Reference |
   +--------+-------+--------------------------------+-----------+
   | 115    | relative location angle                | this RFC  |
   | 116    | relative location shape 2D point       | this RFC  |
   | 117    | relative location shape 3D point       | this RFC  |
   | 118    | relative location shape circlular      | this RFC  |
   | 119    | relative location shape spherical      | this RFC  |
   | 120    | relative location shape elliptical     | this RFC  |
   | 121    | relative location shape ellipsoid      | this RFC  |
   | 122    | relative location shape arc-band       | this RFC  |
   | 123    | relative location map URI              | this RFC  |
   | 124    | relative location map coordinates      | this RFC  |
   | 125    | relative location map angle            | this RFC  |
   | 126    | relative location map scale            | this RFC  |
   +--------+-------+--------------------------------+-----------+

12.2.  URN Sub-Namespace Registration for urn:ietf:params:xml:ns:pidf:????

This document registers a new XML namespace, as per the guidelines in [?].

     --- TBD ---

13.  Acknowledgements

This is the product of a design team on relative location. Besides the authors, this team included: Marc Linsner, James Polk, and James Winterbottom.

14.  References

14.1. Normative References

14.2. Informative References

Authors' Addresses