# @swim/math

**@swim/math** implements common mathematical and geometric structures and
operators. **@swim/math** implements vectors, points, lines, and shapes, with
standard algebraic and computational geometry operators, including containment
and intersection testing. **@swim/math** is part of the
**@swim/core** framework.

## Overview

**@swim/math** defines standard types for linear and affine algebraic
structures and operators, as well as generic geometric shape interfaces.

### Shapes

The `Shape`

interface provides a base type for geometric shapes that can be
containment and intersection tested. The `Shape.fromAny`

factory method
coerces plain JavaScript objects, of type `AnyShape`

, to polymorphic `Shape`

instances.

```
Shape.fromAny({x: 2, y: 3});
// PointR2.of(2, 3)
Shape.fromAny({x0: 0, y0: 1, x1: 1, y1: 0});
// SegmentR2.of(0, 1, 1, 0)
Shape.fromAny({xMin: 0, yMin: 0, xMax: 1, yMax: 1});
// BoxR2.of(0, 0, 1, 1)
Shape.fromAny({cx: 0, cy: 0, r: 1});
// CircleR2.of(0, 0, 1)
```

### 2D Real Space

The `R2Shape`

base class extends `Shape`

with 2D-specific operations.
`PointR2`

, `SegmentR2`

, `BoxR2`

, and `CircleR2`

make up the standard `R2Shape`

implementations. `VectorR2`

represents a vector in 2D real space.

```
PointR2.of(2, 3).plus(VectorR2.of(1, -1));
// PointR2.of(3, 2)
PointR2.of(3, 2).minus(PointR2.of(2, 3));
// VectorR2.of(1, -1)
CircleR2.of(3, 3, 2).intersects(egmentR2.of(0, 0, 4, 4));
// true
CircleR2.of(3, 3, 2).contains(SegmentR2.of(0, 0, 4, 4));
// false
CircleR2.of(3, 3, 2).contains(SegmentR2.of(3, 3, 4, 4));
// true
```

`R2Function`

represents a linear map, and `R2Operator`

corresponds to an
invertible linear operator.

## Installation

### npm

For an npm-managed project, `npm install @swim/math`

to make it a dependency.
TypeScript sources will be installed into `node_modules/@swim/math/main`

.
Transpiled JavaScript and TypeScript definition files install into
`node_modules/@swim/math/lib/main`

. And a pre-built UMD script can
be found in `node_modules/@swim/math/dist/main/swim-math.js`

.

### Browser

Browser applications can load `swim-core.js`

, which comes bundled with the
**@swim/math** library, directly from the SwimOS CDN.

```
<!-- Development -->
<script src="https://cdn.swimos.org/js/latest/swim-core.js"></script>
<!-- Production -->
<script src="https://cdn.swimos.org/js/latest/swim-core.min.js"></script>
```

Alternatively, the standalone `swim-system.js`

script may be loaded
from the SwimOS CDN, which bundles **@swim/math** together with all other
**@swim/system**
libraries.

```
<!-- Development -->
<script src="https://cdn.swimos.org/js/latest/swim-system.js"></script>
<!-- Production -->
<script src="https://cdn.swimos.org/js/latest/swim-system.min.js"></script>
```

## Usage

### ES6/TypeScript

**@swim/math** can be imported as an ES6 module from TypeScript and other
ES6-compatible environments.

`import * as math from "@swim/math";`

### CommonJS/Node.js

**@swim/math** can also be used as a CommonJS module in Node.js applications.

`var math = require("@swim/math");`

### Browser

When loaded by a web browser, the `swim-core.js`

script adds all
**@swim/math** library exports to the global `swim`

namespace.

The `swim-system.js`

script also adds all **@swim/math** library exports
to the global `swim`

namespace, making it a drop-in replacement for
`swim-core.js`

when additional **@swim/system** libraries are needed.