Shp

Namespace: Digi21.DigiNG.IO.Shp
Assembly: Digi21.DigiNG.IO.Shp

Drawing file in ESRI Shapefile format. A Shp represents a folder: each .shp file in the folder is a layer, with its .shx index, .dbf attribute table and .prj coordinate reference system.

public class Shp : IDrawingFile, IDisposable

Implements: IDrawingFile, which in turn implements IReadOnlyDrawingFile, IEnumerable<Entity> and IWindow3D.

The code table defines the relationship between Digi3D.AI codes and layers: each code's Shapefile format translation contains the name of the layer where it is stored. Writing entities therefore requires a code table with this translation.

How the format works in Digi3D.AI is described in ESRI Shapefiles.

Call Dispose (or use using) to close the layers.

Constructors

public Shp(string path)
public Shp(string path, CodePage codePage)
public Shp(string path, bool readOnly)
public Shp(string path, bool readOnly, CodePage codePage)
public Shp(string path, DelegateGetWkt GetWkt)
public Shp(string path, DelegateGetWkt GetWkt, CodePage codePage)
public Shp(string path, DelegateGetWkt GetWkt, bool readOnly)
public Shp(string path, DelegateGetWkt GetWkt, bool readOnly, CodePage codePage)
public Shp(string path, DigiTab digiTab)
public Shp(string path, DigiTab digiTab, CodePage codePage)
public Shp(string path, DigiTab digiTab, bool readOnly)
public Shp(string path, DigiTab digiTab, bool readOnly, CodePage codePage)
public Shp(string path, DigiTab digiTab, DelegateGetWkt GetWkt)
public Shp(string path, DigiTab digiTab, DelegateGetWkt GetWkt, CodePage codePage)
public Shp(string path, DigiTab digiTab, DelegateGetWkt GetWkt, bool readOnly)
public Shp(string path, DigiTab digiTab, DelegateGetWkt GetWkt, bool readOnly, CodePage codePage)
Parameter Description
path Path of a .shp file. The file's folder is the layers folder: the portion of the path before the last backslash (\) is used.
digiTab Code table relating codes to layers. Without this parameter, an empty code table is used: when reading, one code per layer is added to it; when writing, no entity has a code with a Shapefile format translation, so nothing is saved.
GetWkt DelegateGetWkt delegate returning the coordinate reference system's WKT. Called only if the folder has no layers.
readOnly true to open layers read-only. Defaults to false without this parameter.
codePage Text encoding of the .dbf tables created, also written to a .cpg file. When reading, used only if the .dbf does not specify its encoding and there is no .cpg file. Defaults to CodePage.UTF_8 without this parameter.

On opening, all layers in the folder with a .shx file are loaded. This class's overloads do not display the layer selection dialog box.

