## GeoArrow memory layout The low-level decisions of how to store coordinates are crucially important to how efficient a memory format can be. > _(This section gets into some gory technical details. Feel free to skip below!)_ Arrow memory, by design, is both zero-copy and has constant-time access. The zero-copy part implies that multiple threads or processes can read the same data without a copy (though this is harder to use in a browser environment). Through use of a smart data layout, the access to any cell of an Arrow table is always possible in constant time. This means that there's no _parsing_ that needs to happen, even for nested data types, to access a value. ### Arrow-native geometry format GeoArrow is able to build upon Arrow's strengths so that geometry coordinates can be accessed with no copy and in constant time. The current version of the specification [defines](https://github.com/geopandas/geo-arrow-spec/blob/f2eb98e7e2f60ed409ed88078015a9c45f469604/format.md#format) a "nested list" layout. This layout should be familiar to anyone who has used GeoJSON. For each geometry type, the levels of nesting corresponds exactly to the GeoJSON coordinate array (with one extra level of nesting because here we have _an array_ of geometries, not just one). For example, a geometry column of 2D points is defined as: ``` FixedSizeList[2] ``` You can think of this as similar to an array of GeoJSON point coordinates ```js [ [longitude1, latitude1], // First point [longitude2, latitude2], // Second point ... ] ``` A geometry column containing 2D polygons is defined as: ``` List[n_dim]>> ``` You can think of this logical layout as: ```js [ // <-- Array of geometries [ // <-- Array of rings within the first polygon [ // <-- Array of coordinates within the first polygon ring [ // <-- Coordinate pair longitude1, latitude1 ], [ longitude2, latitude2 ], ... ] ] ] ``` ### Efficient underlying buffers But the awesome part of this geometry encoding is that it combines the above "logical" representation with a really efficient underlying "physical" representation. And it's possible to access both representations through the Arrow API. For example, a column of point geometries is _stored_ as: ```js [longitude1, latitude1, longitude2, latitude2, longitude3, latitude3, ...] // ^- first coordinate ^- second coordinate ^- third coordinate ``` Since the column is defined as `FixedSizeList<2>`, we know that to access the _n^th_ coordinate, we choose the `n * 2` and `(n * 2) + 1` values in the flat array. A column of polygon geometries is slightly more complex. It's stored as a flat coordinate array _plus_ two arrays of _offsets_ that define where polygons and rings begin. Let's start at the lowest level. There's still an array just like above that contains _all coordinates_ of _all geometries_ in the column: ```js [longitude1, latitude1, longitude2, latitude2, longitude3, latitude3, ...] // ^- first coordinate ^- second coordinate ^- third coordinate ``` Then one level of nesting up, we have the _ring offsets array_. This might look something like: ```js [0, 5, 12, 19, ...] ``` This means that the first ring has 5 coordinate pairs, from index 0 to index 4 (inclusive) of the base coordinate array. Then the second ring has 7 coordinate pairs, from index 5 to index 11 (inclusive) of the base coordinate array. And so on. But this array of ring offsets doesn't tell us where _each polygon_ begins and ends, since a single polygon can contain multiple rings (secondary rings for a single geometry indicate holes within the first ring). This is where the _geometry offsets array_ comes in. This might look something like: ```js [0, 1, 3, ...] ``` This means that the first geometry only has a single ring, from ring index `0` to ring index `1`. The second geometry has two rings, from ring index `1` to ring index `3`. Thus the first geometry includes coordinates from coordinate index `0` through coordinate index `4` (up to but not including index `1` in the ring offsets array), and the second geometry includes coordinates from coordinate index `5` through coordinate index `18` (from index `1` in the ring offsets array to index `3` in the ring offsets array). Together, these offset arrays define the same geometries as the "logical" nested lists that GeoJSON describes.