geodetic 0.1.0 → 0.3.0

data/docs/coordinate-systems/georef.md

@@ -0,0 +1,221 @@
+# Geodetic::Coordinate::GEOREF
+
+## World Geographic Reference System
+
+GEOREF is a grid-based geocode developed by the US military and adopted by ICAO for air navigation and air defense reporting. It encodes latitude/longitude into a compact alphanumeric string using a false coordinate system that shifts longitude by +180 and latitude by +90 to make all values positive.
+
+The encoding reads longitude first, then latitude at each level:
+
+| Level | Characters | Description | Resolution |
+|-------|-----------|-------------|------------|
+| **Tile** | 1-2 | 15-degree grid (24 lng x 12 lat letters) | 15 degrees |
+| **Degree** | 3-4 | 1-degree subdivision within tile (15 letters each) | 1 degree |
+| **Minutes** | 5+ | Numeric digit pairs (lng digits, then lat digits) | Variable |
+
+The character set uses 24 letters (A-Z, omitting I and O) for tiles, and 15 letters (A-Q, omitting I and O) for degree subdivisions. Minute pairs are decimal digits.
+
+Valid code lengths: 2, 4, 8, 10, 12, 14 characters (not 6 -- minimum numeric portion is 2 digits per axis).
+
+GEOREF is a **2D coordinate system** (no altitude). Conversions to/from other systems go through LLA as the intermediary. Each code represents a rectangular cell; the coordinate's point value is the cell's midpoint.
+
+## Constructor
+
+```ruby
+# From a GEOREF string
+coord = Geodetic::Coordinate::GEOREF.new("GJPJ3417")
+
+# From any coordinate (converts via LLA)
+coord = Geodetic::Coordinate::GEOREF.new(lla_coord)
+coord = Geodetic::Coordinate::GEOREF.new(utm_coord, precision: 10)
+```
+
+| Parameter   | Type              | Default | Description                                    |
+|-------------|-------------------|---------|------------------------------------------------|
+| `source`    | String or Coord   | --      | A GEOREF string or any coordinate object       |
+| `precision` | Integer           | 8       | Code length: 2, 4, 8, 10, 12, or 14           |
+
+Raises `ArgumentError` if the source string is empty, has an invalid length (including 6), or contains invalid characters. String input is case-insensitive (normalized to uppercase).
+
+## Attributes
+
+| Attribute | Type   | Access    | Description              |
+|-----------|--------|-----------|--------------------------|
+| `code`    | String | read-only | The GEOREF code string   |
+
+GEOREF is **immutable** -- there are no setter methods.
+
+## Precision
+
+The precision (code length) determines the size of the encoded cell:
+
+| Length | Resolution | Approximate Cell Size |
+|--------|-----------|----------------------|
+| 2      | 15 degrees | ~1,668 km x 1,668 km |
+| 4      | 1 degree   | ~111 km x 111 km |
+| 8      | 1 minute   | ~1.85 km x 1.85 km |
+| 10     | 0.1 minute | ~185 m x 185 m |
+| 12     | 0.01 minute | ~18.5 m x 18.5 m |
+| 14     | 0.001 minute | ~1.85 m x 1.85 m |
+
+```ruby
+coord.precision              # => 8 (code length)
+coord.precision_in_meters    # => { lat: ~1850, lng: ~1850 }
+```
+
+## Conversions
+
+All conversions chain through LLA. The datum parameter defaults to `Geodetic::WGS84`.
+
+### Instance Methods
+
+```ruby
+coord.to_lla                    # => LLA (midpoint of the cell)
+coord.to_ecef
+coord.to_utm
+coord.to_enu(reference_lla)
+coord.to_ned(reference_lla)
+coord.to_mgrs
+coord.to_usng
+coord.to_web_mercator
+coord.to_ups
+coord.to_state_plane(zone_code)
+coord.to_bng
+coord.to_gh36
+coord.to_gh
+coord.to_ham
+coord.to_olc
+coord.to_gars
+```
+
+### Class Methods
+
+```ruby
+GEOREF.from_lla(lla_coord)
+GEOREF.from_ecef(ecef_coord)
+GEOREF.from_utm(utm_coord)
+GEOREF.from_web_mercator(wm_coord)
+GEOREF.from_gh(gh_coord)
+GEOREF.from_gars(gars_coord)
+# ... and all other coordinate systems
+```
+
+### LLA Convenience Methods
+
+```ruby
+lla = Geodetic::Coordinate::LLA.new(lat: 40.7128, lng: -74.0060)
+georef = lla.to_georef                    # default precision 8
+georef = lla.to_georef(precision: 10)     # 0.1-minute precision
+
+lla = Geodetic::Coordinate::LLA.from_georef(georef)
+```
+
+## Serialization
+
+### `to_s(truncate_to = nil)`
+
+Returns the GEOREF string. An optional integer truncates to that precision (re-encodes from decoded coordinates).
+
+```ruby
+coord = GEOREF.new("GJPJ3417")
+coord.to_s       # => "GJPJ3417"
+coord.to_s(4)    # => "GJPJ"
+coord.to_s(2)    # => "GJ"
+```
+
+### `to_slug`
+
+Alias for `to_s`. GEOREF codes are already URL-safe.
+
+### `to_a`
+
+Returns `[lat, lng]` of the cell midpoint.
+
+```ruby
+coord.to_a    # => [38.286..., -76.411...]
+```
+
+### `from_string` / `from_array`
+
+```ruby
+GEOREF.from_string("GJPJ3417")           # from GEOREF string
+GEOREF.from_array([38.0, -76.0])         # from [lat, lng]
+```
+
+## Neighbors
+
+Returns all 8 adjacent cells as GEOREF instances.
+
+```ruby
+coord = GEOREF.new("GJPJ3417")
+neighbors = coord.neighbors
+# => { N: GEOREF, S: GEOREF, E: GEOREF, W: GEOREF, NE: GEOREF, NW: GEOREF, SE: GEOREF, SW: GEOREF }
+
+neighbors[:N].to_lla.lat > coord.to_lla.lat   # => true
+neighbors[:E].to_lla.lng > coord.to_lla.lng   # => true
+```
+
+Neighbors preserve the same precision as the original code. Latitude is clamped to valid range near the poles; longitude wraps at the antimeridian.
+
+## Area
+
+The `to_area` method returns the GEOREF cell as a `Geodetic::Areas::Rectangle`.
+
+```ruby
+area = coord.to_area
+# => Geodetic::Areas::Rectangle
+
+area.includes?(coord.to_lla)    # => true (midpoint is inside the cell)
+area.nw                         # => LLA (northwest corner)
+area.se                         # => LLA (southeast corner)
+```
+
+## Equality
+
+Two GEOREF instances are equal if their code strings match exactly.
+
+```ruby
+GEOREF.new("GJPJ3417") == GEOREF.new("GJPJ3417")   # => true
+GEOREF.new("GJPJ3417") == GEOREF.new("GJPJ3418")   # => false
+```
+
+## `valid?`
+
+Returns `true` if the code has a valid length (2, 4, 8, 10, 12, or 14), valid tile letters, valid degree letters, and properly formatted minute digits.
+
+```ruby
+coord.valid?    # => true
+```
+
+## Universal Distance and Bearing Methods
+
+GEOREF supports all universal distance and bearing methods via the `DistanceMethods` and `BearingMethods` mixins:
+
+```ruby
+a = GEOREF.new("GJPJ3417")
+b = GEOREF.new("HJAL4243")
+
+a.distance_to(b)                # => Distance
+a.straight_line_distance_to(b)  # => Distance
+a.bearing_to(b)                 # => Bearing
+a.elevation_to(b)               # => Float (degrees)
+```
+
+## Character Sets
+
+**Tile longitude** (24 letters): `A B C D E F G H J K L M N P Q R S T U V W X Y Z`
+
+**Tile latitude** (12 letters): `A B C D E F G H J K L M`
+
+**Degree subdivision** (15 letters): `A B C D E F G H J K L M N P Q`
+
+All sets omit `I` and `O` to avoid confusion with digits `1` and `0`.
+
+## Code Structure Examples
+
+| Code | Meaning |
+|------|---------|
+| `GJ` | 15-degree tile (tile only) |
+| `GJPJ` | 1-degree cell within tile |
+| `GJPJ3417` | 1-minute cell (lng 34', lat 17') |
+| `GJPJ342171` | 0.1-minute cell |
+| `GJPJ34211712` | 0.01-minute cell |