Coordinates are stored without rounding (the format's Precision decimals parameter is 0).

The constructors throw Exception, with the error message, if opening the folder fails; for example, if several codes for the same layer have no condition in the code table.

Properties

Property Description
string Path Value of the constructor's path parameter.
bool CanRead true if layers can be read.
bool CanWrite false if layers were opened read-only.
string Wkt Coordinate reference system WKT: that of the first layer or, if the folder has no layers, the value returned by GetWkt. If the folder has no layers and there is no GetWkt delegate, the property throws an exception.
string ConnectionString Database connection string, or an empty string if there is no database.
IDictionary<string, int> DatabaseTables Database tables: table name and table number.
bool Visible File visibility in Digi3D.AI. Does not affect reading or writing.
double? Xmin, double Ymin, double Zmin, double Xmax, double Ymax, double Zmax Minimum and maximum layer coordinates, read from their headers. Xmin is null if Valid is false. The installed assembly also declares a set accessor on all six properties, which throws InvalidOperationException.
bool Valid true if minimum and maximum coordinates are valid.
double Width, double Height, double Depth Xmax - Xmin, Ymax - Ymin and Zmax - Zmin.
Point3D Center Center of the box defined by the minimum and maximum coordinates.
Point3D NW, N, NE, E, SE, S, SW, W Corners and side midpoints of that box in the X, Y plane. All eight points have Z equal to Zmin.

Methods

Method Description
IEnumerator<Entity> GetEnumerator() Returns the enumerator of all layers' entities, layer by layer. It can be requested only once per Shp: a second call throws InvalidOperationException. Entities are read-only, and their Owner property is this file.
void Add(Entity entity) Stores the entity in its code's layer and its code's attributes (Code.Attributes) in that layer's .dbf table. Creates the layer if it does not exist. Does nothing, without an exception or message, if the entity cannot be stored in that layer (for example, a point in a line layer) or its code is not in the code table.
void Add(IEnumerable<Entity> entities) Stores entities in enumeration order. Unlike Add(Entity), checks the read-only state, Owner and code count of all entities, and uses TaskAdded and ResultsAdded to report entities with attributes in their code (nonempty Code.Attributes) that cannot be stored in the layer corresponding to each entity's code.
ReadOnlyLine Add(Line line)
ReadOnlyPoint Add(Point point)
ReadOnlyText Add(Text text)
ReadOnlyPolygon Add(Polygon polygon)
ReadOnlyComplex Add(Complex complex)
Calls Add(Entity) and returns the same instance with the read-only type.
void Delete(Entity entity) Marks the entity as deleted in its layer. Depending on the Digi3D.AI Geometry elimination mode option, the .dbf record is marked as deleted or a value is written to a field.
void Delete(IEnumerable<Entity> entities) Calls Delete(Entity) for each entity.
int IndexOf(Entity entity) Returns the entity's position among the entities the file has in memory, or -1 if it does not belong to this file or is not among the entities in memory. Throws NullReferenceException if the entity is null.
void Dispose() Closes the layers.

When saving, an entity is not written, and a message is reported through ResultsAdded (once per code), if its code has no Shapefile format translation, no layer name, or its database table is absent from the code table schema. A code with translation disabled is not written and generates no message.

Exceptions from Add and Delete:

Exception When
ArgumentNullException entities is null in Add(IEnumerable<Entity>), or entity is null in Delete(Entity). Add(Entity) with null throws NullReferenceException, and Delete(IEnumerable<Entity>) does not check whether entities is null.
InvalidOperationException Layers are read-only; the entity belongs to another file (its Owner is another file); or the entity has more than one code. Add(Entity) performs these checks only if the entity can be stored in its code's layer.
Exception The entity's code has attributes (Code.Attributes is not empty) and has no database table or its table has no schema; with Add(IEnumerable<Entity>), also if the code is not in the code table. Also, with the error message, if the .dbf table rejects the attributes.

Events

Event Description
ProgressEventHandler ProgressChanged Percentage of a long operation, in ProgressEventArgs.Progress.
ResultsAddedEventHandler ResultsAdded Informational text, in ResultsAddedEventArgs.Message; for example, codes that cannot be stored.
TaskAddedEventHandler TaskAdded Warning or error, in TaskAddedEventArgs.Task: an ITask with Title, Severity (Error, Warning or Message), DrawingFile and Module.

CodePage

public enum CodePage : byte

Language driver identifier (LDID) written to the header of .dbf tables. Values follow ESRI's code page table.

Value LDID
US_MSDOS 1 (0x01)
InternationalMS_DOS 2 (0x02)
WindowsANSILatinI 3 (0x03)
StandardMacintosh 4 (0x04)
DanishOEM 8 (0x08)
DutchOEM 9 (0x09)
DutchOEM2 10 (0x0A)
FinnishOEM 11 (0x0B)
FrenchOEM 13 (0x0D)
FrenchOEM2 14 (0x0E)
GermanOEM 15 (0x0F)
GermanOEM2 16 (0x10)
ItalianOEM 17 (0x11)
ItalianOEM2 18 (0x12)
JapaneseShift_JIS 19 (0x13)
SpanishOEM2 20 (0x14)
SwedishOEM 21 (0x15)
SwedishOEM2 22 (0x16)
NorwegianOEM 23 (0x17)
SpanishOEM 24 (0x18)
EnglishOEM_GreatBritain 25 (0x19)
EnglishOEM_GreatBritain_2 26 (0x1A)
EnglishOEM_US 27 (0x1B)
FrenchOEM_Canada 28 (0x1C)
FrenchOEM2_ 29 (0x1D)
CzechOEM 31 (0x1F)
HungarianOEM 34 (0x22)
PolishOEM 35 (0x23)
PortugueseOEM 36 (0x24)
PortugueseOEM2 37 (0x25)
RussianOEM 38 (0x26)
EnglishOEM_US_2 55 (0x37)
RomanianOEM 64 (0x40)
ChineseGBK_PRC 77 (0x4D)
Korean_ANSI_OEM 78 (0x4E)
ChineseBig5_Taiwan 79 (0x4F)
Thai_ANSI_OEM 80 (0x50)
CurrentANSICP 87 (0x57)
ANSI 87 (0x57)
WesternEuropeanANSI 88 (0x58)
SpanishANSI 89 (0x59)
EasternEuropeanMS_DOS 100 (0x64)
RussianMS_DOS 101 (0x65)
NordicMS_DOS 102 (0x66)
IcelandicMS_DOS 103 (0x67)
Kamenicky_Czech_MS_DOS 104 (0x68)
Mazovia_Polish_MS_DOS 105 (0x69)
GreekMS_DOS_437G 106 (0x6A)
TurkishMS_DOS 107 (0x6B)
French_CanadianMS_DOS 108 (0x6C)
TaiwanBig5 120 (0x78)
Hangul_Wansung 121 (0x79)
PRCGBK 122 (0x7A)
JapaneseShift_JIS_ 123 (0x7B)
ThaiWindows_MS_DOS 124 (0x7C)
GreekOEM 134 (0x86)
SlovenianOEM 135 (0x87)
TurkishOEM 136 (0x88)
RussianMacintosh 150 (0x96)
EasternEuropeanMacintosh 151 (0x97)
GreekMacintosh 152 (0x98)
EasternEuropeanWindows 200 (0xC8)
RussianWindows 201 (0xC9)
TurkishWindows 202 (0xCA)
GreekWindows 203 (0xCB)
BalticWindows 204 (0xCC)
UTF_8 255 (0xFF)

CurrentANSICP and ANSI are 0x57 (87), the current ANSI code page (1252). The NuGet 26.0.0 package's reference assembly declares CurrentANSICP = 0x51, which is not a valid LDID: use ANSI.

Example

This program lists the layers in a Shapefile folder with the entity count for each code:

using Digi21.DigiNG.IO.Shp;

if (args.Length != 1)
{
    Console.WriteLine(@"Uso: ListaCapas <carpeta\cualquiera.shp>");
    return 1;
}

// Read-only and without a code table: add one code per layer.
using var carpeta = new Shp(args[0], true);
carpeta.ResultsAdded += (sender, e) => Console.WriteLine(e.Message);

var porCódigo = new SortedDictionary<string, int>();
foreach (var entidad in carpeta)
{
    var código = entidad.Codes[0].Name;
    porCódigo[código] = porCódigo.GetValueOrDefault(código) + 1;
}

foreach (var (código, número) in porCódigo)
    Console.WriteLine($"{código}: {número}");

return 0;

The Bind2Shape example writes a .bind file's entities to a Shapefile folder, using a code table relating codes to layers.