0
# Spatial Elements
1

2
Spatial element classes for handling spatial data interchange between database representations and Python objects. These elements provide transparent conversion and enable direct application of spatial functions to geometric data.
3

4
## Capabilities
5

6
### WKT Elements
7

8
Handle Well-Known Text representations of geometries, providing human-readable spatial data interchange.
9

10
```python { .api }
11
class WKTElement:
12
    """
13
    Element for Well-Known Text geometry representations.
14
    
15
    Parameters:
16
    - data: str, WKT string representation of geometry
17
    - srid: int, spatial reference system identifier (default: -1)
18
    - extended: bool, use extended WKT format (default: None)
19
    """
20
    
21
    def __init__(self, data: str, srid: int = -1, extended: bool = None): ...
22
    
23
    @property
24
    def desc(self) -> str:
25
        """String representation of the WKT data."""
26
```
27

28
Usage examples:
29

30
```python
31
from geoalchemy2 import WKTElement
32
from geoalchemy2.functions import ST_Area, ST_Buffer
33

34
# Create WKT element from string
35
point = WKTElement('POINT(1 2)', srid=4326)
36
polygon = WKTElement('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))', srid=4326)
37

38
# Use in database operations
39
session.add(Lake(name='Test Lake', geom=polygon))
40

41
# Apply spatial functions directly
42
buffered = point.ST_Buffer(100)
43
area = polygon.ST_Area()
44

45
# Use in queries  
46
lakes = session.query(Lake).filter(
47
    Lake.geom.ST_Contains(point)
48
).all()
49
```
50

51
### WKB Elements
52

53
Handle Well-Known Binary representations of geometries, providing efficient binary spatial data interchange.
54

55
```python { .api }
56
class WKBElement:
57
    """
58
    Element for Well-Known Binary geometry representations.
59
    
60
    Parameters:
61
    - data: bytes, WKB binary representation of geometry
62
    - srid: int, spatial reference system identifier (default: -1)  
63
    - extended: bool, use extended WKB format (default: None)
64
    """
65
    
66
    def __init__(self, data: bytes, srid: int = -1, extended: bool = None): ...
67
    
68
    @property  
69
    def desc(self) -> str:
70
        """Hexadecimal string representation of the WKB data."""
71
```
72

73
Usage examples:
74

75
```python
76
from geoalchemy2 import WKBElement
77
import binascii
78

79
# Create WKB element from binary data
80
wkb_data = binascii.unhexlify('0101000000000000000000F03F0000000000000040')
81
point = WKBElement(wkb_data, srid=4326)
82

83
# WKB elements are typically returned from database queries
84
lake = session.query(Lake).first()
85
geometry = lake.geom  # This is a WKBElement
86

87
# Apply spatial functions
88
center = geometry.ST_Centroid()
89
area = geometry.ST_Area()
90
transformed = geometry.ST_Transform(3857)
91

92
# Use in spatial operations
93
nearby = session.query(Lake).filter(
94
    Lake.geom.ST_DWithin(point, 1000)
95
).all()
96
```
97

98
### Raster Elements
99

100
Handle raster data representations for satellite imagery, digital elevation models, and gridded datasets.
101

102
```python { .api }
103
class RasterElement:
104
    """
105
    Element for raster data representations.
106
    
107
    Parameters:
108
    - data: bytes, binary raster data
109
    - srid: int, spatial reference system identifier (default: -1)
110
    """
111
    
112
    def __init__(self, data: bytes, srid: int = -1): ...
113
    
114
    @property
115
    def desc(self) -> str:
116
        """Hexadecimal string representation of the raster data."""
117
```
118

119
Usage examples:
120

121
```python
122
from geoalchemy2 import RasterElement
123

124
# Raster elements are typically returned from database queries
125
image = session.query(SatelliteImage).first()
126
raster = image.image_data  # This is a RasterElement
127

128
# Apply raster functions
129
width = raster.ST_Width()
130
height = raster.ST_Height()
131
num_bands = raster.ST_NumBands()
132

133
# Extract pixel values
134
pixel_value = raster.ST_Value(1, 100, 200)  # band 1, x=100, y=200
135

136
# Convert to geometry
137
convex_hull = raster.ST_ConvexHull()
138
envelope = raster.ST_Envelope()
139
```
140

141
### Composite Elements
142

143
Handle composite values returned by spatial functions that produce structured results.
144

145
```python { .api }
146
class CompositeElement:
147
    """
148
    Element for accessing components of composite spatial types.
149
    
150
    Parameters:
151
    - base: base expression or element
152
    - field: str, field name to access
153
    - type_: SQLAlchemy type for the field
154
    """
155
    
156
    def __init__(self, base, field: str, type_): ...
157
```
158

159
Usage examples:
160

161
```python
162
from geoalchemy2.functions import ST_Dump
163

164
# ST_Dump returns GeometryDump composite type
165
dump_result = session.query(ST_Dump(polygon)).first()
166

167
# Access composite components
168
path = dump_result.path    # Array of integers
169
geom = dump_result.geom    # Geometry component
170

171
# Use in complex queries
172
components = session.query(
173
    ST_Dump(Lake.geom).geom.label('part'),
174
    ST_Dump(Lake.geom).path.label('path')
175
).all()
176
```
177

178
### Dynamic Elements
179

180
Self-updating element classes that automatically refresh their spatial function capabilities.
181

182
```python { .api }
183
class DynamicWKTElement(WKTElement):
184
    """Dynamic WKT element with auto-updating function capabilities."""
185

186
class DynamicWKBElement(WKBElement):  
187
    """Dynamic WKB element with auto-updating function capabilities."""
188

189
class DynamicRasterElement(RasterElement):
190
    """Dynamic raster element with auto-updating function capabilities."""
191
```
192

193
## Element Conversion
194

195
Spatial elements provide automatic conversion between different representations:
196

197
### From Database
198
- Database binary data → WKBElement (automatic via result processor)
199
- Database text data → WKTElement (when explicitly requested)
200
- Database raster data → RasterElement (automatic via result processor)
201

202
### To Database  
203
- WKTElement → Database-specific text format (via bind processor)
204
- WKBElement → Database-specific binary format (via bind processor)
205
- RasterElement → Database-specific raster format (via bind processor)
206

207
### Between Elements
208
```python
209
# Convert WKT to WKB via database function
210
wkt_elem = WKTElement('POINT(1 2)', srid=4326)
211
wkb_result = session.scalar(wkt_elem.ST_AsBinary())
212

213
# Convert WKB to WKT via database function  
214
wkb_elem = WKBElement(binary_data, srid=4326)
215
wkt_result = session.scalar(wkb_elem.ST_AsText())
216
```
217

218
## Spatial Function Integration
219

220
All spatial elements automatically provide access to the complete library of spatial functions:
221

222
```python
223
# Geometry construction and manipulation
224
transformed = element.ST_Transform(3857)
225
buffered = element.ST_Buffer(100)
226
simplified = element.ST_Simplify(0.1)
227

228
# Spatial relationships and predicates
229
contains = element1.ST_Contains(element2)
230
intersects = element1.ST_Intersects(element2)
231
within = element1.ST_Within(element2)
232

233
# Measurements and calculations
234
area = element.ST_Area()
235
length = element.ST_Length()
236
distance = element1.ST_Distance(element2)
237

238
# Coordinate system operations
239
srid = element.ST_SRID()
240
transformed = element.ST_Transform(4326)
241
```
242

243
Each spatial function returns appropriate types:
244
- Geometric functions return new spatial elements
245
- Predicate functions return boolean values
246
- Measurement functions return numeric values
247
- Analysis functions return composite elements or arrays