data/docs/coordinate-systems/gh.md

@@ -1,4 +1,4 @@
-# Geodetic::Coordinates::GH
+# Geodetic::Coordinate::GH
 
 ## Geohash (Base-32)
 
@@ -15,11 +15,11 @@ GH is a **2D coordinate system** (no altitude). Conversions to/from other system
 
 ```ruby
 # From a geohash string
-coord = Geodetic::Coordinates::GH.new("dr5ru7")
+coord = Geodetic::Coordinate::GH.new("dr5ru7")
 
 # From any coordinate (converts via LLA)
-coord = Geodetic::Coordinates::GH.new(lla_coord)
-coord = Geodetic::Coordinates::GH.new(utm_coord, precision: 8)
+coord = Geodetic::Coordinate::GH.new(lla_coord)
+coord = Geodetic::Coordinate::GH.new(utm_coord, precision: 8)
 ```
 
 | Parameter   | Type              | Default | Description                                  |
@@ -91,11 +91,11 @@ GH.from_gh36(gh36_coord)
 ### LLA Convenience Methods
 
 ```ruby
-lla = Geodetic::Coordinates::LLA.new(lat: 40.689167, lng: -74.044444)
+lla = Geodetic::Coordinate::LLA.new(lat: 40.689167, lng: -74.044444)
 gh = lla.to_gh                    # default precision 12
 gh = lla.to_gh(precision: 6)      # custom precision
 
-lla = Geodetic::Coordinates::LLA.from_gh(gh)
+lla = Geodetic::Coordinate::LLA.from_gh(gh)
 ```
 
 ## Serialization
