gale.tilemap.isometric module

This file contains the isometric counterpart of gale.tilemap.tilemap: cartesian_to_isometric/isometric_to_cartesian (the cartesian <-> isometric screen-space conversion every diamond-grid project ends up writing by hand — useful on their own for any isometric coordinate math, not just tile maps) and IsometricTileMap, a TileMap subclass that renders its grid as a 2:1 diamond projection instead of an axis-aligned one.

Author: Alejandro Mujica (aledrums@gmail.com)

gale.tilemap.isometric.cartesian_to_isometric(x, y, tile_width, tile_height)[source]

Converts a cartesian grid-space position (in tile units — x is the column, y is the row, either can be fractional) into isometric screen-space pixel coordinates, using the standard 2:1 diamond projection.

Parameters:

  • x (float) – A grid-space x coordinate, in tile units (column).

  • y (float) – A grid-space y coordinate, in tile units (row).

  • tile_width (int) – The width, in pixels, of a diamond tile.

  • tile_height (int) – The height, in pixels, of a diamond tile.

Returns:

The equivalent (screen_x, screen_y) in pixels.

Return type:

Tuple[float, float]

gale.tilemap.isometric.isometric_to_cartesian(screen_x, screen_y, tile_width, tile_height)[source]

The exact inverse of cartesian_to_isometric: turns an isometric screen-space pixel position back into a cartesian grid-space one (in tile units).

Parameters:

  • screen_x (float) – A screen-space x coordinate, in pixels.

  • screen_y (float) – A screen-space y coordinate, in pixels.

  • tile_width (int) – The width, in pixels, of a diamond tile.

  • tile_height (int) – The height, in pixels, of a diamond tile.

Returns:

The equivalent (x, y) in grid space (tile units).

Return type:

Tuple[float, float]

class gale.tilemap.isometric.IsometricTileMap(tile_width, tile_height, cols, rows)[source]

Bases: TileMap

A TileMap rendered as a 2:1 isometric diamond grid rather than an axis-aligned one — same rows x cols grid(s) of gids, same tileset(s)/layers/object_layers API, only the projection from (row, col) to pixels (and back) changes.

Conventions used throughout this class:

  • (row 0, col 0) sits at the map’s top corner (the diamond’s topmost point on screen), with row increasing toward the bottom-left and col increasing toward the bottom-right — the usual isometric “diamond” layout.

  • position_of(row, col) returns that cell’s diamond’s top vertex (not a bounding-box top-left corner), shifted right by origin_x = (rows - 1) * tile_width / 2 so the whole map’s top vertex column never goes negative.

  • Tile images are anchored at their top-center: the pixel position_of returns is where the top-center point of the tile_width x tile_height source image should land. render() accounts for this by blitting at (position_of(row, col)[0] - tile_width / 2, position_of(row, col)[1]).

Because row + col increases monotonically along a plain row-major (row ascending, then col ascending) iteration, that iteration order already paints back-to-front for a diamond grid — no extra sort is needed, unlike a general isometric scene with freely-placed entities.

Usage example:

tileset = Tileset(tiles_image, tile_width=64, tile_height=32, first_gid=1) tilemap = IsometricTileMap(tile_width=64, tile_height=32, cols=20, rows=20) tilemap.add_tileset(tileset) ground = tilemap.add_layer(“ground”) ground[5][10] = 1

# Every frame: tilemap.render(surface, camera)

Parameters:

  • tile_width (int)

  • tile_height (int)

  • cols (int)

  • rows (int)

property pixel_width: int
property pixel_height: int
position_of(row, col)[source]
Parameters:

  • row (int) – A tile row.

  • col (int) – A tile column.

Returns:

The screen/world pixel position of that cell’s diamond’s top vertex (see the class docstring for the anchor/origin convention).

Return type:

Tuple[float, float]

tile_at(x, y)[source]
Parameters:

  • x (float) – A screen/world x position, in pixels.

  • y (float) – A screen/world y position, in pixels.

Returns:

The (row, col) of the tile whose diamond contains that point (not clamped to this map’s bounds — check in_bounds if the point might fall outside it).

Return type:

Tuple[int, int]

render(surface, camera=None)[source]
Parameters:

  • surface (Surface) – The surface to draw every layer onto.

  • camera (Any | None) – A gale.camera.Camera to translate/scale tiles through and cull whatever falls outside its viewport. The default value is None, rendering the whole map at a 1:1 scale starting at (0, 0).

Return type:

None