0
# Creation Functions
1

2
High-performance functions for creating arrays of geometries from coordinate data. These functions are optimized for creating large numbers of geometries efficiently and support vectorized operations with NumPy arrays.
3

4
## Capabilities
5

6
### Point Creation
7

8
Create arrays of Point geometries from coordinate data.
9

10
```python { .api }
11
def points(coords, y=None, z=None, indices=None, *, handle_nan='allow', out=None, **kwargs):
12
    """
13
    Create an array of Point geometries.
14
    
15
    Parameters:
16
    - coords: array-like of coordinates, or x-coordinates if y is provided
17
    - y: array-like of y-coordinates (optional)
18
    - z: array-like of z-coordinates (optional)
19
    - indices: array-like of indices for coordinate grouping (optional)
20
    - handle_nan: how to handle NaN coordinates ('allow', 'skip', 'error')
21
    - out: output array (optional)
22
    
23
    Returns:
24
    ndarray of Point geometries
25
    """
26
```
27

28
**Usage Example:**
29

30
```python
31
import shapely
32
import numpy as np
33

34
# Create points from coordinate pairs
35
coords = [(0, 0), (1, 1), (2, 2)]
36
points = shapely.points(coords)
37

38
# Create points from separate x, y arrays
39
x = [0, 1, 2]
40
y = [0, 1, 2]
41
points = shapely.points(x, y)
42

43
# Create 3D points
44
x = [0, 1, 2]
45
y = [0, 1, 2] 
46
z = [0, 1, 2]
47
points_3d = shapely.points(x, y, z)
48

49
# Handle NaN coordinates
50
coords_with_nan = [(0, 0), (np.nan, np.nan), (2, 2)]
51
points = shapely.points(coords_with_nan, handle_nan='skip')
52
```
53

54
### LineString Creation
55

56
Create arrays of LineString geometries from coordinate sequences.
57

58
```python { .api }
59
def linestrings(coords, y=None, z=None, indices=None, *, handle_nan='allow', out=None, **kwargs):
60
    """
61
    Create an array of LineString geometries.
62
    
63
    Parameters:
64
    - coords: array-like of coordinate sequences
65
    - y: array-like of y-coordinates (optional)
66
    - z: array-like of z-coordinates (optional) 
67
    - indices: array-like of indices for coordinate grouping
68
    - handle_nan: how to handle NaN coordinates ('allow', 'skip', 'error')
69
    - out: output array (optional)
70
    
71
    Returns:
72
    ndarray of LineString geometries
73
    """
74
```
75

76
**Usage Example:**
77

78
```python
79
import shapely
80
import numpy as np
81

82
# Create linestrings from nested coordinate sequences
83
coords = [
84
    [(0, 0), (1, 1), (2, 0)],
85
    [(3, 0), (4, 1), (5, 0)]
86
]
87
lines = shapely.linestrings(coords)
88

89
# Create linestrings using indices for grouping
90
all_coords = [(0, 0), (1, 1), (2, 0), (3, 0), (4, 1), (5, 0)]
91
indices = [0, 0, 0, 1, 1, 1]  # Group coords into two linestrings
92
lines = shapely.linestrings(all_coords, indices=indices)
93
```
94

95
### LinearRing Creation
96

97
Create arrays of LinearRing geometries (closed linestrings).
98

99
```python { .api }
100
def linearrings(coords, y=None, z=None, indices=None, *, handle_nan='allow', out=None, **kwargs):
101
    """
102
    Create an array of LinearRing geometries.
103
    
104
    Parameters:
105
    - coords: array-like of coordinate sequences
106
    - y: array-like of y-coordinates (optional)
107
    - z: array-like of z-coordinates (optional)
108
    - indices: array-like of indices for coordinate grouping
109
    - handle_nan: how to handle NaN coordinates ('allow', 'skip', 'error')
110
    - out: output array (optional)
111
    
112
    Returns:
113
    ndarray of LinearRing geometries
114
    """
115
```
116

117
### Polygon Creation
118

119
Create arrays of Polygon geometries from shell and hole definitions.
120

121
```python { .api }
122
def polygons(geometries, holes=None, indices=None, *, out=None, **kwargs):
123
    """
124
    Create an array of Polygon geometries.
125
    
126
    Parameters:
127
    - geometries: array-like of LinearRing objects or coordinate sequences
128
    - holes: array-like of hole definitions (optional)
129
    - indices: array-like of indices for hole grouping
130
    - out: output array (optional)
131
    
132
    Returns:
133
    ndarray of Polygon geometries
134
    """
135
```
136

137
**Usage Example:**
138

