0
# Coordinate Operations
1

2
Direct manipulation and analysis of coordinate arrays that make up geometries. These functions provide efficient access to the underlying coordinate data and coordinate transformations.
3

4
## Capabilities
5

6
### Coordinate Access
7

8
Extract and manipulate coordinate arrays from geometries.
9

10
```python { .api }
11
def get_coordinates(geometry, include_z=False, include_m=False, return_index=False, **kwargs):
12
    """
13
    Get coordinate array from geometry.
14
    
15
    Parameters:
16
    - geometry: input geometry or array of geometries
17
    - include_z: include Z coordinates in output
18
    - include_m: include M coordinates in output  
19
    - return_index: also return indices mapping coordinates to geometries
20
    
21
    Returns:
22
    ndarray: coordinate array, optionally with indices
23
    """
24

25
def set_coordinates(geometry, coordinates, include_z=None, **kwargs):
26
    """
27
    Set coordinates of geometry (modifies geometry in-place).
28
    
29
    Parameters:
30
    - geometry: input geometry or array of geometries
31
    - coordinates: new coordinate array
32
    - include_z: whether coordinates include Z dimension
33
    
34
    Returns:
35
    Geometry or array: modified geometry (same object)
36
    """
37

38
def count_coordinates(geometry, **kwargs):
39
    """
40
    Count number of coordinates in geometry.
41
    
42
    Parameters:
43
    - geometry: input geometry or array of geometries
44
    
45
    Returns:
46
    int or ndarray: coordinate count
47
    """
48
```
49

50
**Usage Example:**
51

52
```python
53
import shapely
54
import numpy as np
55
from shapely.geometry import LineString, Polygon
56

57
# Extract coordinates from geometry
58
line = LineString([(0, 0), (1, 1), (2, 0)])
59
coords = shapely.get_coordinates(line)
60
print(f"Line coordinates:\n{coords}")
61

62
# Count coordinates
63
count = shapely.count_coordinates(line)
64
print(f"Coordinate count: {count}")
65

66
# Modify coordinates
67
new_coords = coords * 2  # Scale by 2
68
shapely.set_coordinates(line, new_coords)
69
print(f"Modified line: {line}")
70

71
# Work with 3D coordinates
72
line_3d = LineString([(0, 0, 0), (1, 1, 1), (2, 0, 2)])
73
coords_3d = shapely.get_coordinates(line_3d, include_z=True)
74
print(f"3D coordinates shape: {coords_3d.shape}")
75
```
76

77
### Coordinate Transformations
78

79
Apply custom transformations to coordinate data.
80

81
```python { .api }
82
def transform(geometry, transformation, include_z=False, *, interleaved=True):
83
    """
84
    Apply coordinate transformation to geometry.
85
    
86
    Parameters:
87
    - geometry: input geometry or array of geometries
88
    - transformation: transformation function (x, y[, z]) -> (x', y'[, z'])
89
    - include_z: whether to include Z coordinates in transformation
90
    - interleaved: whether coordinates are interleaved (x, y, x, y, ...)
91
    
92
    Returns:
93
    Geometry or array: transformed geometry
94
    """
95
```
96

97
**Usage Example:**
98

99
```python
100
import shapely
101
import numpy as np
102
from shapely.geometry import Point, Polygon
103

104
# Define transformation function (rotate 45 degrees)
105
def rotate_45(x, y):
106
    cos_a = np.cos(np.pi/4)
107
    sin_a = np.sin(np.pi/4)
108
    x_new = x * cos_a - y * sin_a
109
    y_new = x * sin_a + y * cos_a
110
    return x_new, y_new
111

112
# Apply transformation
113
square = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
114
rotated_square = shapely.transform(square, rotate_45)
115

116
print(f"Original area: {square.area}")
117
print(f"Rotated area: {rotated_square.area:.6f}")  # Should be same
118
print(f"Areas equal: {abs(square.area - rotated_square.area) < 1e-10}")
119

120
# Transform with projection (example: simple scaling)
121
def scale_transform(x, y):
122
    return x * 1000, y * 2000  # Scale to different units
123

124
point = Point(1.5, 2.5)
125
scaled_point = shapely.transform(point, scale_transform)
126
print(f"Original point: {point}")
127
print(f"Scaled point: {scaled_point}")
128
```
129

130
### Array-Based Operations
131

132
Efficient coordinate operations on geometry arrays.
133

134
**Usage Example:**
135

136
```python
137
import shapely
138
import numpy as np
139

140
# Create array of geometries
141
np.random.seed(42)
142
points = shapely.points(np.random.rand(100, 2) * 10)
143

144
# Get all coordinates at once
145
all_coords = shapely.get_coordinates(points)
146
print(f"All coordinates shape: {all_coords.shape}")
147

148
# Count coordinates for each geometry
149
coord_counts = shapely.count_coordinates(points)
150
print(f"Coordinate counts (should all be 1): {np.unique(coord_counts)}")
151

152
# Apply transformation to entire array
153
def shift_transform(x, y):
154
    return x + 100, y + 200
155

156
shifted_points = shapely.transform(points, shift_transform)
157

158
# Verify transformation
159
original_bounds = shapely.total_bounds(points)
160
shifted_bounds = shapely.total_bounds(shifted_points)
161
print(f"Original bounds: {original_bounds}")
162
print(f"Shifted bounds: {shifted_bounds}")
163
print(f"Shift correct: {np.allclose(shifted_bounds - original_bounds, [100, 200, 100, 200])}")
164
```
165

166
### Advanced Coordinate Manipulation
167

168
Working with complex coordinate structures and indices.
169

170
**Usage Example:**
171

172
```python
173
import shapely
174
from shapely.geometry import MultiLineString
175

176
# Create complex geometry with multiple parts
177
lines = [
178
    [(0, 0), (1, 1)],
179
    [(2, 2), (3, 3), (4, 4)],
180
    [(5, 5), (6, 6), (7, 7), (8, 8)]
181
]
182
multi_line = MultiLineString(lines)
183

184
# Get coordinates with indices
185
coords, indices = shapely.get_coordinates(multi_line, return_index=True)
186
print(f"Total coordinates: {len(coords)}")
187
print(f"Indices: {indices}")
188
print(f"Coordinates per geometry: {np.bincount(indices)}")
189

190
# Modify specific geometry's coordinates
191
# Find coordinates belonging to first geometry (index 0)
192
mask = indices == 0
193
first_geom_coords = coords[mask]
194
print(f"First geometry coordinates:\n{first_geom_coords}")
195

196
# Scale just the first geometry
197
new_coords = coords.copy()
198
new_coords[mask] *= 2
199

200
# Create new geometry with modified coordinates
201
new_multi_line = shapely.set_coordinates(multi_line, new_coords)
202
print(f"Modified geometry: {new_multi_line}")
203
```