@@ -270,7 +270,7 @@ GH (base-32) is the de facto standard. Virtually all spatial databases and servi
 ### Converting Between GH and GH36
 
 ```ruby
-gh = Geodetic::Coordinates::GH.new("dr5ru7")
+gh = Geodetic::Coordinate::GH.new("dr5ru7")
 gh36 = gh.to_gh36                    # => GH36 instance
 gh_back = gh36.to_gh                 # => GH instance
 

data/docs/coordinate-systems/gh36.md

@@ -1,4 +1,4 @@
-# Geodetic::Coordinates::GH36
+# Geodetic::Coordinate::GH36
 
 ## Geohash-36
 
@@ -13,11 +13,11 @@ GH36 is a **2D coordinate system** (no altitude). Conversions to/from other syst
 
 ```ruby
 # From a geohash string
-coord = Geodetic::Coordinates::GH36.new("bdrdC26BqH")
+coord = Geodetic::Coordinate::GH36.new("bdrdC26BqH")
 
 # From any coordinate (converts via LLA)
-coord = Geodetic::Coordinates::GH36.new(lla_coord)
-coord = Geodetic::Coordinates::GH36.new(utm_coord, precision: 8)
+coord = Geodetic::Coordinate::GH36.new(lla_coord)
+coord = Geodetic::Coordinate::GH36.new(utm_coord, precision: 8)
 ```
 
 | Parameter   | Type              | Default | Description                                  |
@@ -86,11 +86,11 @@ GH36.from_web_mercator(wm_coord)
 ### LLA Convenience Methods
 
 ```ruby
-lla = Geodetic::Coordinates::LLA.new(lat: 40.689167, lng: -74.044444)
+lla = Geodetic::Coordinate::LLA.new(lat: 40.689167, lng: -74.044444)
 gh36 = lla.to_gh36                    # default precision 10
 gh36 = lla.to_gh36(precision: 5)      # custom precision
 
