Block Places

Geographic translation utilities for use on the Blockchain: ( Longitude, Latitude ) <-> ( Block Place Id )

Author: ivyroot: https://farcaster.xyz/ivyroot - https://x.com/ivyroot_zk

Description:
- Block Places are a set of ids that can be used to identify locations anywhere on Earth.
- Each Block Place is a rectangular area with sides that are 1/100th of a degree long.
- They are stored as Longitude, Latitude pairs encoded in a single number, the Block Place ID.

Components:
- The Longitude and Latitude values for a Block Place are each stored as two parts:
- The first gives the whole number, from 0-359 for Longitude and from 0-179 for Latitude.
- The second gives the decimal in hundredths of a degree. So 0.00, 0.01, 0.02 ... 0.99 map to 0 through 99.

Bitpacking:
- The set of 4 values specifying a Block Place are bitpacked together into a single unique number:
- Longitude whole degree values must be less than 360. They are stored as 16 bits.
- Latitude whole degree values must be less than 180. They are stored as 8 bits.
- Decimal values must be less than 100. They are stored as 8 bits each.
- The byte ordering format is [Longitude][Latitude][Longitude Decimal][Latitude Decimal]

Translation to Geographic Coordinates:
- All values composing a BlockPlace are stored as non-negative integers.
- They are mapped to geographic coordinates using offsets that remove
negative values.
- When geographic coordinates are passed in they have an offset added
to them.
- When geographic coordinates are passed out they have an offset
subtracted from them.
- The offset is 180 for Longitude and 90 for Latitude.

Multi-Place Regions (Square Regions)

Overview:
Block Places can represent regions larger than a single 0.01° × 0.01°
square. Multi-place regions are defined by an origin place and a
size parameter, where size indicates how many places the region
spans in each direction.

Origin Convention - Northwest Corner:
The origin place for a multi-place region is always the **northwest
(top-left) corner**. This convention is defined in the Solidity smart
contract function placeIdsInSquare(uint256 northWestPlaceId, uint256
size) in BlockPlaces.sol.

Expansion Direction:
From the northwest origin, the region expands:
- EAST (positive longitude direction): lng + j
- SOUTH (negative latitude direction): lat - i

For a region of size = N:
- Width: N places = N × 0.01° longitude
- Height: N places = N × 0.01° latitude
- Total places: N × N places

Example - Size 2 Region:
Given a northwest origin place at (lng: 100.50, lat: 40.75):
``
NW (origin) | NE
100.50, 40.75 | 100.51, 40.75
--------------+--------------
100.50, 40.74 | 100.51, 40.74
SW | SE
`

Calculating Bounds:
To calculate the geographic bounds of a multi-place region:

1. Get the origin place bounds (northwest corner)
2. Southwest corner latitude = originNorth - (size × 0.01)
3. Northeast corner longitude = originEast + (size × 0.01)
(equivalent to originWest + (size × 0.01))
4. Final bounds: [originWest, swLat] to [neLng, originNorth]

Implementation Reference:
- Solidity: placeIdsInSquare() in src/BlockPlaces.sol
(lines 130-159)
- TypeScript: sizedLngLatBoundsFromPlaceId() in
typescript/src/BlockPlaces.ts` (lines 94-108)

Important Note for Rendering:
When rendering multi-place regions on a map, always treat the provided
placeId as the northwest corner. The region extends east and south
from this origin. Using any other corner (e.g., southwest) will result
in incorrect geographic positioning.