A tile address is a position in a declared grid
A tiled map opens, its colours look familiar, and every image can be decoded. Yet one row of tiles appears in the wrong place. The pictures may be intact while the grid interpretation is wrong. To find the error, start with the relationship between the matrix, the tile dimensions and the coordinate reference—not the appearance of the map.
GeoPackage raster tile tables use declared matrix information to connect image arrays to geographic positions. This guide works through that connection from first principles: how much space one pixel occupies, how tile rows and columns identify a region, and why a grid can be structurally complete while its actual observations remain sparse.
All grids and coordinates below are fictional planar teaching examples. Their stated metre units make the arithmetic easy; they are not registered reference systems or surveys. Real packages require the applicable GeoPackage specification, correctly interpreted reference definitions, supported readers and independent location evidence.
Geoinformatics subject guide · Learning that transfers into life · How X Works hub
Choose your reading route
Route 1: Read the grid contract · Chapters 1–3
Route 2: Locate tiles and pixels · Chapters 4–6
Route 3: Check levels and coverage · Chapters 7–8
Read each zoom level rather than assuming a universal pyramid
Route 4: Diagnose and test · Chapters 9–10
Diagnose row reversal, wrong scale and wrong reference separately
Route 5: Transfer and deliver · Chapters 11–12
Transfer the grid into another representation without losing meaning
Full chapter index · Independent worked case · Questions and practical checks
Chapter index
Read the grid contract · Chapters 1–3
Separate the image from its geographic address
Read the matrix set and the level-specific matrix together
Derive tile spans and total grid dimensions
Locate tiles and pixels · Chapters 4–6
Locate a tile using top-left zero-based indexing
Distinguish pixel edges from pixel centres
Treat outer boundaries and neighbouring tiles deliberately
Check levels and coverage · Chapters 7–8
Read each zoom level rather than assuming a universal pyramid
Separate potential tile positions from stored coverage
Diagnose and test · Chapters 9–10
Diagnose row reversal, wrong scale and wrong reference separately
Build a repeatable grid-validation fixture
Transfer and deliver · Chapters 11–12
Transfer the grid into another representation without losing meaning
Deliver a grid explanation that another reader can check
CHAPTER 1 OF 12
1. Separate the image from its geographic address
A tile image is an array of pixels. On its own, it can be displayed as a picture without establishing where those pixels belong on Earth. The geographic interpretation comes from a connected set of declarations: the tiled area, coordinate reference, zoom-level matrix, tile dimensions, pixel sizes and each stored tile’s row and column. A readable image is only one part of that chain.
Think of a classroom wall made from numbered picture cards. You can inspect each card separately and still assemble the wall incorrectly by reversing its rows. Nothing inside the printed picture needs to be damaged. The error concerns placement. Tiled geographic data has a similar distinction between the resource being stored and the addressing system used to position it.
Begin an audit by naming the tile table and the relevant zoom level. Numbers from another table or level can look plausible while describing a different grid. Keep the table identity attached to every matrix lookup. A successful query returning one matrix row does not prove that the row belongs to the images you intend to interpret.
Also identify the content type. This guide concerns GeoPackage raster tile matrices, not the coordinate geometry encoded inside vector tiles. The connected vector-tile guide explains a different representation. Similar words such as tile, extent and zoom can appear in both systems without giving their numerical fields identical meanings.
CHAPTER 2 OF 12
2. Read the matrix set and the level-specific matrix together
The GeoPackage tile matrix set establishes the reference and spatial bounds for a tiled dataset. The tile matrix table describes each represented level: matrix width and height in tiles, tile width and height in pixels, and horizontal and vertical pixel sizes. These values work together; none should be interpreted as an isolated scale label.
For our fictional grid, let min_x be 1000 and max_y be 5000. At the chosen level, tiles are 256 pixels wide and 128 pixels high. Pixel sizes are 2 metres horizontally and 4 metres vertically. The matrix has three tile columns and four tile rows. These explicit declarations are the whole classroom contract; no real-world CRS is being implied.
Before calculating a position, write units beside each number. Matrix width counts tiles. Tile width counts pixels per tile. Pixel size measures reference-coordinate units per pixel. Multiplying those three quantities cancels the intermediate counting units and produces a spatial width. Confusing any two of them can create a plausible-looking but incorrectly scaled map.
Do not replace declared values with familiar defaults. A developer may expect square images, square pixels or a global web map grid. Our fixture deliberately uses rectangular images and different horizontal and vertical pixel sizes. It exposes assumptions that a symmetric example would conceal. Real values must come from the actual package, not from the last map a client happened to open.
CHAPTER 3 OF 12
3. Derive tile spans and total grid dimensions
One fictional tile spans 256×2=512 metres horizontally. It also spans 128×4=512 metres vertically. Its image is rectangular in pixel counts but its coordinate footprint is square under the stated pixel sizes. That distinction is a useful early check: image aspect ratio alone does not establish the aspect ratio of the geographic support.
The matrix width is 3×512=1536 metres, and its height is 4×512=2048 metres. Starting from min_x=1000 gives max_x=2536. Starting from max_y=5000 and moving down 2048 gives min_y=2952. Our declared matrix-set bounds are therefore x from 1000 to 2536 and y from 2952 to 5000.
The published GeoPackage rules connect matrix-set width and height to the products of matrix dimensions, tile dimensions and pixel sizes. Test both axes independently. A correct width does not rescue an incorrect height. In this example, mistakenly using horizontal pixel size for both axes would halve the intended vertical extent while leaving the horizontal calculation unchanged.
Keep numerical tolerance separate from an obvious unit or dimension error. Real floating-point values may need an implementation-appropriate comparison, but a factor-of-two discrepancy is not explained away by harmless rounding. Record the formula, inputs and discrepancy so that another reader can identify whether the disagreement is numerical precision or a different interpretation of the grid.
CHAPTER 4 OF 12
4. Locate a tile using top-left zero-based indexing
GeoPackage tile matrices are numbered from the top-left corner, beginning with column zero and row zero. Columns increase to the right; rows increase downward. In our fictional coordinate plane, x increases to the right and y increases upward, so increasing the tile row decreases its upper y coordinate. Keeping those directions visible prevents a common vertical reversal.
For tile column c and row r, the left boundary is min_x+c×tile_span_x. Its upper boundary is max_y−r×tile_span_y. The right boundary adds one horizontal tile span, and the lower boundary subtracts one vertical span. These equations follow directly from the classroom grid and its declared orientation; they do not require a map renderer.
Take column1, row2. Its left boundary is1000+1×512=1512, and its upper boundary is5000−2×512=3976. The right boundary is2024 and the lower boundary is3464. The tile therefore occupies x1512–2024 and y3464–3976. The row number identifies a band below the top, not a height measured upward from the bottom.
Use an asymmetric control tile when testing software. Tile0,0 is convenient, but some incorrect formulas happen to agree at an origin or central position. Column1,row2 in a three-by-four matrix gives different horizontal and vertical indices and an off-centre location. A deliberately informative fixture can expose errors that many visually regular examples miss.
CHAPTER 5 OF 12
5. Distinguish pixel edges from pixel centres
A tile’s outer corner is not the centre of its first pixel. In a simple area-pixel interpretation of our fixture, the first pixel spans two metres across and four metres down from the upper-left edge. Its centre is one metre right and two metres down. A half-pixel distinction can matter when comparing raster positions with independently located points.
Within tile column1,row2, let pixel column j and pixel row i start at zero. The centre coordinates are x=1512+(j+0.5)×2 and y=3976−(i+0.5)×4. For j=10 and i=20, the centre is(1533,3894). Its cell edges span x1532–1534 and y3892–3896 under the stated area-pixel model.
Now compare that centre with an export that places the same sample at(1532,3896), its upper-left corner. The discrepancy is one metre horizontally and two metres vertically. In this classroom exercise, it is a reference-to-pixel-position mistake, not evidence that the real scene moved. The apparent shift needs a diagnosis before anyone edits the observation.
Do not turn this example into a universal statement about every raster product’s sampling semantics. Point samples, area summaries and particular encoding conventions need their own documented interpretation. The transferable check is to establish whether a coordinate refers to an edge, a centre or another defined location before comparing datasets that use different conventions.
CHAPTER 6 OF 12
6. Treat outer boundaries and neighbouring tiles deliberately
Adjacent tiles share geometric boundaries. The right edge of column1 is the left edge of column2. A point exactly on that edge can be associated with a neighbouring cell according to a declared indexing rule. Without such a rule, a naive lookup can assign the point twice or select an index outside the allowed matrix.
For a paper lookup, use interior points first. A point strictly inside tile column1,row2 should produce those indices under the declared grid equations. Then add boundary points as separate cases. This keeps a clear baseline from being obscured by edge conventions, floating-point representations or the receiving application’s choices about what constitutes a pixel’s support.
A common arithmetic lookup uses a floor operation after measuring an offset from the upper-left origin. At the global far-right boundary, that formula can return the matrix width rather than the last valid column. In our exercise, x=2536 produces column3 although the valid columns are0,1 and2. The boundary needs explicit treatment; silent clamping can hide a wrong input.
State whether your task is locating a sample, finding every intersecting tile or choosing one cell for a point. Those are different relationships. A boundary line may legitimately intersect more than one tile even when a point-assignment routine must choose one. The count of candidate tiles should not be confused with the count of uniquely assigned observations.
CHAPTER 7 OF 12
7. Read each zoom level rather than assuming a universal pyramid
A familiar map pyramid often doubles linear resolution at the next level. GeoPackage can describe other supported arrangements, and level numbers alone are not the pixel sizes. Inspect the actual matrix row for every level used. A zoom label is an address within the dataset’s declared structure, not a guarantee of one universal metres-per-pixel value.
For a second level in our fictional pyramid, halve both pixel sizes to1 and2 metres while keeping tiles256×128 pixels. Each tile now spans256×256 metres. Covering the same1536×2048 matrix-set extent requires six columns and eight rows. The grid has48 potential tile positions rather than12, even though the geographic area has not increased.
That fourfold increase in potential positions follows from doubling the counts along both axes. It does not establish that48 tile rows are actually stored or that the data contains four times as much independent information. Resampling an old image can create more pixels without creating new observations. Spatial resolution, storage density and source evidence need separate descriptions.
Do not treat a missing level as a missing row inside another level. A client may display a neighbouring resolution or resample according to its capabilities. Test the delivered result and record any substitution. A smooth zooming experience can conceal a limitation that matters to a measurement task, particularly when categorical values or sharp boundaries are involved.
CHAPTER 8 OF 12
8. Separate potential tile positions from stored coverage
Our three-column, four-row matrix contains12 potential positions. Suppose only eight positions have stored tile records. The matrix declaration still describes a12-position addressing grid, while the stored population is eight. Neither number alone establishes how much usable observed area is available. You need the positions and the meaning of the actual image content.
A missing tile, a stored fully transparent tile and a stored tile with invalid measurements can produce similar blank areas in one display. They are not identical file states. The absence of a tile record may reflect permitted sparse storage, a deliberate omission or an incomplete delivery. Determine the intended dataset coverage before labelling the absence a defect.
Even eight equally sized stored tiles do not automatically supply eight full tiles of usable observations. Their contents may include masked areas or imagery outside the study region. The raster-validity guide explains how to distinguish readable values from eligible measurements. Grid occupancy is a storage question; usable coverage is a question about evidence within the stored resources.
For a useful completeness report, separate expected tile positions, stored positions, decodable images and task-eligible pixels. Add the source version and study extent. A result reading eight of twelve positions stored answers one question clearly, while the broader claim two-thirds of the landscape was observed would require additional assumptions and actual content checks.
CHAPTER 9 OF 12
9. Diagnose row reversal, wrong scale and wrong reference separately
A vertical flip can arise when a client counts rows upward from the bottom rather than downward from the top. In a four-row matrix, top-based row2 corresponds geometrically to bottom-based row1. Substituting row2 under the bottom-based convention places the tile one band higher than intended in our fixture. The images may remain internally intact throughout.
A scale error has another signature. If the client uses2 metres for the vertical pixel size instead of4, the height of each tile becomes256 metres rather than512. A reference error is different again: the numbers may be internally consistent but interpreted under an incorrect CRS. The connected SRS guide explains why agreement among labels is not independent proof of correct location.
Classify the discrepancy before choosing a repair. Reordering tile records will not fix a wrong pixel size. Changing a CRS label will not correct a reversed row convention. Resampling every image can create an expensive derivative while leaving the addressing error unresolved. A small numerical control set is often more informative than repeatedly adjusting the display until it looks plausible.
Compare an independently justified landmark or source extent where the real task needs geographic accuracy. Our arithmetic proves consistency with a fictional grid definition, not agreement with Earth. A structurally coherent matrix can still be attached to the wrong source location. Keep structural validation and independent positional checking as complementary requirements in the acceptance record.
CHAPTER 10 OF 12
10. Build a repeatable grid-validation fixture
A practical fixture should include the top-left tile, an off-centre tile, the last valid row and column, an interior pixel centre and an outer-boundary point. State expected coordinates before opening the file. The set should expose row direction, index origin, both pixel sizes and edge treatment without needing hundreds of images or an elaborate interface.
Check stored tile addresses against their level’s matrix dimensions. Valid columns run from zero through matrix_width minus one, with a corresponding range for rows. Inspect the actual tile’s decoded dimensions and encoding under the applicable specification. A valid address does not establish that the resource occupying it has the required image structure.
Next reopen the saved test copy using the intended receiving reader. Compare the displayed or queried positions with the independent calculations. Record the software and relevant options. A preview in the writer’s memory is not the saved artifact, and two applications sharing the same undocumented override may agree without validating the underlying package declarations.
Retain the test inputs, formulas, expected positions, observed outputs and unresolved differences. Do not describe a small successful fixture as a complete conformance certificate. Its purpose is narrower and valuable: it establishes that the tested addressing and interpretation path behaves as intended for the declared cases, while leaving other requirements to their own validation.
CHAPTER 11 OF 12
11. Transfer the grid into another representation without losing meaning
Exporting tile images as ordinary picture files preserves their pixels but can discard their spatial addresses. A folder of PNG images is not automatically a geographically interpretable dataset. If the task requires location, preserve or reconstruct the relevant reference information, grid positions and transformation evidence through a supported export route.
A change in target format can also alter pixel interpretation, available metadata, compression or invalid-data treatment. Compare what the exporter actually saved rather than assuming that a successful progress bar means every spatial dependency survived. Open the delivered output and test representative positions, values and masks under the intended recipient’s workflow.
For a changed-context exercise, hand a colleague the eight stored classroom images without the matrix table. They may reconstruct a visually plausible mosaic, but several placements can fit the pictures. Add the tile addresses, reference definition and level-specific grid information. The interpretation becomes reproducible because the missing contract has been restored, not because the pictures became sharper.
Where an export resamples data, state the method and its consequences. A method suitable for a continuous image may be inappropriate for categorical classes. The connected resampling guide explains that distinction. Correct tile addressing is necessary for placing a resource, but it does not authorise every later numerical operation on that resource.
CHAPTER 12 OF 12
12. Deliver a grid explanation that another reader can check
A clear handoff names the table, matrix-set reference and bounds, levels used, tile and matrix dimensions, pixel sizes, stored coverage and known limits. Include at least one independently calculable tile position. A note saying the map aligns leaves the recipient dependent on your screenshot and on assumptions the screenshot cannot reveal.
Ask the reader to locate a new off-centre tile without copying the earlier worked result. They should explain why a row increment moves downward, why one tile spans its stated width and height, and why more potential cells at a finer level do not establish new observations. That is a transfer check rather than a memorisation exercise.
Keep repair history explicit. Say whether an error involved addresses, declarations, actual image content or a receiving client’s interpretation. Preserve the original package and use authorised copies for diagnosis. Do not rewrite production tile tables or remove unfamiliar structures merely because a classroom formula suggests a likely cause.
The practical endpoint is a grid whose numbers tell the same story as its intended positions. You can explain where a tile belongs, what a pixel represents under the documented model and which parts of the area actually have usable evidence. The map becomes an inspectable geographic product rather than a collection of pictures that happen to open.
Independent worked case and evidence checks
Try a second independent fictional matrix. Its bounds are x0–1800 and y0–1200 in a stated local metre plane. Each tile contains300 columns and200 rows of pixels. Horizontal pixel size is2 metres and vertical pixel size is3 metres. Work out the tile spans and matrix dimensions before looking at any tile address.
Each tile spans300×2=600 metres across and200×3=600 metres down. The full grid therefore needs three columns and two rows. Its six potential addresses run across columns0,1,2 and down rows0,1. A square coordinate footprint has again been represented by a rectangular image array because the two pixel sizes differ.
Tile column2,row1 begins at x1200 and upper y600. Its footprint is x1200–1800 and y0–600. Under the declared area-pixel exercise, its first pixel centre is(1201,598.5). Pixel column100,row50 has centre x1200+100.5×2=1401 and y600−50.5×3=448.5.
Now deliberately swap horizontal and vertical pixel sizes during interpretation. The resulting tile span becomes900 metres wide and400 metres high. Those spans no longer reproduce the declared matrix-set width and height. This failure is visible through arithmetic before a single image is drawn. It is not a harmless alternative display of the same declared grid.
Suppose only four of the six potential tile positions are stored. One of those four images is entirely invalid for the measurement task. The file has four stored tile records, while task-eligible support is less than four full tile footprints. A renderer showing three colourful patches cannot by itself tell you which missing areas arose from absent records and which from invalid content.
For transfer, change the tile dimensions to150×100 pixels and keep pixel sizes unchanged. A tile now spans300×300 metres. Covering the same extent requires six columns and four rows, or24 potential positions. Explain why changing tile packaging can multiply the number of files without changing geographic extent or adding any new source observations.
Finally place a query point on the far-right outer boundary x1800. A naive floor-based lookup produces column3 in the original three-column grid. The correct handling depends on the declared boundary task and receiving contract. Record that decision explicitly and keep it separate from the unambiguous interior-pixel tests that established the basic addressing arithmetic.
Return to the first matrix for one more independent check. It has768 pixel columns across the entire width and512 pixel rows down the entire height. Its outer edges are x1000 and2536, while the first and last pixel centres lie at x1001 and2535 under the declared area-pixel model. Vertically, the outer edges are y5000 and2952, while the corresponding centres are4998 and2954. Explain why centre bounds and outer-edge bounds differ without describing either pair as a rounding error.
Worked comparison
| Quantity | Unit or role | Fictional first matrix |
|---|---|---|
| Matrix dimensions | Tiles across and down | 3×4 potential positions |
| Tile dimensions | Pixels across and down | 256×128 |
| Pixel sizes | Reference units per pixel | 2 metres and4 metres |
| Tile footprint | Reference-coordinate span | 512×512 metres |
| Matrix footprint | Whole declared grid | 1536×2048 metres |
| Stored records | Actual occupied addresses | Not implied by matrix dimensions |
Questions and practical checks
Does row zero start at the bottom?
Not in the GeoPackage tile-matrix convention discussed here. Numbering starts at the top left, with rows increasing downward.
Must tiles and pixels be square?
Do not assume that. Read tile width, tile height and both pixel sizes from the actual matrix declarations.
Does a matrix with twelve positions contain twelve tiles?
Not necessarily. Sparse storage is possible; inspect the actual stored addresses and intended coverage.
Is a tile corner the first pixel centre?
No under the declared area-pixel exercise. Establish the applicable pixel interpretation before comparing coordinates.
Does a correct grid prove scientific accuracy?
No. It establishes aspects of placement and internal consistency. Source location, calibration, masks and suitability for the task require additional evidence.
Continue with the connected subjects
Preserve file and coordinate meaning
GeoPackage structure: distinguish language edits from spatial transformations
GeoPackage SRS consistency: declarations versus independently justified positions
Check the evidence inside the grid
Raster masks: stored values versus task-eligible support
Vector tiles: a different relationship between tiles and source objects
Categorical resampling: protect class meaning during image operations
Sources and scope
Published OGC GeoPackage1.4.0: tile matrix sets, matrix dimensions, pixel sizes and tile addresses
SQLite inspection pragmas: distinguish database checks from geographic interpretation
The numerical cases in this guide are original fictional teaching examples, not measurements from a real site. This is an educational explanation, not a field safety instruction, engineering approval or an official certification. For a real project, use qualified practitioners, current product documentation and site-specific evidence. Sources were checked on 30 October 2026.
Connect the time, grid and file checks
These guides cover different dependencies in one geographic information chain. A successful result at one stage does not replace the evidence needed at another. Choose the check that matches the unresolved question.
STAC times: observation, capture range and metadata maintenance. Keep observation time distinct from later maintenance before combining geographically aligned resources.
Foreign keys: orphan references and the limits of integrity checks. Check declared relationships and independently justified associations rather than relying on one healthy-file result.
Extension scope: operation-specific reading and editing support. Establish what the receiving reader or writer supports before treating a successful preview as complete interoperability.