[−][src]Crate hexeng

hexeng: a crate for handling hexagonal tilings / grids / tesselation.

Provides calculations on hexagonal tiles, using nalgebra for underlying linear algebra and data structures.

Coordinate frames

The core concept of this crate is the coordinate frame, represented by the Frame trait. There are three coordinate frames:

It is possible to convert coordinates between a pair of frames. The conversion from Axial to World determines a 2D Euclidean location for each hexagon on the grid. The conversion from World to View is intended to allow the grid to be displayed with arbitrary scale/rotation (etc) on a display.

Axial to/from World conversions

The axial coordinates are pairs of integers like 0, 1, or -10, -4. The conversion to the "World" frame is a fixed mapping shown in the image below.

The choice of geometry in the World frame is to make the conversion convenient. An explanation of the full conversion algorithm can be found here.

Converting from a World coordinate to Axial coordinates will find the hexagon that contains that world coordinate. Converting from the Axial coordinate back to World coordinates will find the origin of the specified hexagon, i.e. the 0, 0 point on the geometry shown below:

This means that the point retrieved by the Axial to World conversion is not inside the hexagon at that axial address. The following example may clarify this further:

use hexeng::{World, Axial, Recast, ViewTransform};
use nalgebra::Matrix3;

// To use the Recast trait, we must define the View transform (but
// since we are not using the View frame in this example, its value is
// not important - just use the identity matrix).
let view_transform = Matrix3::identity();

// World point 1.5, 6.0 is inside the 1, 3 hexagon
let world = World::from([1.5, 6.0]);
let axial: Axial = world.recast(&view_transform);
assert_eq!(axial.as_slice(), &[1, 3]);

// The "origin coordinate" of the 1, 3 hexagon is found
// by converting back to world coordinates. Note that the
// origin is actually *not* inside the 1, 3 hexagon as it is
// at the lower left corner!
let origin: World = axial.recast(&view_transform);
assert_eq!(origin.as_slice(), &[1.0, 5.0]);
assert_eq!(Recast::<Axial>::recast(origin, &view_transform).as_array(), [0, 2]);

World to/from View coordinates

The conversion between world and view is defined by a transformation that must be supplied to the recast method by way of the ViewTransform trait.

The transformation should be specified using the geometry system provided by the nalgebra crate.

use hexeng::{World, View, Recast, ViewTransform};
use nalgebra::{Vector2, Matrix3};

fn get_transform(translation: [f64; 2], scale: [f64; 2]) -> Matrix3<f64> {
    Matrix3::identity()
        .append_translation(&Vector2::from(translation))
        .append_nonuniform_scaling(&Vector2::from(scale))
}

let world = World::from([2.0, 3.5]);
let view: View = world.recast(&get_transform([0.1, 0.2], [1., 1.]));
assert_eq!(view.as_slice(), &[2.1, 3.7]);

// Converting from view to world applies the inverse transform
let view = View::from([2.0, 3.5]);
let world: World = view.recast(&get_transform([0., 0.], [0.5, 0.5]));
assert_eq!(world.as_slice(), &[4.0, 7.0]);

Structs

Frame

An object representing a point within a specified frame.

Enums

TAxial

Used to identify Frame objects that are in Axial coordinates by typing.

TView

Used to identify Frame objects that are in View coordinates by typing.

TWorld

Used to identify Frame objects that are in World coordinates by typing.

Traits

AnyFrame

Trait implemented by all the frame types (Axial, View and World).

Recast

Implemented by Frame objects, to allow converting to other frames

ViewTransform

Implemented by objects that can be treated as transformations between world/view coordinates.

Type Definitions

Axial

Axial coordinates

View

View coordinates

World

World coordinates