139
```python
140
import shapely
141

142
# Create simple polygons from coordinate sequences
143
geometries = [
144
    [(0, 0), (2, 0), (2, 2), (0, 2)],  # Square
145
    [(3, 0), (5, 0), (4, 2)]           # Triangle
146
]
147
polygons = shapely.polygons(geometries)
148

149
# Create polygons with holes
150
geometries = [[(0, 0), (4, 0), (4, 4), (0, 4)]]  # Outer square
151
holes = [[(1, 1), (3, 1), (3, 3), (1, 3)]]   # Inner square hole
152
polygons_with_holes = shapely.polygons(geometries, holes)
153
```
154

155
### Box Creation
156

157
Create rectangular Polygon geometries from bounding coordinates.
158

159
```python { .api }
160
def box(xmin, ymin, xmax, ymax, ccw=True, **kwargs):
161
    """
162
    Create rectangular Polygon geometries.
163
    
164
    Parameters:
165
    - xmin: minimum x-coordinate(s)
166
    - ymin: minimum y-coordinate(s)
167
    - xmax: maximum x-coordinate(s)
168
    - ymax: maximum y-coordinate(s)
169
    - ccw: create counter-clockwise oriented polygons
170
    
171
    Returns:
172
    Polygon geometry or ndarray of Polygon geometries
173
    """
174
```
175

176
**Usage Example:**
177

178
```python
179
import shapely
180
import numpy as np
181

182
# Create single box
183
box = shapely.box(0, 0, 1, 1)
184

185
# Create multiple boxes
186
xmin = [0, 2, 4]
187
ymin = [0, 0, 0]
188
xmax = [1, 3, 5]
189
ymax = [1, 1, 1]
190
boxes = shapely.box(xmin, ymin, xmax, ymax)
191
```
192

193
### Multi-Geometry Creation
194

195
Create collections of geometries.
196

197
```python { .api }
198
def multipoints(geometries, indices=None, *, out=None, **kwargs):
199
    """Create MultiPoint geometries from Point arrays."""
200

201
def multilinestrings(geometries, indices=None, *, out=None, **kwargs):
202
    """Create MultiLineString geometries from LineString arrays."""
203

204
def multipolygons(geometries, indices=None, *, out=None, **kwargs):
205
    """Create MultiPolygon geometries from Polygon arrays."""
206

207
def geometrycollections(geometries, indices=None, out=None, **kwargs):
208
    """Create GeometryCollection geometries from mixed geometry arrays."""
209
```
210

211
**Usage Example:**
212

213
```python
214
import shapely
215

216
# Create individual geometries
217
points = shapely.points([(0, 0), (1, 1), (2, 2)])
218

219
# Group into multi-geometry
220
indices = [0, 0, 1]  # First two points in one MultiPoint, third in another
221
multipoints = shapely.multipoints(points, indices=indices)
222
```
223

224
### Empty Geometry Creation
225

226
Create arrays of empty geometries.
227

228
```python { .api }
229
def empty(shape, geom_type=None, order='C'):
230
    """
231
    Create an array of empty geometries.
232
    
233
    Parameters:
234
    - shape: shape of output array
235
    - geom_type: geometry type (optional, defaults to generic geometry)
236
    - order: array order ('C' for C-contiguous, 'F' for Fortran-contiguous)
237
    
238
    Returns:
239
    ndarray of empty geometries
240
    """
241
```
242

243
### Geometry Preparation
244

245
Prepare geometries for efficient repeated operations.
246

247
```python { .api }
248
def prepare(geometry, **kwargs):
249
    """
250
    Prepare geometries for efficient repeated spatial operations.
251
    
252
    Parameters:
253
    - geometry: geometry or array of geometries to prepare
254
    
255
    Returns:
256
    Prepared geometry objects
257
    """
258

259
def destroy_prepared(geometry, **kwargs):
260
    """
261
    Destroy prepared geometry data.
262
    
263
    Parameters:
264
    - geometry: prepared geometry to destroy
265
    """
266
```
267

268
**Usage Example:**
269

270
```python
271
import shapely
272

273
# Create and prepare geometry for efficient queries
274
polygon = shapely.box(0, 0, 10, 10)
275
prepared_poly = shapely.prepare(polygon)
276

277
# Now spatial queries against prepared_poly will be faster
278
points = shapely.points([(1, 1), (5, 5), (15, 15)])
279
contains_results = shapely.contains(prepared_poly, points)
280
```
281

282
## Types
283

284
```python { .api }
285
# Enumeration for NaN handling
286
class HandleNaN:
287
    allow = 0   # Allow NaN coordinates (default)
288
    skip = 1    # Skip NaN coordinates  
289
    error = 2   # Raise error on NaN coordinates
290
```