-lla = Geodetic::Coordinates::LLA.from_gh36(gh36)
+lla = Geodetic::Coordinate::LLA.from_gh36(gh36)
 ```
 
 ## Serialization

data/docs/coordinate-systems/h3.md

@@ -0,0 +1,312 @@
+# Geodetic::Coordinate::H3
+
+## H3 Hexagonal Hierarchical Index
+
+H3 is Uber's hierarchical geospatial indexing system that divides the globe into hexagonal cells (and 12 pentagons per resolution level) using an icosahedron projection. Each cell is identified by a 64-bit integer, typically displayed as a 15-character hex string like `872a1072bffffff`.
+
+**H3 requires the `libh3` C library** installed on your system. Without it, all other coordinate systems work normally; H3 operations raise a clear error message with installation instructions.
+
+### Prerequisites
+
+```bash
+# macOS (Homebrew)
+brew install h3
+
+# Linux (build from source)
+git clone https://github.com/uber/h3.git
+cd h3
+cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local
+cmake --build build
+sudo cmake --install build
+```
+
+You can also set the `LIBH3_PATH` environment variable to specify a custom library path:
+
+```bash
+export LIBH3_PATH=/path/to/libh3.dylib
+```
+
+Geodetic searches these paths automatically:
+- `/opt/homebrew/lib/libh3.dylib` (macOS ARM Homebrew)
+- `/usr/local/lib/libh3.dylib` (macOS Intel Homebrew)
+- `/usr/lib/libh3.so` (Linux system)
+- `/usr/local/lib/libh3.so` (Linux local install)
+
+### Key Differences from Other Spatial Hashes
+
+| Feature | GH/OLC/GARS/GEOREF/HAM | H3 |
+|---------|------------------------|-----|
+| Cell shape | Rectangle | Hexagon (6 vertices) |
+| `to_area` returns | `Areas::Rectangle` | `Areas::Polygon` |
+| `neighbors` returns | Hash with 8 cardinal keys | Array of 6 cells |
+| Code format | String | 64-bit integer (hex string) |
+| Dependency | None (pure Ruby) | `libh3` (C library via fiddle) |
+
+H3 is a **2D coordinate system** (no altitude). Conversions to/from other systems go through LLA as the intermediary. Each hex string represents a hexagonal cell; the coordinate's point value is the cell's centroid.
+
+## Constructor
+
+```ruby
+# From a hex string
+coord = Geodetic::Coordinate::H3.new("872a1072bffffff")
+
+# From a hex string with 0x prefix
+coord = Geodetic::Coordinate::H3.new("0x872a1072bffffff")
+
+# From a 64-bit integer
+coord = Geodetic::Coordinate::H3.new(0x872a1072bffffff)
+
+# From any coordinate (converts via LLA)
+coord = Geodetic::Coordinate::H3.new(lla_coord)
+coord = Geodetic::Coordinate::H3.new(utm_coord, precision: 9)
+```
+
+| Parameter   | Type                    | Default | Description                                |
+|-------------|-------------------------|---------|--------------------------------------------|
+| `source`    | String, Integer, or Coord | --    | An H3 hex string, integer, or coordinate   |
+| `precision` | Integer                 | 7       | H3 resolution level (0-15)                 |
+
+Raises `ArgumentError` if the source string is empty, contains invalid hex characters, or does not represent a valid H3 cell index. String input is case-insensitive (normalized to lowercase). The `0x` prefix is stripped automatically.
+
+## Attributes
+
+| Attribute  | Type    | Access    | Description                     |
+|------------|---------|-----------|----------------------------------|
+| `code`     | String  | read-only | The hex string representation    |
+| `h3_index` | Integer | read-only | The 64-bit H3 cell index         |
+
+H3 is **immutable** -- there are no setter methods.
+
+## Resolution
+
+H3 uses "resolution" (0-15) instead of string-length precision. Higher resolution means smaller cells.
+
+| Resolution | Approximate Cell Area | Approximate Edge Length |
+|------------|----------------------|------------------------|
+| 0          | 4,357,449 km^2       | 1,108 km               |
+| 1          | 609,788 km^2         | 419 km                 |
+| 2          | 86,801 km^2          | 158 km                 |
+| 3          | 12,393 km^2          | 60 km                  |
+| 4          | 1,770 km^2           | 23 km                  |
+| 5          | 252 km^2             | 8.5 km                 |
+| 6          | 36 km^2              | 3.2 km                 |
+| 7          | 5.2 km^2 (default)   | 1.2 km                 |
+| 8          | 0.74 km^2            | 461 m                  |
+| 9          | 0.105 km^2           | 174 m                  |
+| 10         | 0.015 km^2           | 66 m                   |
+| 11         | 0.002 km^2           | 25 m                   |
+| 12         | 307 m^2              | 9.4 m                  |
+| 13         | 43 m^2               | 3.6 m                  |
+| 14         | 6.2 m^2              | 1.3 m                  |
+| 15         | 0.9 m^2              | 0.5 m                  |
+
+```ruby
+coord.resolution             # => 7 (alias: coord.precision)
+coord.cell_area              # => 5182586.98 (square meters)
+coord.precision_in_meters    # => { lat: ~2276, lng: ~2276, area_m2: ~5182586 }
+```
+
+## Checking Availability
+
+```ruby
+Geodetic::Coordinate::H3.available?   # => true if libh3 is found
+```
+
+## Conversions
+
+All conversions chain through LLA. The datum parameter defaults to `Geodetic::WGS84`.
+
+### Instance Methods
+
+```ruby
+coord.to_lla                    # => LLA (centroid of the cell)
+coord.to_ecef
+coord.to_utm
+coord.to_enu(reference_lla)
+coord.to_ned(reference_lla)
+coord.to_mgrs
+coord.to_usng
+coord.to_web_mercator
+coord.to_ups
+coord.to_state_plane(zone_code)
+coord.to_bng
+coord.to_gh36
+coord.to_gh
+coord.to_ham
+coord.to_olc
+coord.to_georef
+coord.to_gars
+```
+
+### Class Methods
+
+```ruby
+H3.from_lla(lla_coord)
+H3.from_ecef(ecef_coord)
+H3.from_utm(utm_coord)
+H3.from_web_mercator(wm_coord)
+H3.from_gh(gh_coord)
+H3.from_georef(georef_coord)
+H3.from_gars(gars_coord)
+# ... and all other coordinate systems
+```
+
+### LLA Convenience Methods
+
+```ruby
+lla = Geodetic::Coordinate::LLA.new(lat: 40.689167, lng: -74.044444)
+h3 = lla.to_h3                    # default resolution 7
+h3 = lla.to_h3(precision: 9)      # resolution 9
+
+lla = Geodetic::Coordinate::LLA.from_h3(h3)
+```
+
+## Serialization
+
+### `to_s(format = nil)`
+
+Returns the hex string. Pass `:integer` to get the 64-bit integer value.
+
+```ruby
+coord = H3.new("872a1072bffffff")
+coord.to_s             # => "872a1072bffffff"
+coord.to_s(:integer)   # => 608693941536498687
+coord.h3_index         # => 608693941536498687
+```
+
+### `to_slug`
+
+Alias for `to_s`. H3 hex strings are already URL-safe.
+
+### `to_a`
+
+Returns `[lat, lng]` of the cell centroid.
+
+```ruby
+coord.to_a    # => [40.685..., -74.030...]
+```
+
+### `from_string` / `from_array`
+
+```ruby
+H3.from_string("872a1072bffffff")           # from hex string
+H3.from_array([40.689167, -74.044444])       # from [lat, lng]
+```
+
+## Neighbors
+
+Returns all adjacent cells as an Array of H3 instances. Hexagons have 6 neighbors; pentagons have 5.
+
+Note: unlike the rectangular spatial hashes which return a directional Hash (`:N`, `:S`, etc.), H3 returns a flat Array because hexagonal cells do not have cardinal directions.
+
+```ruby
+coord = H3.new("872a1072bffffff")
+neighbors = coord.neighbors
+# => [H3, H3, H3, H3, H3, H3]
+
+neighbors.length    # => 6
+```
+
+## Grid Disk
+
+The `grid_disk(k)` method returns all cells within `k` steps. This is a generalization of `neighbors` (which is `grid_disk(1)` minus self).
+
+```ruby
+coord.grid_disk(0)     # => [self] (1 cell)
+coord.grid_disk(1)     # => [self + 6 neighbors] (7 cells)
+coord.grid_disk(2)     # => 19 cells
+```
+
+## Parent and Children
+
+Navigate the H3 hierarchy by moving to coarser or finer resolution levels.
+
+```ruby
+coord = H3.new("872a1072bffffff")    # resolution 7
+parent = coord.parent(5)              # => H3 at resolution 5
+parent.resolution                     # => 5
+
+children = coord.children(8)          # => Array of 7 H3 cells at resolution 8
+children.length                       # => 7
+children.first.resolution             # => 8
+```
+
+`parent` raises `ArgumentError` if the target resolution is not coarser (lower number). `children` raises `ArgumentError` if the target resolution is not finer (higher number).
+
+## Area
+
+The `to_area` method returns the hexagonal cell boundary as an `Areas::Polygon` with 6 vertices (5 for pentagons).
+
+```ruby
+area = coord.to_area
+# => Geodetic::Areas::Polygon
+
+area.includes?(coord.to_lla)    # => true (centroid is inside the cell)
+area.boundary.length             # => 7 (6 vertices + closing point)
+```
+
+## Pentagon Detection
+
+12 cells at each resolution level are pentagons (artifacts of the icosahedral projection). These have 5 neighbors and 5 boundary vertices instead of 6.
+
+```ruby
+coord.pentagon?    # => false (most cells are hexagons)
+```
+
+## Cell Area
+
+```ruby
+coord.cell_area    # => 5182586.98 (square meters)
+```
+
+## Equality
+
+Two H3 instances are equal if their hex strings match exactly.
+
+```ruby
+H3.new("872a1072bffffff") == H3.new("872a1072bffffff")       # => true
+H3.new("872a1072bffffff") == H3.new(0x872a1072bffffff)       # => true (integer)
+H3.new("872a1072bffffff") == H3.new("87195da49ffffff")       # => false
+```
+
+## `valid?`
+
+Returns `true` if the H3 cell index is valid according to the H3 library.
+
+```ruby
+coord.valid?    # => true
+```
+
+## Universal Distance and Bearing Methods
+
+H3 supports all universal distance and bearing methods via the `DistanceMethods` and `BearingMethods` mixins:
+
+```ruby
+a = H3.new("872a1072bffffff")     # Statue of Liberty area
+b = H3.new("87195da49ffffff")     # London area
+
+a.distance_to(b)                # => Distance (~5,570 km)
+a.straight_line_distance_to(b)  # => Distance
+a.bearing_to(b)                 # => Bearing
+a.elevation_to(b)               # => Float (degrees)
+```
+
+## Well-Known H3 Cells
+
+| Location | H3 Index (res 7) | Resolution |
+|----------|------------------|------------|
+| Statue of Liberty | `872a1072bffffff` | 7 |
+| London | `87195da49ffffff` | 7 |
+| Null Island (0, 0) | `87754e64dffffff` | 7 |
+
+## Implementation Notes
+
+Geodetic uses Ruby's `fiddle` (part of the standard library) to call the H3 v4 C API directly. No gem dependency beyond `fiddle` is required. The H3 C library must be installed separately.
+
+The library search order is:
+1. `LIBH3_PATH` environment variable
+2. `/opt/homebrew/lib/libh3.dylib` (macOS ARM)
+3. `/usr/local/lib/libh3.dylib` (macOS Intel)
+4. `/usr/lib/libh3.so` (Linux)
+5. `/usr/local/lib/libh3.so` (Linux local)
+6. Architecture-specific Linux paths

data/docs/coordinate-systems/ham.md

@@ -1,4 +1,4 @@
-# Geodetic::Coordinates::HAM
+# Geodetic::Coordinate::HAM
 
 ## Maidenhead Locator System
 
@@ -21,11 +21,11 @@ HAM is a **2D coordinate system** (no altitude). Conversions to/from other syste
 
 ```ruby
 # From a Maidenhead locator string
-coord = Geodetic::Coordinates::HAM.new("FN31pr")
+coord = Geodetic::Coordinate::HAM.new("FN31pr")
 
 # From any coordinate (converts via LLA)
-coord = Geodetic::Coordinates::HAM.new(lla_coord)
-coord = Geodetic::Coordinates::HAM.new(utm_coord, precision: 8)
+coord = Geodetic::Coordinate::HAM.new(lla_coord)
+coord = Geodetic::Coordinate::HAM.new(utm_coord, precision: 8)
 ```
 
 | Parameter   | Type              | Default | Description                                    |
@@ -98,11 +98,11 @@ HAM.from_olc(olc_coord)
 ### LLA Convenience Methods
 
 ```ruby
-lla = Geodetic::Coordinates::LLA.new(lat: 40.689167, lng: -74.044444)
+lla = Geodetic::Coordinate::LLA.new(lat: 40.689167, lng: -74.044444)
 ham = lla.to_ham                    # default precision 6
 ham = lla.to_ham(precision: 8)      # extended precision
 
-lla = Geodetic::Coordinates::LLA.from_ham(ham)
+lla = Geodetic::Coordinate::LLA.from_ham(ham)
 ```
 
 ## Serialization