0
# Core Cell Operations
1
2
Essential cell creation, validation, and conversion functions that form the foundation of H3 operations. These functions handle the basic operations needed to work with H3 cells: creating cells from coordinates, validating cell identifiers, converting between formats, and extracting basic cell properties.
3
4
## Capabilities
5
6
### Cell Creation
7
8
Convert geographic coordinates to H3 cell identifiers at a specified resolution.
9
10
```python { .api }
11
def latlng_to_cell(lat: float, lng: float, res: int) -> str:
12
"""
13
Convert latitude/longitude to H3 cell at specified resolution.
14
15
Args:
16
lat: Latitude in degrees (-90 to 90)
17
lng: Longitude in degrees (-180 to 180)
18
res: H3 resolution (0-15, where 0 is coarsest, 15 is finest)
19
20
Returns:
21
H3 cell identifier as hexadecimal string
22
23
Raises:
24
H3LatLngDomainError: If lat/lng outside valid ranges
25
H3ResDomainError: If resolution outside 0-15 range
26
"""
27
```
28
29
### Cell Validation
30
31
Verify that H3 cell identifiers are valid.
32
33
```python { .api }
34
def is_valid_cell(h: str) -> bool:
35
"""
36
Check if an H3 cell identifier is valid.
37
38
Args:
39
h: H3 cell identifier (string or int)
40
41
Returns:
42
True if valid H3 cell, False otherwise
43
44
Note:
45
Returns False for any input that cannot be parsed as H3 cell,
46
including H3 edges or vertices.
47
"""
48
```
49
50
### Cell Properties
51
52
Extract basic properties from H3 cell identifiers.
53
54
```python { .api }
55
def get_resolution(h: str) -> int:
56
"""
57
Get the resolution of an H3 cell.
58
59
Args:
60
h: H3 cell identifier
61
62
Returns:
63
Resolution level (0-15)
64
65
Raises:
66
H3CellInvalidError: If h is not a valid H3 cell
67
"""
68
69
def is_pentagon(h: str) -> bool:
70
"""
71
Check if an H3 cell is a pentagon.
72
73
Args:
74
h: H3 cell identifier
75
76
Returns:
77
True if cell is a pentagon, False if hexagon
78
79
Note:
80
There are exactly 12 pentagons at each resolution level.
81
All other cells are hexagons.
82
"""
83
84
def get_base_cell_number(h: str) -> int:
85
"""
86
Get the base cell number (0-121) of an H3 cell.
87
88
Args:
89
h: H3 cell identifier
90
91
Returns:
92
Base cell number (0 to 121)
93
94
Note:
95
The base cell is the resolution-0 cell containing this cell.
96
"""
97
98
def is_res_class_III(h: str) -> bool:
99
"""
100
Determine if cell has Class II or Class III orientation.
101
102
Args:
103
h: H3 cell identifier
104
105
Returns:
106
True if Class III orientation, False if Class II
107
108
Note:
109
Class III resolutions: 1,3,5,7,9,11,13,15
110
Class II resolutions: 0,2,4,6,8,10,12,14
111
"""
112
```
113
114
### Coordinate Conversion
115
116
Convert H3 cells back to geographic coordinates and boundaries.
117
118
```python { .api }
119
def cell_to_latlng(h: str) -> tuple[float, float]:
120
"""
121
Get the center coordinates of an H3 cell.
122
123
Args:
124
h: H3 cell identifier
125
126
Returns:
127
Tuple of (latitude, longitude) in degrees
128
129
Raises:
130
H3CellInvalidError: If h is not a valid H3 cell
131
"""
132
133
def cell_to_boundary(h: str) -> tuple[tuple[float, float], ...]:
134
"""
135
Get the boundary vertices of an H3 cell.
136
137
Args:
138
h: H3 cell identifier
139
140
Returns:
141
Tuple of (lat, lng) coordinate pairs defining cell boundary.
142
Hexagons return 6 points, pentagons return 5 points.
143
144
Raises:
145
H3CellInvalidError: If h is not a valid H3 cell
146
147
Note:
148
Points are ordered counterclockwise around the cell boundary.
149
"""
150
```
151
152
### Format Conversion
153
154
Convert between hexadecimal string and integer representations of H3 cells.
155
156
```python { .api }
157
def str_to_int(h: str) -> int:
158
"""
159
Convert hexadecimal string H3 identifier to 64-bit integer.
160
161
Args:
162
h: H3 identifier as hexadecimal string (e.g., '89754e64993ffff')
163
164
Returns:
165
H3 identifier as unsigned 64-bit integer
166
167
Raises:
168
ValueError: If h is not valid hexadecimal format
169
"""
170
171
def int_to_str(x: int) -> str:
172
"""
173
Convert 64-bit integer H3 identifier to hexadecimal string.
174
175
Args:
176
x: H3 identifier as unsigned 64-bit integer
177
178
Returns:
179
H3 identifier as hexadecimal string (e.g., '89754e64993ffff')
180
181
Raises:
182
ValueError: If x is not a valid H3 integer identifier
183
"""
184
```
185
186
### System Information
187
188
Get information about the H3 system and library versions.
189
190
```python { .api }
191
def versions() -> dict[str, str]:
192
"""
193
Get version information for H3 Python and C libraries.
194
195
Returns:
196
Dictionary with keys:
197
- 'python': Python wrapper version (e.g., '4.3.1')
198
- 'c': C library version (e.g., '4.3.0')
199
200
Note:
201
Python and C versions match on major.minor but may differ on patch.
202
"""
203
204
def get_num_cells(res: int) -> int:
205
"""
206
Get total number of H3 cells at a given resolution.
207
208
Args:
209
res: H3 resolution (0-15)
210
211
Returns:
212
Total number of cells (hexagons + pentagons) at resolution
213
214
Raises:
215
H3ResDomainError: If resolution outside 0-15 range
216
217
Note:
218
Cell counts grow exponentially: ~7x more cells per resolution level.
219
"""
220
```
221
222
## Usage Examples
223
224
### Basic Cell Operations
225
226
```python
227
import h3
228
229
# Create cell from coordinates
230
lat, lng = 37.7749, -122.4194 # San Francisco
231
cell = h3.latlng_to_cell(lat, lng, resolution=9)
232
print(f"Cell: {cell}") # Cell: 89283082e6bffff
233
234
# Validate and get properties
235
if h3.is_valid_cell(cell):
236
print(f"Resolution: {h3.get_resolution(cell)}") # Resolution: 9
237
print(f"Is pentagon: {h3.is_pentagon(cell)}") # Is pentagon: False
238
print(f"Base cell: {h3.get_base_cell_number(cell)}") # Base cell: 20
239
240
# Get center and boundary
241
center = h3.cell_to_latlng(cell)
242
print(f"Center: {center[0]:.6f}, {center[1]:.6f}")
243
244
boundary = h3.cell_to_boundary(cell)
245
print(f"Boundary has {len(boundary)} vertices")
246
for i, (lat, lng) in enumerate(boundary):
247
print(f" Vertex {i}: {lat:.6f}, {lng:.6f}")
248
```
249
250
### Format Conversion
251
252
```python
253
import h3
254
255
# Convert between string and integer formats
256
hex_cell = '89283082e6bffff'
257
int_cell = h3.str_to_int(hex_cell)
258
print(f"Integer: {int_cell}") # Integer: 621566949282324479
259
260
# Convert back to string
261
back_to_hex = h3.int_to_str(int_cell)
262
print(f"Hex: {back_to_hex}") # Hex: 89283082e6bffff
263
assert hex_cell == back_to_hex
264
265
# Use integer API directly
266
import h3.api.basic_int as h3int
267
cell_int = h3int.latlng_to_cell(37.7749, -122.4194, 9)
268
print(f"Integer cell: {cell_int}") # Integer cell: 621566949282324479
269
```
270
271
### System Information
272
273
```python
274
import h3
275
276
# Check library versions
277
versions = h3.versions()
278
print(f"Python h3: {versions['python']}") # Python h3: 4.3.1
279
print(f"C library: {versions['c']}") # C library: 4.3.0
280
281
# Get cell counts by resolution
282
for res in range(0, 6):
283
count = h3.get_num_cells(res)
284
print(f"Resolution {res}: {count:,} cells")
285
286
# Resolution 0: 122 cells
287
# Resolution 1: 842 cells
288
# Resolution 2: 5,882 cells
289
# Resolution 3: 41,162 cells
290
# Resolution 4: 288,122 cells
291
# Resolution 5: 2,016,842 cells
292
```