Struct CellMap

pub struct CellMap<L, T>
where
    L: Layer,
{ /* private fields */ }

Provides a many-layer 2D map of cellular data.

Implementations

impl<L, T> CellMap<L, T>

where L: Layer,

pub fn new_from_data( params: CellMapParams, data: Vec<Array2<T>>, ) -> Result<Self, Error>

Creates a new map from the given data.

If data is the wrong shape or has the wrong number of layers this function will return an error.

pub fn cell_size(&self) -> Vector2<f64>

Returns the size of the cells in the map.

pub fn num_cells(&self) -> Vector2<usize>

Returns the number of cells in each direction of the map.

pub fn cell_bounds(&self) -> Bounds

Returns the bounds of this map

pub fn params(&self) -> CellMapParams

Returns the parameters used to build this map.

pub fn to_parent(&self) -> Affine2<f64>

Gets the nalgebra::Affine2<f64> transformation between the map frame and the parent frame.

pub fn move_map( &mut self, position_in_parent: Vector2<f64>, rotation_in_parent_rad: f64, )

Moves this map relative to a new position and rotation relative to the parent frame.

Note: This doesn’t move the data relative to the map origin, the indexes into the map remain the same, but the position of each cell in the map will change.

pub fn index_in_map(&self, index: Point2<usize>) -> bool

Returns whether or not the given index is inside the map.

pub fn position_in_map(&self, position: Point2<f64>) -> bool

Returns whether or not the given parent-relative position is inside the map.

pub fn get(&self, layer: L, index: Point2<usize>) -> Option<&T>

Get a reference to the value at the given layer and index. Returns None if the index is outside the bounds of the map.

pub unsafe fn get_unchecked(&self, layer: L, index: Point2<usize>) -> &T

Get a reference to the value at the given layer and index, without checking the bounds of the map.

Safety

This function will panic if index is outside the map.

pub fn get_mut(&mut self, layer: L, index: Point2<usize>) -> Option<&mut T>

Get a mutable reference to the value at the given layer and index. Returns None if the index is outside the bounds of the map.

pub unsafe fn get_mut_unchecked( &mut self, layer: L, index: Point2<usize>, ) -> &mut T

Get a mutable reference to the value at the given layer and index, without checking the bounds of the map.

Safety

This function will panic if index is outside the map.

pub fn set( &mut self, layer: L, index: Point2<usize>, value: T, ) -> Result<(), Error>

Set the given layer and index in the map to the given value. Returns an Error if the index was outside the map.

pub unsafe fn set_unchecked(&mut self, layer: L, index: Point2<usize>, value: T)

Set the given layer and index in the map to the given value, without checking if index is the map.

Safety

This function will panic if index is outside the map

pub fn position(&self, index: Point2<usize>) -> Option<Point2<f64>>

Returns the position in the parent frame of the centre of the given cell index.

Returns None if the given index is not inside the map.

pub fn position_unchecked(&self, index: Point2<usize>) -> Point2<f64>

Returns the position in the parent frame of the centre of the given cell index, without checking that the index is inside the map.

Safety

This method won’t panic if index is outside the map, but it’s result can’t be guaranteed to be a position in the map.

pub fn index(&self, position: Point2<f64>) -> Option<Point2<usize>>

Get the cell index of the given poisition.

Returns None if the given position is not inside the map.

pub unsafe fn index_unchecked(&self, position: Point2<f64>) -> Point2<isize>

Get the cell index of the given poisition, without checking that the position is inside the map.

Safety

This function will not panic if position is outside the map, but use of the result to index into the map is not guaranteed to be safe. It is possible for this function to return a negative index value, which would indicate that the cell is outside the map.

pub fn iter(&self) -> CellMapIter<'_, L, T, Many<L>, Cells>

Returns an iterator over each cell in all layers of the map.

pub fn iter_mut(&mut self) -> CellMapIterMut<'_, L, T, Many<L>, Cells>

Returns a mutable iterator over each cell in all layers of the map.

pub fn window_iter( &self, semi_width: Vector2<usize>, ) -> Result<CellMapIter<'_, L, T, Many<L>, Windows>, Error>

Returns an iterator over windows of cells in the map.

The semi_width is half the size of the window in the x and y axes, not including the central cell. E.g. to have a window which is in total 5x5, the semi_window_size needs to be Vector2::new(2, 2).

pub fn window_iter_mut( &mut self, semi_width: Vector2<usize>, ) -> Result<CellMapIterMut<'_, L, T, Many<L>, Windows>, Error>

Returns a mutable iterator over windows of cells in the map.

The semi_width is half the size of the window in the x and y axes, not including the central cell. E.g. to have a window which is in total 5x5, the semi_window_size needs to be Vector2::new(2, 2).

pub fn line_iter( &self, start_position: Point2<f64>, end_position: Point2<f64>, ) -> Result<CellMapIter<'_, L, T, Many<L>, Line>, Error>

Returns an iterator over cells along the line joining start_position and end_position, which are expressed as positions in the map’s parent frame.

