# bracket-geometry

This crate provides geometry support for the overall `bracket-lib` system, and is useful stand-alone. It provides some geometric primitives (`Point`, `Point3D`, `Rect`), support functions and distance calculations. It also includes Bresenham's line algorithm, a vector line algorithm, and Bresenham's Circle algorithm.

It uses UltraViolet for fast processing, and includes conversion functions to/from native UltraViolet types.

## Using bracket-geometry

You can include it in your project by adding the following to your `Cargo.toml` file:

```toml
[dependencies]
bracket-geometry = "~0.8"
```

## Point2D

A basic 2D (integer) point. You can create points with:

* `new`: Create a point with any integer-compatible type (it will be `i32` internally, but uses `TryFrom`).
* `zero`: a `(0,0)` point.
* `from_tuple`: takes a `(i32, i32)` tuple.

It also provides conversion to other types:

* `to_index` for simple array striding (use the `bracket-algorithm-traits` crate for better implementations).
* `to_tuple` converts to an `(i32, i32)` tuple.
* `to_unsigned_tuple` converts to a `(usize, usize)` tuple.
* `to_vec2` converts to an UltraViolet `Vec2`.
* `to_vec2i` converts to an UltraViolet `Vec2i`.

`From` is also implemented for these.

## Point3D

A basic 3D (integer) point. You can create points with:

* `new`: Create a point from any integer-compatible type (x/y/z).
* `from_tuple`: Creates a point from an `(i32,i32,i32)` tuple.

It also provides conversion to UltraViolet's `Vec3` and `Vec3i` types.

## Rectangle (`Rect`)

Represents a rectangle in 2D space. You can create rectangles with:

* `with_size`: provide an X/Y and a width/height.
* `with_exact`: provide all four coordinates.
* `zero`: a zeroed rectangle.

It provides quite a few helper functions:

* `intersect` - does this rectangle intersect with another rectangle?
* `center` - the middle point of the rectangle.
* `point_in_rect` - is a point inside the rectangle (including edges)?
* `for_each` - call a passed lambda/callback for each point in the rectangle.
* `point_set` - returns a `HashSet` of all points in the rectangle.
* `width` and `height` return the current dimensions of the rectangle.

## Line Plotting

Line plotting is provided using Bresenham and vector algorithms. You can return points in the line as either a vector of `Point` objects, or an iterator.

For example, returning a line as a vector:

```rust
use bracket_geometry::prelude::*;
let bresenham_line = line2d(LineAlg::Bresenham, Point::new(1,1), Point::new(5,5));
println!("{:?}", bresenham_line);
```

Or iterating along the points:

```rust
use bracket_geometry::prelude::*;
for point in Bresenham::new(Point::new(1,1), Point::new(5,5)) {
    println!("{:?}", point);
}
```

You can substitute `LineAlg::Bresenham` with `LineAlg::Vector` to use a simple vector-based projection instead (this is faster on some systems).

## Circle Plotting

Bresenham's circle algorithm is also included. For example:

```rust
use bracket_geometry::prelude::*;
for point in BresenhamCircle::new(Point::new(10,10), 5) {
    println!("{:?}", point);
}
```

## Distance Heuristics

There's a full set of distance algorithms available:

```rust
use bracket_geometry::prelude::*;
println!("{:?}", DistanceAlg::Pythagoras.distance2d(Point::new(0,0), Point::new(5,5)));
println!("{:?}", DistanceAlg::PythagorasSquared.distance2d(Point::new(0,0), Point::new(5,5)));
println!("{:?}", DistanceAlg::Manhattan.distance2d(Point::new(0,0), Point::new(5,5)));
println!("{:?}", DistanceAlg::Chebyshev.distance2d(Point::new(0,0), Point::new(5,5)));
```

## Feature Flags

If you enable `serde`, it provides serialization/de-serialization via the `Serde` library for the `Point`, `Point3D` and `Rect` types.

## Examples

The following examples are included; they use `crossterm` to print to your terminal. Run examples with `cargo run --example <name>`:

* `bresenham_circle` - draws a circle.
* `bresenham_line` - draws a line.
* `vector_line` - draws a line, using an algorithm that doesn't smooth corners.
* `distance` - calculates distance between two points with all supported algorithms and outputs it.