MapProjection

Axis-aligned linear projection engine converting between external world coordinates and MapCanvas internal map coordinates.

Overview

MapProjection performs fast axis-aligned linear transformations between external game world coordinates and internal MapCanvas map coordinates.

Transformation model: - mapX = worldX * scaleX + offsetX - mapY = worldY * scaleY + offsetY

Calibration: - Direct creation via explicit scale and offset values (MapProjection(scaleX, offsetX, scaleY, offsetY)). - Calibration from two calibration point pairs using MapProjection.axisAligned(...) or the fluent builder MapProjection.affine().

Calibrating World to Map Coordinate Projection

MapProjection projection = MapProjection.affine()
    .worldPoint(-1000, -1000).mapPoint(0, 0)
    .worldPoint(1000, 1000).mapPoint(2048, 2048)
    .build();

Related links

• MapCanvas: Interactive 2D map widget extending WorldCanvas with map sizing, texture and grid layers, coordinate projection, and marker handles.
• WorldCanvas: Infinite 2D/3D world canvas supporting camera pan and zoom, coordinate transformations, background world layers, and pinned screen-space anchor widgets.

API

MapProjection(float, float, float, float)

Constructs a MapProjection directly with explicit scale and offset values.

Parameter	Type	Description
scaleX	float	Horizontal scale factor.
offsetX	float	Horizontal translation offset.
scaleY	float	Vertical scale factor.
offsetY	float	Vertical translation offset.

MapProjection::affine()

Starts fluent builder configuration of a projection via world-to-map calibration points.

Returns Builder: A new projection Builder instance..

MapProjection::axisAligned(float, float, float, float, float, float, float, float)

Constructs an axis-aligned projection calibrated from two world-to-map point pairs.

Parameter	Type	Description
worldX1	float	World X coordinate of the first calibration point.
worldY1	float	World Y coordinate of the first calibration point.
mapX1	float	Map X coordinate corresponding to worldX1.
mapY1	float	Map Y coordinate corresponding to worldY1.
worldX2	float	World X coordinate of the second calibration point.
worldY2	float	World Y coordinate of the second calibration point.
mapX2	float	Map X coordinate corresponding to worldX2.
mapY2	float	Map Y coordinate corresponding to worldY2.

Returns MapProjection: The constructed MapProjection instance..

MapProjection::identity()

Returns the identity projection where world coordinates map 1:1 to map coordinates.

Returns MapProjection: The constructed MapProjection instance..

MapProjection::mapX(float)

Transforms an external world X coordinate into map X coordinate space.

Parameter	Type	Description
worldX	float	World X coordinate.

Returns float: The floating-point coordinate or dimension value..

MapProjection::mapY(float)

Transforms an external world Y coordinate into map Y coordinate space.

Parameter	Type	Description
worldY	float	World Y coordinate.

Returns float: The floating-point coordinate or dimension value..

MapProjection::offsetX()

Returns the horizontal X translation offset.

Returns float: The axis translation offset..

MapProjection::offsetY()

Returns the vertical Y translation offset.

Returns float: The axis translation offset..

MapProjection::project(float, float)

Transforms external world coordinates into a 2D map point.

Parameter	Type	Description
worldX	float	World X coordinate.
worldY	float	World Y coordinate.

Returns ViewportPoint: Transformed 2D coordinate point..

MapProjection::scaleX()

Returns the horizontal X scale factor.

Returns float: The axis scale factor..

MapProjection::scaleY()

Returns the vertical Y scale factor.

Returns float: The axis scale factor..

MapProjection::unproject(float, float)

Inverse transforms a map coordinate point back into external world coordinates.

Parameter	Type	Description
mapX	float	Map X coordinate.
mapY	float	Map Y coordinate.

Returns ViewportPoint: Transformed 2D coordinate point..

MapProjection::worldX(float)

Inverse transforms a map X coordinate back into external world X space.

Parameter	Type	Description
mapX	float	Map X coordinate.

Returns float: The floating-point coordinate or dimension value..

MapProjection::worldY(float)

Inverse transforms a map Y coordinate back into external world Y space.

Parameter	Type	Description
mapY	float	Map Y coordinate.

Returns float: The floating-point coordinate or dimension value..