v2 - A Minimalistic 2D Symplectic Vector Space JavaScript Class

A short overview about symplectic geometry in vector space ℝ² is given in this Cheat Sheet. If you want to learn more, read this. In a nutshell:

"The standard inner (dot) product together with an orthogonal operator is the symplectic inner product."

Symplectic geometry is a geometry of even dimensional spaces in which area measurements, rather than length measurements, are the fundamental quantities. Benefits are:

• Symplectic geometry is coordinate free, i.e. coordinates aren't needed except weexplicitly want them.
• The definition of an explicit origin is not required.
• Transformation matrices are rarely need. Similarity transformation mostly does what we want.

v2 class library in its version 3.0 has undergone considerable changes. We now have v2 objects as well as v2 static functions. Latter work with arbitrary objects as long as these expose x and y members or x and y getters and setters.

• v2 objects
  • Properties
  • operator methods
  • mutator methods
• v2 static functions
  • analysis functions
  • operator functions
  • mutator functions

v2 objects are of v2.prototype. They own two member values x and y. Polar coordinates – magnitude r and angle w – are accessible and modifyable via getters and setters. Given that they are exactly as lightweight as plain {x,y} objects with Object.prototype.

v2 objects

Properties

Non-modifying Operator Methods

v2 vector operations are non-modifying by nature. If result value is a vector, it's always a temporarily created new one.

Consider vector expression (a+b-c)*s, with a,b,c being vectors and s a scalar. An appropriate representation using operator functions reads

a.add(b).sub(c).scl(s)

None of the used vectors a,b,c are modified. Instead three temporary vector objects are created by each method used. Think (((a+b)-c)*s), where each parenthesis pair creates a temporary vector.

Modifying Mutator Methods

Whereas operator methods never modify the current vector, mutator methods (starting with letter i – read inplace) intentionally do exactly that. Consider vector expression (a+b-c)s again. When using mutator methods

a.add(b).isub(c).iscl(s)

only the first operator method add creates a tempory vector object, which is then succeedingly reused and overwritten by mutator methods isub and iscl (read 'inplace subtract' and 'inplace scale'). So using mutator methods that way we can save memory and improve performance.

Please note that methods not returning a vector don't need an accompanying inplace method.

Static v2 Functions

v2 has three types of static vector functions:

• Aalysis functions (isZero, isUnit, equals, len/r, angle/w, sqr)
• Operator functions (unit, tilde/perp, neg, sum/add, dif/sub, rot, scl, simtrf, dot, symp)
• Mutator functions (set, set_len/set_r, set_angle/set_w, set_unit, ineg, itilde/iperp, isum/iadd, idif/isub, irot, iscl, isimtrf, case1, case2, case3, case4, case5)

Analysis and Operator functions never modify their vector arguments. They work on arbitrary objects as long as these expose readable x and y members or x and y getters. Here is an example:

const cir = { x:100, y:200, r: 50 }, 
      pnt = { x: 30, y:150 },
      dist = v2.r(v2.dif(cir,pnt)) - cir.r;  // dist = 36.02325

In contrast Mutator functions intentionly modify their arguments. So they avoid creating temporary objects, which might be advantageous for memory saving and performance reasons. Mutator functions usually require argument objects with writeable x and y members or x and y getters and setters. Mutator functions accompanying operator functions ar distinguished by a prefixed letter i.

const box = {
   x0:100, y0:200, b:100, h:60,
   // center point
   get x()  { return this.x0 + this.b/2; },
   set x(q) { this.x0 = q - this.b/2; },
   get y()  { return this.y0 + this.h/2; },
   set y(q) { this.y0 = q - this.h/2; }
}
v2.iadd(box,{x:50,y:75})    // box = { x0:150, y0:275, b:100, h:60 }

Analysis Functions

Operator Functions

Operator functions work on arbitrary objects as long as these expose xand y members or xand y getters. They do not modify their arguments.

Mutator Functions

Mutator functions work on arbitrary objects as long as these expose x and y members or xand y getters and setters. They might modify their arguments.

Functions case1, case2, case3, case4, case5 allow to easily solve the five cases of the planar triangle equation.

v2 is minimal and well suited for graphics, physics and engineering applications. It is tiny. v2 weights 22 kB uncompressed and 6 kb minified.

Node Installation

npm install v2d

const v2 = require('v2d');
const u = v2(3,4);

Browser

<script src="v2.js"></script>
<script>
   const u = v2(3,4);
</script>

Test

npm run test

CDN

Use the link https://cdn.jsdelivr.net/gh/goessner/v2/v2.js for uncompressed and https://cdn.jsdelivr.net/gh/goessner/v2/v2.min.js for minified version.

In HTML use ...

<script src="https://cdn.jsdelivr.net/gh/goessner/v2/v2.min.js"></script>

License

v2 is licensed under the terms of the MIT License. See LICENSE-MIT for details.

#Change Log

All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.

3.0.0 - 2021-22-05

Fundmental rewrite. Provide lightweight objects and static functions.

1.3.8 - 2016-12-07

Modified

• scl and iscl function: default value [=1] of second parameter factor removed. Value 0 is allowed and supported now.

1.3.1 - 2016-07-05

Added

• isimtrf function for applying inplace similarity transform.
• Examples to API docs added.

1.3.0 - 2016-07-04

Added

• polar function for converting to polar coordinates.
• cartesian function for converting from polar to cartesian coordinates.
• ipolar function for inplace converting to polar coordinates.
• icartesian function for inplace converting from polar to cartesian coordinates.

Modified

• toPolar previous converting function marked as obsolete. Use polar instead.
• fromPolar previous converting function marked as obsolete. Use cartesian instead.

1.2.0 - 2016-05-14

Added

`simtrf` function for applying efficient similarity transformation @goessner.

1.1.0 - 2016-01-08

Added

toPolar function @goessner.
fromPolar function @goessner.
CHANGELOG.md @goessner.