RFC 5491
GEOPRIV Presence Information Data Format Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations
RFC 5491: GEOPRIV Presence Information Data Format Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations 🦋
Okay bestie, this is RFC 5491 💅 It's a Standards Track doc from the Network Working Group, published in March 2009. The authors are J. Winterbottom and M. Thomson from Andrew Corporation, plus H. Tschofenig from Nokia Siemens Networks 🌸 It updates RFC 4119, and the header doesn't list anything it obsoletes, so nothing gets retired here 💜
Status of This Memo ✨
This doc specifies an Internet standards track protocol for the Internet community, and it's literally asking people for discussion and suggestions for improvements 🫶 If you want the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌈
Copyright Notice 📜
Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved.
This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, as they stand on the date this document was published (http://trustee.ietf.org/license-info). Read those carefully, because they spell out your rights and restrictions for this document 🎀
Abstract 🧚
PIDF-LO is a super flexible, versatile way to represent location information. Sometimes, though, the info needs to be constrained so that fewer options have to be implemented. There's growing interest in using the location info inside a PIDF-LO for routing apps, and for apps to interoperate smoothly, the location info needs to be normative and way more tightly constrained than RFC 4119 (PIDF-LO) currently says 🔥 This document gives recommendations on how to constrain, represent, and interpret locations in a PIDF-LO. It also picks out a subset of Geography Markup Language (GML) 3.1.1 that applications involved in location-based routing are mandatory to implement 💖
Table of Contents 💜
1. Introduction ....................................................3
2. Terminology .....................................................3
3. Using Location Information ......................................4
3.1. Single Civic Location Information ..........................7
3.2. Civic and Geospatial Location Information ..................7
3.3. Manual/Automatic Configuration of Location Information .....8
3.4. Multiple Location Objects in a Single PIDF-LO ..............9
4. Geodetic Coordinate Representation .............................10
5. Geodetic Shape Representation ..................................10
5.1. Polygon Restrictions ......................................12
5.2. Shape Examples ............................................13
5.2.1. Point ..............................................13
5.2.2. Polygon ............................................14
5.2.3. Circle .............................................17
5.2.4. Ellipse ............................................17
5.2.5. Arc Band ...........................................19
5.2.6. Sphere .............................................21
5.2.7. Ellipsoid ..........................................22
5.2.8. Prism ..............................................24
6. Security Considerations ........................................26
7. Acknowledgments ................................................26
8. References .....................................................26
8.1. Normative References ......................................26
8.2. Informative References ....................................271. Introduction 🧚
Okay so PIDF-LO [RFC4119] is the recommended way to encode location information and its associated privacy policies 💅 Location info in a PIDF-LO can be described geospatially, based on a subset of Geography Markup Language (GML) 3.1.1 [OGC-GML3.1.1], or as civic location information [RFC5139]. A GML profile for expressing geodetic shapes in a PIDF-LO is described in [GeoShape]. PIDF-LO is envisioned for tons of location-based apps, and this document makes recommendations for formats and conventions so interoperability is less of a headache 🌸
The PIDF-LO is a general presence format for representing location info, and it lets you specify location info about a whole range of aspects of a Target 🦋 The general presence data model is described in [RFC4479], and it's built for a presence document that describes different aspects of a presentity's reachability. Continuing that approach, one presence document can hold several GEOPRIV objects, each specifying different locations and aspects of reachability for a presentity. This flexibility matters, so the recommendations here make no attempt to forbid using a PIDF-LO this way 👑 This document only gives a specific set of guidelines for building presence documents when it's important to unambiguously convey exactly one location 💖
2. Terminology 💖
The big capital-letter words are the ones that really matter 🔥 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be read as described in [RFC2119].
The definition for "Target" is taken from [RFC3693] 🎀
In this document, a "discrete location" is a place, point, area, or volume where a Target can be found 🌈
The term "compound location" describes location info that's a composite of both civic and geodetic information 💜 An example would be a geodetic polygon outlining the perimeter of a building, plus a civic element showing which floor of the building it is 🏢
The term "method" in this document refers to the mechanism used to work out where a Target is 🧚 It can be something run by a location information server (LIS) or by the Target itself. It specifically does not mean the location configuration protocol (LCP) used to deliver location info to either the Target or the Recipient 🫶
The term "source" refers to the LIS, node, or device that a Recipient (Target or Third-Party) gets location info from ✨
3. Using Location Information ✨
okay so a PIDF document can hold an unbounded number of <tuple>, <device>, and <person> elements 🫧 Each one holds a single <status> element, and that <status> can hold more than one <geopriv> element as a child. Every <geopriv> has to contain at least two children: <location-info> and <usage-rules>. The actual location elements live inside <location-info> 📍
So a single PIDF document can contain any number of location objects, and some of them might contradict each other while others add to each other 🌀 Here's the structure in a picture, bestie 🦋
<presence>
<tuple> -- #1
<status>
<geopriv> -- #1
<location-info>
location element #1
location element #2
...
location element #n
<usage-rules>
</geopriv>
<geopriv> -- #2
<geopriv> -- #3
...
<geopriv> -- #m
</status>
</tuple>
<device>
<geopriv> -- #1
<location-info>
location element(s)
<usage-rules>
</geopriv>
<geopriv> -- #2
...
<geopriv> -- #m
</device>
<person>
<geopriv> -- #1
<location-info>
location element(s)
<usage-rules>
</geopriv>
<geopriv> -- #2
...
<geopriv> -- #m
</person>
<tuple> -- #2
<device> -- #2
<person> -- #2
...
<tuple> -- #o
</presence>Figure 1: Structure of a PIDF-LO Document
ngl all of these possible sources and storage spots make things super confusing for the people who create, pass along, and read location info 😭 The United States National Emergency Number Association (NENA) went through this mess in real life and came up with a set of conventions to fix it 💅 These rules have no particular order, but creators and consumers of location info in a PIDF-LO should still follow them so everyone reads the data the same way 🫶
- Rule #1: A <geopriv> element MUST describe a discrete location. 🎯
- Rule #2: Where a discrete location can be uniquely described in more than one way, each location description SHOULD reside in a separate <tuple>, <device>, or <person> element; only one geopriv element per tuple. 🌸
- Rule #3: Providing more than one <geopriv> element in a single presence document (PIDF) MUST only be done if the locations refer to the same place or are put into different element types. For example, one location in a <tuple>, a second location in a <device> element, and a third location in a <person> element.
- This may occur if a Target's location is determined using a series of different techniques or if the Target wishes to represent her location as well as the location of her PC. In general, avoid putting more than one location into a document unless it makes sense to do so. 💭
- Rule #4: Providing more than one location chunk in a single <location-info> element SHOULD be avoided where possible. Rule #5 and Rule #6 provide further refinement. 🧚
- Rule #5: When providing more than one location chunk in a single <location-info> element, the locations MUST be provided by a common source at the same time and by the same location determination method. ⏰
- Rule #6: Providing more than one location chunk in a single <location-info> element SHOULD only be used for representing compound location referring to the same place.
- For example, a geodetic location describing a point, and a civic location indicating the floor in a building. 🏢
- Rule #7: Where the compound location is provided in a single <location-info> element, the coarse location information MUST be provided first.
- For example, a geodetic location describing an area and a civic location indicating the floor should be represented with the area first followed by the civic location. 🗺️
- Rule #8: Where a PIDF document contains more than one <geopriv> element, the priority of interpretation is given to the first <device> element in the document containing a location. If no <device> element containing a location is present in the document, then priority is given to the first <tuple> element containing a location. Locations contained in <person> tuples SHOULD only be used as a last resort. 👑
- Rule #9: Where multiple PIDF documents can be sent or received together, say in a multi-part MIME body, and current location information is required by the recipient, then document selection SHOULD be based on document order, with the first document considered first. 📑
The examples below show these rules in action 🌈
3.1. Single Civic Location Information
Jane is chilling at a coffee shop on the ground floor of a huge shopping mall ☕ She opens her laptop and connects to the coffee shop's WiFi hotspot. Jane gets a complete civic address for where she is right now, for example through the DHCP civic mechanism defined in [RFC4776] 📮 A Location Object is built from one PIDF document with a single <tuple> or <device> element, a single <status> element, a single <geopriv> element, and a single location chunk sitting in the <location-info> element. This document is unambiguous, and receiving nodes should interpret it consistently if it gets sent over the network ✨
3.2. Civic and Geospatial Location Information
Mike is visiting his Seattle office and plugs his laptop into the Ethernet port in a spare cube 💻 In this case the location info is a geodetic location, with the altitude written as a building floor number. Mike's main location is the point given by the geodetic coordinates. He's also on the second floor of the building at those coordinates, so he's giving us a double whammy 🫠 Applying rules #6 and #7, the resulting compound location information looks like Figure 2.
<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:gml="http://www.opengis.net/gml"
xmlns:cl="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
entity="pres:mike@seattle.example.com">
<dm:device id="mikepc">
<gp:geopriv>
<gp:location-info>
<gml:Point srsName="urn:ogc:def:crs:EPSG::4326">
<gml:pos>-43.5723 153.21760</gml:pos>
</gml:Point>
<cl:civicAddress>
<cl:FLR>2</cl:FLR>
</cl:civicAddress>
</gp:location-info>
<gp:usage-rules/>
<gp:method>Wiremap</gp:method>
</gp:geopriv>
<dm:deviceID>mac:8asd7d7d70cf</dm:deviceID>
<dm:timestamp>2007-06-22T20:57:29Z</dm:timestamp>
</dm:device>
</presence>Figure 2: PIDF-LO Containing a Compound Location
3.3. Manual/Automatic Configuration of Location Information
Loraine has a predefined civic location saved on her laptop, since she normally lives in Sydney, so the address is for her Sydney apartment 🦘 Then she decides to visit sunny San Francisco 🌞 When she gets there she plugs in her laptop and makes a call. Her laptop gets a new location from the visited network in San Francisco. This system can't be sure that the old location and the new one describe the same place, so Loraine's computer makes a brand new PIDF-LO to represent where she is 💅 If her computer were to tack the new location onto her existing PIDF location document (breaking rule #3), the correct info could still be read by the Location Recipient, as long as it applies rule #9. In that case the San Francisco location should come first in the PIDF document, followed by Sydney. Since the info comes from different sources, rule #8 should also apply, and each location should go in a different tuple, with the San Francisco tuple first 🧳
3.4. Multiple Location Objects in a Single PIDF-LO
Vanessa has her PC with her at the park, but because of a misconfiguration, her PC reports her location as being in the office 🙈 The resulting PIDF-LO has a <device> element showing that Vanessa's PC is at the park, and a <person> element saying that Vanessa is in her office 🌳🏢
<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:RDBR>Campbell Street</ca:RDBR>
<ca:LMK>
Gilligan's Island
</ca:LMK> <ca:LOC>Corner</ca:LOC>
<ca:NAM> Video Rental Store </ca:NAM>
<ca:PC>2500</ca:PC>
<ca:ROOM> Westerns and Classics </ca:ROOM>
<ca:PLC>store</ca:PLC>
<ca:POBOX>Private Box 15</ca:POBOX>
</ca:civicAddress>
</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>
<dm:person id="ness">
<gp:geopriv>
<gp:location-info>
<gs:Circle srsName="urn:ogc:def:crs:EPSG::4326">
<gml:pos>-34.410649 150.87651</gml:pos>
<gs:radius uom="urn:ogc:def:uom:EPSG::9001">
30
</gs:radius>
</gs:Circle>
</gp:location-info>
<gp:usage-rules/>
<gp:method>Manual</gp:method>
</gp:geopriv>
<dm:timestamp>2007-06-24T12:28:04Z</dm:timestamp>
</dm:person>
</presence>Figure 3: PIDF-LO Containing Multiple Location Objects
4. Geodetic Coordinate Representation 🌍
The geodetic examples in RFC 4119 [RFC4119] are drawn using the <gml:location> element, which uses the <gml:coordinates> element inside the <gml:Point> element. That approach has a few drawbacks, though 🙃 First, it was deprecated in later versions of GML (3.1 and beyond), so it's not a good idea for new applications. Second, the coordinates type is opaque, which makes it hard to parse and interpret consistently, since the same geodetic location can be written in lots of different ways. The PIDF-LO Geodetic Shapes specification [GeoShape] gives a specific GML profile for expressing commonly used shapes with simple GML representations 💖 The shapes defined in [GeoShape] are the recommended shapes for ensuring interoperability 🫶
5. Geodetic Shape Representation 🗺️✨
Okay bestie, the cellular world is obsessed with geodetic location info right now, for emergency calls and location-based apps alike 📱💖 Usually a location is a point (2D or 3D) plus an area or volume of uncertainty around it. In theory, that area is where the user is most likely to be, and the point is just the centroid. In practice, most systems treat the point as an absolute value and ignore the uncertainty 🙈 Nobody can tell if that's for simplicity, and it's even harder to predict whether uncertainty will matter more later. So an important decision is whether an uncertainty area should be specified at all 🤔
The PIDF-LO Geodetic Shapes specification [GeoShape] defines eight shape types. Most of them translate easily into shape definitions used in other applications and protocols, like the Open Mobile Alliance (OMA) Mobile Location Protocol (MLP) 🦋 For completeness, here are the shapes from [GeoShape]:
- Point (2d and 3d)
- Polygon (2d)
- Circle (2d)
- Ellipse (2d)
- Arc band (2d)
- Sphere (3d)
- Ellipsoid (3d)
- Prism (3d)
The above-listed shapes MUST be implemented. 🔥
The GeoShape specification [GeoShape] also describes a standard set of coordinate reference systems (CRS), units of measure (UoM), and conventions for lines and distances 📏 The world geodetic system 1984 (WGS84) [WGS84] coordinate reference system is the one to use, and the European petroleum survey group (EPSG) code 4326 is mandated for two-dimensional (2d) shapes. You know it by its URN, urn:ogc:def:crs:EPSG::4326, [CRS-URN]. For three-dimensional (3d) volumes, EPSG 4979 is the one, identified by urn:ogc:def:crs:EPSG::4979. Distances and heights are in meters, using EPSG 9001, identified by urn:ogc:def:uom:EPSG::9001. Angular measures MUST use either degrees or radians. Degrees MUST be identified by urn:ogc:def:uom:EPSG::9102, and radians MUST be identified by urn:ogc:def:uom:EPSG::9101. Bearings are measured clockwise from Northing, as defined by the WGS84 CRS, not magnetic north 🧭
Implementations MUST specify the CRS using the srsName attribute on the outermost geometry element. The CRS MUST NOT be respecified or changed for any sub-elements. The srsDimension attribute SHOULD be omitted, since the number of dimensions in these CRSs is already known 💅 A CRS MUST be specified using the above URN notation only. Implementations do not need to support user-defined CRSs, so no custom CRS drama 🙅♀️
Numerical values for coordinates and measures use the lexical representation for "double" defined in [W3C.REC-xmlschema-2-20041028]. Leading zeros and trailing zeros past the decimal point are not significant. For example, "03.07500" is equivalent to "3.075" ✨
It is RECOMMENDED that uncertainty is expressed at a confidence of 95% or higher. Specifying a convention for confidence is what makes uncertainty values actually useful 🎀
5.1. Polygon Restrictions
Okay, so the polygon shape type in [GeoShape] has no limit on how many vertices it can have. That means you can define some seriously complicated shapes and send them in a PIDF-LO 🌀 But if the location info is going to be used in real-time processing, like location-dependent routing, shapes with tens or even hundreds of points could cause real performance hits 😭 To keep that under control, Polygon shapes SHOULD be restricted to a maximum of 15 points (16 including the repeated point) when the location information is intended for real-time applications. The 15-point limit is a sweet spot: complex enough to be useful, and it lets you interoperate with other location transport protocols like the 3rd Generation Partnership Project (3GPP) (see [3GPP.23.032]) and OMA, where a 15-point limit is already imposed 🧚
The edges of a polygon are defined by the shortest path between two points in space, not a geodesic curve. Two-dimensional points MAY be interpreted as having a zero value for their altitude component. To avoid big errors from possible geodesic interpolation, the length between adjacent vertices SHOULD be restricted to a maximum of 130 km. More info on this restriction is in [GeoShape] 🌸
A connecting line SHALL NOT cross another connecting line of the same Polygon. No crossing lines, periodt 🚫
Polygons MUST be defined with the upward normal pointing up. This is done by defining the vertices in a counter-clockwise direction 🔄
Points specified in a polygon using three-dimensional coordinates MUST all have the same altitude. 🦋
5.2. Shape Examples
This section shows some examples of where the more complex shapes are used, how they're determined, and how they're represented in a PIDF-LO 💜 Complete details on all of the GeoShape types are in [GeoShape].
5.2.1. Point
The point shape type is the simplest form of geodetic location information (LI), and it's natively supported by GML. The gml:Point element is used when there's no known uncertainty. A point also forms part of a bunch of other geometries. A point may be specified using either WGS 84 (latitude, longitude) or WGS 84 (latitude, longitude, altitude). Figure 4 shows a 2d point 📍
<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: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>
</presence>Figure 4: PIDF-LO Containing a Two-Dimensional Point
Figure 5 shows a 3d point 🌈
<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:gml="http://www.opengis.net/gml"
entity="pres:point3d@example.com">
<dm:device id="point3d">
<gp:geopriv>
<gp:location-info>
<gml:Point srsName="urn:ogc:def:crs:EPSG::4979"
xmlns:gml="http://www.opengis.net/gml">
<gml:pos>-34.407 150.883 24.8</gml:pos>
</gml:Point>
</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>
</presence>Figure 5: PIDF-LO Containing a Three-Dimensional Point
5.2.2. Polygon
The polygon shape type may be used to represent a building outline or a coverage area 🏢 The first and last points of the polygon have to be the same. Take the hexagon in Figure 6, with vertices A, B, C, D, E, and F. The resulting polygon is defined with 7 points, with the first and last points both having the coordinates of point A 🔷
F--------------E
/ \
/ \
/ \
A D
\ /
\ /
\ /
B--------------CFigure 6: Example of a Polygon
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
xmlns:gml="http://www.opengis.net/gml"
entity="pres:hexagon@example.com">
<tuple id="polygon-pos">
<status>
<gp:geopriv>
<gp:location-info>
<gml:Polygon srsName="urn:ogc:def:crs:EPSG::4326">
<gml:exterior>
<gml:LinearRing>
<gml:pos>43.311 -73.422</gml:pos> <!--A-->
<gml:pos>43.111 -73.322</gml:pos> <!--F-->
<gml:pos>43.111 -73.222</gml:pos> <!--E-->
<gml:pos>43.311 -73.122</gml:pos> <!--D-->
<gml:pos>43.411 -73.222</gml:pos> <!--C-->
<gml:pos>43.411 -73.322</gml:pos> <!--B-->
<gml:pos>43.311 -73.422</gml:pos> <!--A-->
</gml:LinearRing>
</gml:exterior>
</gml:Polygon>
</gp:location-info>
<gp:usage-rules/>
<gp:method>Wiremap</gp:method>
</gp:geopriv>
</status>
<timestamp>2007-06-22T20:57:29Z</timestamp>
</tuple>
</presence>Figure 7: PIDF-LO Containing a Polygon
In addition to the form in Figure 7, GML supports a posList, which is a more compact way to represent the coordinates of the Polygon vertices than the discrete pos elements. The compact form is shown in Figure 8. Both forms are permitted 💅
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
xmlns:gml="http://www.opengis.net/gml"
entity="pres:hexagon@example.com">
<tuple id="polygon-poslist">
<status>
<gp:geopriv>
<gp:location-info>
<gml:Polygon srsName="urn:ogc:def:crs:EPSG::4326">
<gml:exterior>
<gml:LinearRing>
<gml:posList>
43.311 -73.422 43.111 -73.322
43.111 -73.222 43.311 -73.122
43.411 -73.222 43.411 -73.322
43.311 -73.422
</gml:posList>
</gml:LinearRing>
</gml:exterior>
</gml:Polygon>
</gp:location-info>
<gp:usage-rules/>
<gp:method>Wiremap</gp:method>
</gp:geopriv>
</status>
<timestamp>2007-06-22T20:57:29Z</timestamp>
</tuple>
</presence>Figure 8: Compact Form of a Polygon Expressed in a PIDF-LO
5.2.3. Circle 🎀
okay so the circle is how we talk about uncertainty around a point in two-dimensional CRSs 🫶 it's based on the one-dimensional geometry in GML, gml:CircleByCenterPoint. the center point gets specified with a two-dimensional CRS, but in three dimensions the orientation of the circle can't be specified correctly with this representation 💀 so if you've got a point with uncertainty in 3D, you should use the sphere shape type instead 🌈
<presence xmlns="urn:ietf:params:xml:ns:pidf" xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10" xmlns:gml="http://www.opengis.net/gml" xmlns:gs="http://www.opengis.net/pidflo/1.0" entity="pres:circle@example.com"> <tuple id="circle"> <status> <gp:geopriv> <gp:location-info> <gs:Circle srsName="urn:ogc:def:crs:EPSG::4326"> <gml:pos>42.5463 -73.2512</gml:pos> <gs:radius uom="urn:ogc:def:uom:EPSG::9001"> 850.24 </gs:radius> </gs:Circle> </gp:location-info> <gp:usage-rules/> <gp:method>OTDOA</gp:method> </gp:geopriv> </status> </tuple> </presence>
Figure 9: PIDF-LO Containing a Circle
5.2.4. Ellipse 🦋
an ellipse is an elliptical area in two-dimensional space 🌸 it's described by a center point, the lengths of its semi-major and semi-minor axes, and the orientation of the semi-major axis. just like the circle, the ellipse MUST be specified using the two-dimensional CRS, no exceptions bestie 💅
<presence xmlns="urn:ietf:params:xml:ns:pidf" xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10" xmlns:gml="http://www.opengis.net/gml" xmlns:gs="http://www.opengis.net/pidflo/1.0" entity="pres:Ellipse@somecell.example.com"> <tuple id="ellipse"> <status> <gp:geopriv> <gp:location-info> <gs:Ellipse srsName="urn:ogc:def:crs:EPSG::4326"> <gml:pos>42.5463 -73.2512</gml:pos> <gs:semiMajorAxis uom="urn:ogc:def:uom:EPSG::9001"> 1275 </gs:semiMajorAxis> <gs:semiMinorAxis uom="urn:ogc:def:uom:EPSG::9001"> 670 </gs:semiMinorAxis> <gs:orientation uom="urn:ogc:def:uom:EPSG::9102"> 43.2 </gs:orientation> </gs:Ellipse> </gp:location-info> <gp:usage-rules/> <gp:method>Device-Assisted_A-GPS</gp:method> </gp:geopriv> </status> <timestamp>2007-06-22T20:57:29Z</timestamp> </tuple> </presence>
Figure 10: PIDF-LO Containing an Ellipse
so the breakdown is giving 🧚 gml:pos is where the center (or origin) of the ellipse sits. gs:semiMajorAxis and gs:semiMinorAxis are the lengths of the semi-major and semi-minor axes. and gs:orientation is the angle the semi-major axis gets rotated from the first axis of the CRS towards the second axis. for WGS 84, the orientation shows rotation from Northing to Easting, which (if it's in degrees) is roughly the same as a compass bearing, if magnetic north were the same as the WGS north pole 🧭
Note: An ellipse with equal major and minor axis lengths is a circle.
5.2.5. Arc Band 🌙
the arc band shape is super common in wireless systems where timing advance or code offset sequences get used to make up for the distance between handsets and the access point 📡 it's drawn as two radii coming out of a central point, plus two angles for the starting angle and the opening angle of the arc. in a cellular setup, the central point is nominally the cell tower location, the two radii come from the extent of the timing advance, and the two angles are generally provisioned info 🍓
okay, the example is 🥹 Paul is on a cellular wireless device, 7 timing advance symbols away from the cell tower. on a GSM-based network, that puts Paul roughly between 3,594 meters and 4,148 meters from the tower, which gives us the inner and outer radius values. if the start angle is 20 degrees from north and the opening angle is 120 degrees, Paul's arc band looks like Figure 11 💖
N ^ ,.__
| a(s) / `-. |
|---|
| 20 / `-. |
| --. / `. |
| `/ \ |
| /__ \ |
| . `-. \ |
| . `. \ |
| . \ \ . |
---c-- a(o) -- | | -->
| . / 120 ' | E |
|---|---|
| . / ' | |
| . / ; |
.,' / r(i). / (3594m) . / . ,' . ,' r(o)`' (4148m)
Figure 11: Example of an Arc Band
and the resulting PIDF-LO is Figure 12 ✨
<presence xmlns="urn:ietf:params:xml:ns:pidf" xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10" xmlns:gml="http://www.opengis.net/gml" xmlns:gs="http://www.opengis.net/pidflo/1.0" entity="pres:paul@somecell.example.com"> <tuple id="arcband"> <status> <gp:geopriv> <gp:location-info> <gs:ArcBand srsName="urn:ogc:def:crs:EPSG::4326"> <gml:pos>-43.5723 153.21760</gml:pos> <gs:innerRadius uom="urn:ogc:def:uom:EPSG::9001"> 3594 </gs:innerRadius> <gs:outerRadius uom="urn:ogc:def:uom:EPSG::9001"> 4148 </gs:outerRadius> <gs:startAngle uom="urn:ogc:def:uom:EPSG::9102"> 20 </gs:startAngle> <gs:openingAngle uom="urn:ogc:def:uom:EPSG::9102"> 20 </gs:openingAngle> </gs:ArcBand> </gp:location-info> <gp:usage-rules/> <gp:method>TA-NMR</gp:method> </gp:geopriv> </status> <timestamp>2007-06-22T20:57:29Z</timestamp> </tuple> </presence>
Figure 12: PIDF-LO Containing an Arc Band
one important thing about the arc band 🚨 the center point used to define the shape is not part of the enclosed area, and Target can be anywhere inside the defined arc band area 🫧
5.2.6. Sphere 🫧
the sphere is a volume that gives you the same info as a circle, but in three dimensions 🌐 it has to be specified using a three-dimensional CRS. Figure 13 shows the sphere shape, which is basically the circle example with one extra thing: an altitude in the provided coordinates 🏔️
<presence xmlns="urn:ietf:params:xml:ns:pidf" xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10" xmlns:gml="http://www.opengis.net/gml" xmlns:gs="http://www.opengis.net/pidflo/1.0" entity="pres:sphere@example.com"> <tuple id="sphere"> <status> <gp:geopriv> <gp:location-info> <gs:Sphere srsName="urn:ogc:def:crs:EPSG::4979"> <gml:pos>42.5463 -73.2512 26.3</gml:pos> <gs:radius uom="urn:ogc:def:uom:EPSG::9001"> 850.24 </gs:radius> </gs:Sphere> </gp:location-info> <gp:usage-rules/> <gp:method>Device-Based_A-GPS</gp:method> </gp:geopriv> </status> </tuple> </presence>
Figure 13: PIDF-LO Containing a Sphere
5.2.7. Ellipsoid 🌈
the ellipsoid is the volume GPS systems produce most often 🛰️ it's used a lot in navigation systems and wireless location networks, so it's kind of everywhere. it's built around a central point given in three dimensions, and three mutually perpendicular axes stretch outward from that point. those are the semi-major (M) axis, the semi-minor (m) axis, and the vertical (v) axis, in that order. there's also an orientation angle, measured in degrees from north, showing which way the semi-major axis points from the center point 🧭✨
\ _.-""""^"""""-._ .' \ | `. / v m \
| \ | |
|---|---|
| -c ----M----> |
\ / ._ _.' -...........-'
Figure 14: Example of an Ellipsoid
and a PIDF-LO containing an ellipsoid looks like Figure 15 💜
<presence xmlns="urn:ietf:params:xml:ns:pidf" xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10" xmlns:gml="http://www.opengis.net/gml" xmlns:gs="http://www.opengis.net/pidflo/1.0" entity="pres:somone@gpsreceiver.example.com"> <tuple id="ellipsoid"> <status> <gp:geopriv> <gp:location-info> <gs:Ellipsoid srsName="urn:ogc:def:crs:EPSG::4979"> <gml:pos>42.5463 -73.2512 26.3</gml:pos> <gs:semiMajorAxis uom="urn:ogc:def:uom:EPSG::9001"> 7.7156 </gs:semiMajorAxis> <gs:semiMinorAxis uom="urn:ogc:def:uom:EPSG::9001"> 3.31 </gs:semiMinorAxis> <gs:verticalAxis uom="urn:ogc:def:uom:EPSG::9001"> 28.7 </gs:verticalAxis> <gs:orientation uom="urn:ogc:def:uom:EPSG::9102"> 90 </gs:orientation> </gs:Ellipsoid> </gp:location-info> <gp:usage-rules/> <gp:method>Hybrid_A-GPS</gp:method> </gp:geopriv> </status> <timestamp>2007-06-22T20:57:29Z</timestamp> </tuple> </presence>
Figure 15: PIDF-LO Containing an Ellipsoid
5.2.8. Prism 🧊✨
okay so a prism is literally the move when you need to describe a chunk of a building or a range of floors 🏢💅 it takes a polygon and extrudes it upward by giving it a height element. the base is a bunch of coplanar points in 3D, all sitting at the same altitude, and the prism is just that base stretched up to whatever the height element says 🫶 the height of the Prism MUST be a positive value, no negatives, bestie 🙅♀️ also the first and last points of the polygon have to be the same, so it closes the loop like a perfect little circle of coordinates 💜
here's the vibe with the cube in Figure 16 🧊🌈 if you extrude the prism from the bottom up, the base polygon is points A, B, C, D, A. the height is the distance from point A to point E, in meters 📏
G-----F
/| /|
/ | / |
H--+--E |
| C--|--B
| / | /
|/ |/
D-----A
Figure 16: Example of a Prismthe PIDF-LO comes out looking like Figure 17 🎀 it's giving very organized xml energy 🤓
<presence xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
xmlns:gml="http://www.opengis.net/gml"
xmlns:gs="http://www.opengis.net/pidflo/1.0"
entity="pres:mike@someprism.example.com">
<tuple id="prism">
<status>
<gp:geopriv>
<gp:location-info>
<gs:Prism srsName="urn:ogc:def:crs:EPSG::4979">
<gs:base>
<gml:Polygon>
<gml:exterior>
<gml:LinearRing>
<gml:posList>
42.556844 -73.248157 36.6 <!--A-->
42.656844 -73.248157 36.6 <!--B-->
42.656844 -73.348157 36.6 <!--C-->
42.556844 -73.348157 36.6 <!--D-->
42.556844 -73.248157 36.6 <!--A-->
</gml:posList>
</gml:LinearRing>
</gml:exterior>
</gml:Polygon>
</gs:base>
<gs:height uom="urn:ogc:def:uom:EPSG::9001">
2.4
</gs:height>
</gs:Prism>
</gp:location-info>
<gp:usage-rules/>
<gp:method>Wiremap</gp:method>
</gp:geopriv>
</status>
<timestamp>2007-06-22T20:57:29Z</timestamp>
</tuple>
</presence>
Figure 17: PIDF-LO Containing a Prism6. Security Considerations 🔐
okay this one is SERIOUS bestie 😭🔥 the primary security considerations are about how location information gets conveyed and used, and those are outside the scope of this document 🙈 this doc is only meant to be a set of guidelines for which elements MUST or SHOULD be implemented by systems that want to do location dependent routing 🗺️ and the ramification is that these recommendations extend to devices and clients that want to use those services too, so everybody in the chain has to pay attention 👀💀
7. Acknowledgments 🫶🌸
the authors want to give a huge shoutout to the GEOPRIV working group for their discussions around PIDF-LO 👑 especially Carl Reed, Ron Lake, James Polk, Henning Schulzrinne, Jerome Grenier, Roger Marshall and Robert Sparks 💖 they also want to thank Jon Peterson as the author of PIDF-LO, and Nadine Abbott for her constructive comments that helped clarify some parts of the document ✨
and thanks to Karen Navas for pointing out some omissions in the examples 🧚 she's literally the reason the examples are better 🙌
8. References 📚
8.1. Normative References 💅
[GeoShape] Thomson, M. and C. Reed, "GML 3.1.1 PIDF-LO Shape Application Schema for use by the Internet Engineering Task Force (IETF)", Candidate OpenGIS Implementation Specification 06-142r1, Version: 1.0, April 2007.
[OGC-GML3.1.1] Portele, C., Cox, S., Daisy, P., Lake, R., and A. Whiteside, "Geography Markup Language (GML) 3.1.1", OGC 03-105r1, July 2003.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4119] Peterson, J., "A Presence-based GEOPRIV Location Object Format", RFC 4119, December 2005.
[RFC4479] Rosenberg, J., "A Data Model for Presence", RFC 4479, July 2006.
[RFC5139] Thomson, M. and J. Winterbottom, "Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO)", RFC 5139, February 2008.
[W3C.REC-xmlschema-2-20041028] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, http://www.w3.org/TR/2004/REC-xmlschema-2-20041028.
8.2. Informative References 🦋
[3GPP.23.032] 3rd Generation Partnership Project, "Universal Geographical Area Description (GAD)", 3GPP TS 23.032 V6.0.0, January 2005, http://www.3gpp.org/ftp/Specs/html-info/23032.htm.
[CRS-URN] Whiteside, A., "GML 3.1.1 Common CRSs Profile", OGC 03-105r1, November 2005.
[RFC3693] Cuellar, J., Morris, J., Mulligan, D., Peterson, J., and J. Polk, "Geopriv Requirements", RFC 3693, February 2004.
[RFC4776] Schulzrinne, H., "Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information", RFC 4776, November 2006.
[WGS84] US National Imagery and Mapping Agency, "Department of Defense (DoD) World Geodetic System 1984 (WGS 84), Third Edition", NIMA TR8350.2, January 2000.
Authors' Addresses 🎀
James Winterbottom Andrew Corporation Wollongong NSW Australia
EMail: james.winterbottom@andrew.com
Martin Thomson Andrew Corporation Wollongong NSW Australia
EMail: martin.thomson@andrew.com
Hannes Tschofenig Nokia Siemens Networks Linnoitustie 6 Espoo 02600 Finland
Phone: +358 (50) 4871445 EMail: Hannes.Tschofenig@gmx.net URI: http://www.tschofenig.priv.at
that's the whole spec, bestie 💖 you made it through all five parts 🌈👑
📦 where this page comes from
- ietf: rfc5491 2009-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms