Shapefile Class

The reader reads every shape type. The Z values become the altitudes and the M values the GeoPosition.Measure of the positions, a value below -1038 (no data) or NaN becoming no measure; the M values of the Z shapes are optional. A PolyLine of one part is a GeoLineString, and of several parts a GeoMultiLineString; a MultiPoint is always a GeoMultiPoint. The rings of a Polygon are grouped as the shapefile orients them: each clockwise ring is an exterior ring, and each counterclockwise ring is a hole of the smallest exterior ring that contains it, or a polygon when no exterior ring contains it; when no ring is clockwise, a ring is a hole when it is inside an odd number of rings. The positions are kept in the order of the file, so the exterior rings are clockwise. A MultiPatch becomes polygons, as GDAL reads it: one per triangle of its strips and fans, and one per outer or first ring, with the inner rings and the rings that follow it as its holes. A null shape, a shape without positions and a point of NaN coordinates give a feature without geometry. The .shx file is not read.

The coordinate reference system of the .prj file, read by CoordinateReferenceSystem.ParseWkt, is the GeoFeatureCollection.CoordinateReferenceSystem of the features; it is null without a .prj file, or when the file is not valid or declares a projection that is not supported. The coordinates are those of the file: set ShapefileReaderOptions.TransformToWgs84 to convert them to longitudes and latitudes.

The features are the records of the .dbf file, as GDAL reads them: a record marked as deleted is skipped with its shape, a record without shape has no geometry, and the shapes after the last record are ignored. Without a .dbf file, the features are the shapes, without properties. The property values are a String for a character field (without its trailing spaces), a Double for a numeric field (N or F), a Boolean for a logical field, a DateOnly for a date field, and the text of the field for the other types, such as the block number of a memo field. A blank value, an empty text, a number of asterisks, a ? logical value and an invalid date are null. When two fields have the same name, the second one is named name_1. The features have no identifier.

The text of the .dbf file is decoded with ShapefileReaderOptions.Encoding, else the code page of the .cpg file (such as UTF-8, ISO-8859-1 or 1252), else the language driver ID of the .dbf header. UTF-8, ISO-8859-1 and Windows-1252 are always available; the other code pages (such as 437, 850 or 1251) are used when the application registered a provider, such as CodePagesEncodingProvider. When no encoding is declared, or the declared one is not available, each value is decoded as UTF-8 when it is valid UTF-8, else as ISO-8859-1.

The writer writes the .shp, .shx, .dbf, .cpg (UTF-8) and .prj (WGS 84 longitudes and latitudes) files. A shapefile has one shape type: Point for GeoPoint features, MultiPoint when a feature is a GeoMultiPoint, PolyLine for lines and Polygon for polygons, with Z (PointZ, MultiPointZ, PolyLineZ, PolygonZ) when a position has an altitude, the positions without altitude getting 0. The M values are written when a position has a measure, in the Z shapes or in the M shapes (PointM, MultiPointM, PolyLineM, PolygonM) when no position has an altitude; the positions without measure get the no-data value. The times are not written. Features that mix points, lines and polygons, or that have a GeoGeometryCollection, throw an ArgumentException. A feature without geometry, or with an empty geometry, is a null shape. The exterior rings are written clockwise and the holes counterclockwise, closed.

The fields are the union of the property names, in the order they are first seen. The names are cut to 10 bytes of UTF-8, and a name equal to a previous one, ignoring the case, gets a suffix: name_1, name_2... as GDAL does. A field gets its type from its non-null values: a string is a character field as wide as the longest value, up to 254 bytes (a longer value is cut, between two characters); integers, and whole numbers below 1015, are an N field without decimals; other numbers are an N field of width 24 and 15 decimals, as GDAL writes them, holding the shortest text that gives the number back; a Boolean is a logical field; a DateOnly, a DateTime or a DateTimeOffset is a date field, without the time of day. A field whose values have different types, or have another type, is a character field of their text. A null or non-finite number is written as a null value. When no feature has a property, the file gets an FID field with the index of the feature, as GDAL does. The identifiers of the features are not written.