digi21.io.shp
Module: digi21.io
Reads and writes ESRI shapefiles (.shp, .shx, .dbf, .prj and .cpg). A shapefile has one geometry type, so the exporter writes one layer per code in the destination folder.
import digi21.io.shp as shp
Important
Import digi21.io.shp before loading the code table with DigiTab.load. The first table loaded in the process receives ioshp:transform elements only if the module is already imported.
open
open(path, digitab=None) -> DrawingFile
| Argument | Type | Description |
|---|---|---|
path |
str |
Path of one .shp in the folder. |
digitab |
DigiTab | Optional code table. An empty one is used if omitted. |
Returns a DrawingFile with geometries from all layers in the folder of path, in layer order. DrawingFile.path is the folder. Polygon vertices are read in the reverse order to writing: the format stores exterior rings clockwise. Raises FileNotFoundError if path does not exist.
create
create(path, digitab=None, crs="", *, precision=0, encoding=0xFF) -> DrawingWriter
| Parameter | Type | Default | Description |
|---|---|---|---|
path |
str |
— | Path of a .shp in the destination folder. Only the folder is used: layer names come from the code table. |
digitab |
DigiTab | None |
Code table. Essential: each code needs an ioshp:transform and a database table. |
crs |
str |
"" |
Coordinate system: WKT or "EPSG:<código>". Required. Written to each new layer's .prj. |
precision |
int |
0 |
Decimal places for coordinate rounding, 0 through 12 inclusive. With 0, no rounding. Out-of-range values raise ValueError. |
encoding |
int |
0xFF |
Language driver ID (LDID) for .dbf encoding, 0 through 255 inclusive. With 0xFF, .cpg declares UTF-8; with 0x57, 1252. Out-of-range values raise ValueError. |
precision and encoding are the format's two IMPORTATION_PARAMETERS parameters and are keyword-only.
Code table requirements for each written code:
- An assigned database table (
table) existing in the database schema (databaseSchema), with a numeric primary key. - An
ioshp:transformwith the layer name (nameSHP) and geometry type (typeNewTable: 11 = points, 13 = lines, 15 = polygons, all with Z).
<databaseSchema>
<table name="Prueba" description="">
<field name="Id" title="Id" type="N" length="11" primaryKey="1" />
<field name="Nombre" title="Nombre" type="C" length="50" />
</table>
</databaseSchema>
<codes>
<code name="040645" description="Árbol puntual" type="0" table="Prueba" …>
<io>
<ioshp:transform export="1" nameSHP="shp_040645" typeNewTable="13" />
Exporter behavior:
- Rejects geometries whose code does not meet requirements;
warningsidentifies what is missing. - Rejects geometries of an incompatible layer type (text in a polygon layer, a line in a point layer).
- Replaces same-name layers and preserves other layers in the folder. Replaced layers retain their
.prj;warningsreports any folder.prjwith a different coordinate system.
create exceptions: ValueError for missing or invalid crs or out-of-range precision or encoding; FileNotFoundError if the path folder does not exist.
Examples
These examples were run with Python 3.12; the output shown is the actual output. Digi.tab.xml is the code table above: codes 010123, 040645 and 020402 map to shp_010123 (points), shp_040645 (lines) and shp_020402 (polygons).
Create layers from scratch
import os
import digi21.io.shp as shp
from digi21.base import DigiTab, Line, Point, Polygon
digitab = DigiTab.load("Digi.tab.xml")
os.makedirs("capas", exist_ok=True)
with shp.create("capas/parcelas.shp", digitab, crs="EPSG:25830", precision=3) as writer:
writer.add(Point((500010.0, 4400010.0, 650.0), ["010123"]))
writer.add(Line(["040645"], [(500000, 4400000, 650), (500100, 4400000, 652), (500100, 4400080, 655)]))
writer.add(Polygon(["020402"], [(500000, 4400000, 650), (500100, 4400000, 652),
(500100, 4400080, 655), (500000, 4400000, 650)]))
print(writer.written, "escritas,", writer.rejected, "rechazadas")
print(sorted(f for f in os.listdir("capas") if f.endswith(".shp")))
3 escritas, 0 rechazadas
['shp_010123.shp', 'shp_020402.shp', 'shp_040645.shp']
The name parcelas.shp is unused.
Read every layer in the folder
import collections
import digi21.io.shp as shp
from digi21.base import DigiTab
digitab = DigiTab.load("Digi.tab.xml")
conteo = collections.Counter()
for geometry in shp.open("capas/shp_040645.shp", digitab):
conteo[(geometry.codes[0].code, type(geometry).__name__)] += 1
for (codigo, tipo), n in sorted(conteo.items()):
print(codigo, tipo, n)
010123 Point 1
020402 Polygon 1
040645 Line 1
open receives one layer and reads all three.
Convert BinDouble to shapefiles
import os
import digi21.io.bindouble as bind
import digi21.io.shp as shp
from digi21.base import DigiTab
digitab = DigiTab.load("Digi.tab.xml")
origen = bind.open("parcelas.bind", digitab)
os.makedirs("convertido", exist_ok=True)
with shp.create("convertido/capas.shp", digitab, crs=origen.crs) as writer:
for geometry in origen:
if not writer.add(geometry):
print("Rechazada:", type(geometry).__name__, [c.code for c in geometry.codes])
print(writer.written, "escritas,", writer.rejected, "rechazadas")
for aviso in writer.warnings:
print(aviso)
Rechazada: Text ['020402']
3 escritas, 1 rechazadas
The format cannot store a text with the code 020402.
parcelas.bind is created by the first digi21.io.bindouble example. The 020402 layer contains polygons, so text is rejected.
Choose .dbf encoding
import os
import digi21.io.shp as shp
from digi21.base import DigiTab, Point
digitab = DigiTab.load("Digi.tab.xml")
os.makedirs("ansi", exist_ok=True)
with shp.create("ansi/capas.shp", digitab, crs="EPSG:25830", encoding=0x57) as writer:
writer.add(Point((500010.0, 4400010.0, 650.0), ["010123"]))
with open("ansi/shp_010123.dbf", "rb") as dbf:
print(hex(dbf.read(30)[29]))
with open("ansi/shp_010123.cpg", encoding="ascii") as cpg:
print(cpg.read())
0x57
1252
Byte 29 of the .dbf header is the LDID. 0x57 means Windows-1252, declared by .cpg.
See also
- digi21.io — module index and shared behavior.
- digi21.io.geopackage — a single database with one table per code.
- DrawingFile and DrawingWriter
- SHP format