pub fn line_iter_mut( &mut self, start_position: Point2<f64>, end_position: Point2<f64>, ) -> Result<CellMapIterMut<'_, L, T, Many<L>, Line>, Error>

Returns a mutable iterator over cells along the line joining start_position and end_position, which are expressed as positions in the map’s parent frame.

impl<L, T> CellMap<L, T>

where L: Layer + Serialize, T: Clone + Serialize,

pub fn to_cell_map_file(&self) -> CellMapFile<L, T>

Builds a new CellMapFile from the given map, which can be serialised or deserialised using serde.

pub fn write_json<P: AsRef<Path>>(&self, path: P) -> Result<(), Error>

Writes the map to the given path as a JSON file.

impl<L, T> CellMap<L, T>

where L: Layer + DeserializeOwned, T: DeserializeOwned,

pub fn from_json<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Loads a map stored in JSON format at the given path.

impl<L, T> CellMap<L, T>

where L: Layer, T: Clone,

pub fn new_from_elem(params: CellMapParams, elem: T) -> Self

Creates a new CellMap from the given params, filling each cell with elem.

impl<L, T> CellMap<L, T>

where L: Layer, T: Default + Clone,

pub fn new(params: CellMapParams) -> Self

Creates a new CellMap from the given params, filling each cell with T::default().

Examples found in repository

examples/map_rotations_check.rs (lines 16-21)

fn main() {
    let translated = CellMap::<Layers, f64>::new(CellMapParams {
        cell_size: Vector2::new(1.0, 1.0),
        cell_bounds: Bounds::new((0, 10), (0, 10)).unwrap(),
        position_in_parent: Vector2::new(5.0, 5.0),
        ..Default::default()
    });

    let rotated = CellMap::<Layers, f64>::new(CellMapParams {
        cell_bounds: Bounds::new((0, 10), (0, 10)).unwrap(),
        cell_size: Vector2::new(1.0, 1.0),
        position_in_parent: Vector2::new(5.0, 5.0),
        rotation_in_parent_rad: std::f64::consts::FRAC_PI_4,
        ..Default::default()
    });

    let scaled = CellMap::<Layers, f64>::new(CellMapParams {
        cell_bounds: Bounds::new((0, 10), (0, 10)).unwrap(),
        cell_size: Vector2::new(0.5, 0.5),
        position_in_parent: Vector2::new(5.0, 5.0),
        rotation_in_parent_rad: std::f64::consts::FRAC_PI_4,
        ..Default::default()
    });

    #[cfg(all(feature = "debug_maps"))]
    {
        use cell_map::write_debug_map;

        write_debug_map(&translated, "translated");
        write_debug_map(&rotated, "rotated");
        write_debug_map(&scaled, "scaled");
    }
}

pub fn resize(&mut self, new_bounds: Bounds)

Resizes the map into the new bounds, filling any newly added cells with T::default().

Any cells that are in the map currently, which would be outside the new map, are removed.

pub fn merge<F: Fn(&T, &[T]) -> T>(&mut self, other: &CellMap<L, T>, func: F)

Merge other into self, resizing self so that other will be fully included in the map.

Both maps should belong to the same parent frame, and other.cell_size <= self.cell_size. For others that have larger cells than self you should implement your own merge functon based on this one that could for example use 2D linear interpolation.

func is responsible for actually merging data in both self and other into a single new value in self. The first argument is the value of the cell in self, while the second argument will be the values from cells in other whose centres lie within the cell in self.

Trait Implementations

impl<L, T: Clone> Clone for CellMap<L, T>

where L: Layer + Clone,

fn clone(&self) -> CellMap<L, T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<L, T: Debug> Debug for CellMap<L, T>

where L: Layer + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, L, T> Deserialize<'de> for CellMap<L, T>

where L: Layer + Serialize + DeserializeOwned, T: Clone + Serialize + DeserializeOwned,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<L, T> From<CellMap<L, T>> for CellMapFile<L, T>

where L: Layer + Serialize, T: Clone + Serialize,

fn from(map: CellMap<L, T>) -> Self

Converts to this type from the input type.

impl<L, T> Index<(L, Point<usize, U2>)> for CellMap<L, T>

where L: Layer,

type Output = T

The returned type after indexing.

fn index(&self, index: (L, Point2<usize>)) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<L, T> Index<L> for CellMap<L, T>

where L: Layer,

type Output = ArrayBase<OwnedRepr<T>, Dim<[usize; 2]>>

The returned type after indexing.

fn index(&self, index: L) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<L, T> IndexMut<(L, Point<usize, U2>)> for CellMap<L, T>

where L: Layer,

fn index_mut(&mut self, index: (L, Point2<usize>)) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<L, T> IndexMut<L> for CellMap<L, T>

where L: Layer,

fn index_mut(&mut self, index: L) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<L, T> Serialize for CellMap<L, T>

where L: Layer + Serialize + DeserializeOwned, T: Clone + Serialize + DeserializeOwned,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<L, T> TryFrom<CellMapFile<L, T>> for CellMap<L, T>

where L: Layer,

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: CellMapFile<L, T>) -> Result<Self, Self::Error>

Performs the conversion.