Geospatial Data Types - .NET SDK

GeoPoint

A GeoPoint defines a specific location on the Earth's surface. All of the geospatial data types use GeoPoints to define their location.

GeoCircle

A GeoCircle defines a circle on the Earth's surface. You define a GeoCircle by providing a GeoPoint for the center of the circle and a Distance object to specify the radius of the circle.

The following code shows two examples of creating a circle:

var circle1 = new GeoCircle((47.8, -122.6),
    Distance.FromKilometers(44.4));
var circle2 = new GeoCircle(
    new GeoPoint(latitude: 47.3, longitude: -121.9),
    Distance.FromDegrees(0.25));

click to enlarge

GeoBox

A GeoBox defines a rectangle on the Earth's surface. You define the rectangle by specifying the bottom left (southwest) corner and the top right (northeast) corner. The following example creates 2 boxes:

var box1 = new GeoBox(bottomLeftCorner: (47.3, -122.7),
    topRightCorner: (48.1, -122.1));
var box2 = new GeoBox(new GeoPoint(47.5, -122.4),
   new GeoPoint(47.9, -121.8));

click to enlarge

GeoPolygon

A GeoPolygon defines a polygon on the Earth's surface. Because a polygon is a closed shape, you must provide a minimum of 4 points: 3 points to define the polygon's shape, and a fourth to close the shape.

You can also exclude areas within a polygon by defining one or more "holes". A hole is another polygon whose bounds fit completely within the outer polygon. The following example creates 3 polygons: one is a basic polygon with 5 points, one is the same polygon with a single hole, and the third is the same polygon with two holes:

var basicPolygon = new GeoPolygon((48, -122.8),
    (48.2, -121.8), (47.6, -121.6), (47.0, -122.0),
    (47.2, -122.6), (48, -122.8));
// Create a polygon with a single hole
var outerRing = new GeoPoint[] {
    (48, -122.8), (48.2, -121.8),
    (47.6, -121.6), (47.0, -122.0), (47.2, -122.6),
    (48, -122.8) };
var hole1 = new GeoPoint[] {
    (47.8, -122.6), (47.7, -122.2),
    (47.4, -122.6), (47.6, -122.5),
    (47.8, -122.6) };
var polygonWithOneHole = new GeoPolygon(outerRing, hole1);
// Add a second hole to the polygon
var hole2 = new GeoPoint[] {
    (47.55, -122.05), (47.5, -121.9),(47.3, -122.1),
    (47.55, -122.05) };
var polygonWithTwoHoles =
    new GeoPolygon(outerRing, hole1, hole2);

click to enlarge

Creating a GeoJSON-Compatible Class

To create a class that conforms to the GeoJSON spec, you:

1. Create an embedded realm object (a class that inherits from IEmbeddedObject).

2. At a minimum, add the two fields required by the GeoJSON spec:

   • A field of type IList<double> that maps to a "coordinates" (case sensitive) property in the realm schema.

   • A field of type string that maps to a "type" property. The value of this field must be "Point".

The following example shows an embedded class named "CustomGeoPoint" that is used to persist GeoPoint data:

public partial class CustomGeoPoint : IEmbeddedObject
{
    [MapTo("coordinates")]
    public IList<double> Coordinates { get; } = null!;
    [MapTo("type")]
    private string Type { get; set; } = "Point";
    public CustomGeoPoint(double latitude, double longitude)
    {
        Coordinates.Add(longitude);
        Coordinates.Add(latitude);
    }
}

Using the Embedded Class

You then use the custom GeoPoint class in your realm model, as shown in the following example:

public partial class Company : IRealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public Guid Id { get; private set; } = Guid.NewGuid();
    public CustomGeoPoint? Location { get; set; }
    public Company() { }
}

You then add instances of your class to realm just like any other Realm model:

realm.WriteAsync(() =>
{
    realm.Add(new Company
    {
        Location = new CustomGeoPoint(47.68, -122.35)
    });
    realm.Add(new Company
    {
        Location = new CustomGeoPoint(47.9, -121.85)
    });
});

The following image shows the results of creating these two company objects.

click to enlarge