digi21.io.bin
Module: digi21.io
Reads and writes BIN files (.bin), Digi3D.AI's binary format with 32-bit integer coordinates.
import digi21.io.bin as bin_
The name bin conflicts with Python's bin() function: import it under another name, such as bin_.
open
open(path, digitab=None, *, precision=2, global_origin=(0.0, 0.0, 0.0)) -> DrawingFile
| Parameter | Type | Default | Description |
|---|---|---|---|
path |
str |
— | .bin file path. |
digitab |
DigiTab | None |
Code table. An empty one is used if omitted. |
precision |
int |
2 |
Number of decimal places used to write the file. |
global_origin |
tuple |
(0.0, 0.0, 0.0) |
Origin (x, y, z) used to write the file. Added to coordinates read. |
Returns a DrawingFile. The file stores neither precision nor global origin: pass the same precision and global_origin to open as to create. The coordinate system comes from the .prj matching the drawing filename.
precision and global_origin are keyword-only. If path does not exist, open raises FileNotFoundError; if global_origin contains infinity or nan, it raises ValueError.
create
create(path, digitab=None, crs="", *, precision=2, global_origin=(0.0, 0.0, 0.0)) -> DrawingWriter
| Parameter | Type | Default | Description |
|---|---|---|---|
path |
str |
— | .bin file path. Replaces an existing file. |
digitab |
DigiTab | None |
Code table. An empty one is used if omitted. |
crs |
str |
"" |
Coordinate system: WKT or "EPSG:<código>". Required. Written to a .prj beside the drawing. |
precision |
int |
2 |
Decimal places to save. Coordinates are stored as 32-bit integers: with 2 decimal places, the maximum value is ±21,474,836.47. |
global_origin |
tuple |
(0.0, 0.0, 0.0) |
Origin (x, y, z) subtracted from coordinates before saving. |
precision and global_origin are the format's two parameters in IMPORTATION_PARAMETERS and are keyword-only.
Exporter behavior:
- Writes points, lines, polygons, text and complex elements.
- Saves codes with at most 6 characters:
"VERTICE"becomes"VERTIC", andwarningsincludes one warning per truncated code. - Preserves an existing matching
.prjbeside the destination instead of writingcrs, andwarningsreports that the existing.prjis preserved. To usecrs, delete that.prjbefore creating the file.
create exceptions: ValueError for missing or invalid crs; FileNotFoundError if the path folder does not exist.
Warning
Because the file does not store precision, reading with a different precision scales coordinates: writing with precision=3 and reading with the default, 2, returns coordinates multiplied by 10 (see the last example).
Examples
These examples were run with Python 3.12; the output shown is the actual output.
Create a file from scratch
import digi21.io.bin as bin_
from digi21.base import Line, Point, Polygon, Text
with bin_.create("parcelas.bin", crs="EPSG:25830") 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)]))
writer.add(Text("Parcela 12", (500050, 4400040, 653), ["020402"], text_height=2.5))
print(writer.written, "entidades escritas en", writer.path)
4 entidades escritas en parcelas.bin
The exporter also writes parcelas.prj with EPSG:25830.
Read and count by type and code
import collections
import digi21.io.bin as bin_
por_tipo = collections.Counter()
por_codigo = collections.Counter()
dibujo = bin_.open("parcelas.bin")
for geometry in dibujo:
por_tipo[type(geometry).__name__] += 1
for code in geometry.codes:
por_codigo[code.code] += 1
print(dict(por_tipo))
print(dict(por_codigo))
{'Point': 1, 'Line': 1, 'Polygon': 1, 'Text': 1}
{'010123': 1, '040645': 1, '020402': 2}
Convert BinDouble to BIN
import digi21.io.bin as bin_
import digi21.io.bindouble as bind
origen = bind.open("parcelas.bind")
with bin_.create("parcelas-convertido.bin", crs=origen.crs) as writer:
for geometry in origen:
writer.add(geometry)
print(writer.written, "escritas,", writer.rejected, "rechazadas")
4 escritas, 0 rechazadas
crs=origen.crs copies the source file's coordinate system.
Write with a global origin
With global_origin, coordinates are saved relative to that origin. Because the file does not store it, pass the same global origin to open as to create:
import digi21.io.bin as bin_
from digi21.base import Line
origen_global = (500000.0, 4400000.0, 0.0)
with bin_.create("origen.bin", crs="EPSG:25830", global_origin=origen_global) as writer:
writer.add(Line(["040645"], [(500000.12, 4400000.25, 650.5), (500100.5, 4400080.75, 655.0)]))
print("Sin origen:", [list(g) for g in bin_.open("origen.bin")])
print("Con origen:", [list(g) for g in bin_.open("origen.bin", global_origin=origen_global)])
Sin origen: [[(0.12, 0.25, 650.5), (100.5, 80.75, 655.0)]]
Con origen: [[(500000.12, 4400000.25, 650.5), (500100.5, 4400080.75, 655.0)]]
open keeps the file open while its DrawingFile or any of its geometries exists: before reopening the same file, release references to the first DrawingFile and its geometries.
Codes longer than 6 characters
import digi21.io.bin as bin_
from digi21.base import Point
with bin_.create("codigos.bin", crs="EPSG:25830") as writer:
writer.add(Point((500010.0, 4400010.0, 650.0), ["VERTICE"]))
for aviso in writer.warnings:
print(aviso)
print([c.code for g in bin_.open("codigos.bin") for c in g.codes])
Se ha almacenado en el archivo BIN una entidad con código desconocido: VERTICE. Se ha conservado dicho código en el archivo de dibujo.
El código VERTICE tiene más de 6 caracteres, el máximo del formato BIN. Se ha almacenado como VERTIC.
['VERTIC']
Exporter warnings use the installation language.
Precision other than 2
import digi21.io.bin as bin_
from digi21.base import Point
with bin_.create("precision.bin", crs="EPSG:25830", precision=3) as writer:
writer.add(Point((1.234, 5.678, 9.0), ["010123"]))
print([list(g) for g in bin_.open("precision.bin", precision=3)])
print([list(g) for g in bin_.open("precision.bin")])
[[(1.234, 5.678, 9.0)]]
[[(12.34, 56.78, 90.0)]]
The file stores 1234, 5678 and 9000. With precision=3, open divides them by 1000; with the default, 2, by 100.
See also
- digi21.io — module index and shared behavior.
- DrawingFile and DrawingWriter
- digi21.io.bindouble — double-precision binary format without coordinate limits.
- BIN format