vector

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 26, 2022 License: MIT Imports: 2 Imported by: 0

README

vector

Version GoDoc Go Report Card

The motivation behind this package is to find a better way to write vector math in Golang, there has to be a more expressive way without it getting to verbose.

This is an experiment, there are lots of other libraries tackling vector math as well. You should properly take a look at gonum before consider using this package.

Install

go get github.com/kvartborg/vector

Usage

Golang does not have a way to define generic types yet, which limits this package to operate with vectors represented as float64 values only. To allow for multi-dimensional vectors, a vector is simply represented as a list of float64 values.

// A Vector is simply a list of float64 values
type Vector []float64

I will consider adding float32 and int support at a later stage, if there is a good reason or when go adds generics to the language.

Tackling verbosity

Another goal of this experiment is to minimize the verbosity around using the package, this can be achieved by using type aliasing. In this way you can omit the package identifier and give the Vector a shorter name like vec or something else, it is up to you.

// Minimize the verbosity by using type aliasing
type vec = vector.Vector

// addition of two vectors
result := vec{1, 2}.Add(vec{2, 4})

A nice side effect of representing a vector as a list of float64 values is that a slice of float64 values can easily be turned into a vector by using type casting. This elimitates the need for any constructor functions for the vector type.

// Turn a list of floats into a vector
v := vec([]float64{1, 2, 3})
Mutability vs Immutability

All arithmetic operations are immutable by default. But if needed a Vector can be turned into a MutableVector with the vector.In function, see example below. A mutable vector performs arithemetic operations much faster without taking up any memory.

// create vectors
v1, v2 := vec{1, 2}, vec{2, 4}

// Immutable addition, will return a new vector containing the result.
result := v1.Add(v2)

// Mutable addition, will do the calculation in place in the v1 vector
vector.In(v1).Add(v2)
Slicing a vector

Another benefit of using a list of float64 to represent a vector is that you can slice vectors as you normally would slice lists in go.

v1 := vec{1, 2, 3}
v2 := v1[1:] // returns a new vec{2, 3}

Documentation

The full documentation of the package can be found on godoc.

Contributions

Contributions with common vector operations that are not included in this package are welcome.

Credits

Thanks to gonum for inspiration and the following functions axpyUnitaryTo, scalUnitaryTo that enhances the performance of arithmetic operations in this package.

License

This project is licensed under the MIT License and includes gonum code that is licensed under 3-Clause BSD license.

Documentation

Overview

Package vector provides useful math operations for vectors and a way to represent vectors as a list of float64 values. 

// Minimize the verbosity by using type aliasing
type vec = vector.Vector

// Create a vector
v1 := vec{1, 2}

// Create a vector from a list of float64 values
v2 := vec([]float64{2, 6})

// Do arithmetic operations with the vectors
result := v1.Add(v2)
Example 
// create a zero vector of 3-dimensions
v1 := make(vec, 3)

// Create a new vector
v2 := vec{4, 2}

// Create a vector from a list of float64
v3 := vec([]float64{1, 2, 4})

fmt.Println(
	v1.Sum(v2, v3),
)

Output:

[5 4 4]

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// X is the vector axis which can be used to rotate another vector around
	X = Vector{1, 0, 0}
	// Y is the vector axis which can be used to rotate another vector around
	Y = Vector{0, 1, 0}
	// Z is the vector axis which can be used to rotate another vector around
	Z = Vector{0, 0, 1}
)
View Source 
var (
	// ErrNot3Dimensional is an error that is returned in functions that only
	// supports 3 dimensional vectors
	ErrNot3Dimensional = errors.New("vector is not 3 dimensional")
	// ErrNotSameDimensions is an error that is returned when functions need both
	// Vectors provided to be the same dimensionally
	ErrNotSameDimensions = errors.New("the two vectors provided aren't the same dimensional size")

	// ErrNotValidSwizzleIndex is an error that is returned when swizzling a vector and passing
	// an index that lies outside of the length of the vector
	ErrNotValidSwizzleIndex = errors.New("index for swizzling is not valid for the given vector")
)

Functions

This section is empty.

Types

type MutableVector 

type MutableVector []float64

MutableVector is a vector where all arithmetic operations will be done in place on the calling vector. This will increase performance and minimize the memory consumption.

func In 

func In(a Vector) MutableVector

In takes a vector and turns it into a mutable vector.

Example 
result, v1, v2 := make(vec, 3), vec{2, 1, 3}, vec{4, 12, 6}

vector.In(result).
	Add(v2).
	Sub(v1)

fmt.Println(result)

Output:

[2 11 3]

func (MutableVector) Add 

func (a MutableVector) Add(b Vector) MutableVector

Add a vector in place in the mutable vector

func (MutableVector) Angle 

func (a MutableVector) Angle(axis ...Vector) float64

Angle returns the angle in radians from the first MutableVector to the second, and an error if the two MutableVectors aren't of equal dimensions (length). For 0-dimension MutableVectors, the returned angle is 0. For 1-dimension MutableVectors, the angle is Pi if the second MutableVector's coordinate is less than the first MutableVector's coordinate, and 0 otherwise.

func (MutableVector) Clone 

func (a MutableVector) Clone() MutableVector

Clone a mutable vector.

func (MutableVector) Cross 

func (a MutableVector) Cross(b Vector) (Vector, error)

Cross product of two vectors

func (MutableVector) Dot 

func (a MutableVector) Dot(b Vector) float64

Dot product of two vectors

func (MutableVector) Equal 

func (a MutableVector) Equal(b Vector) bool

Equal compares that two vectors are equal to each other

func (MutableVector) Invert 

func (a MutableVector) Invert() MutableVector

Invert inverts the vector, and then returns it

func (MutableVector) Magnitude 

func (a MutableVector) Magnitude() float64

Magnitude of a vector

func (MutableVector) Rotate 

func (a MutableVector) Rotate(angle float64, axis ...Vector) MutableVector

Rotate is rotating a vector around an abitrary vector axis If no axis are specified it will default to rotate around the Z axis

If a vector with more than 3-dimensions is rotated, it will cut the extra dimensions and return a 3-dimensional vector.

NOTE: the ...MutableVector is just syntactic sugar that allows the vector axis to not be specified and default to the Z axis, if multiple axis is passed the first will be set as the rotational axis

func (MutableVector) Scale 

func (a MutableVector) Scale(size float64) MutableVector

Scale vector with a given size

func (MutableVector) Sub 

func (a MutableVector) Sub(b Vector) MutableVector

Sub subtracts a vector with another vector or a set of vectors

func (MutableVector) Sum 

func (a MutableVector) Sum(vectors ...Vector) MutableVector

Sum a vector with a vector or a set of vectors

func (MutableVector) Unit 

func (a MutableVector) Unit() MutableVector

Unit returns a direction vector with the length of one.

func (MutableVector) X 

func (a MutableVector) X() float64

X is corresponding to doing a MutableVector[0] lookup, if index 0 does not exist yet, a 0 will be returned instead

func (MutableVector) Y 

func (a MutableVector) Y() float64

Y is corresponding to doing a MutableVector[1] lookup, if index 1 does not exist yet, a 0 will be returned instead

func (MutableVector) Z 

func (a MutableVector) Z() float64

Z is corresponding to doing a MutableVector[2] lookup, if index 2 does not exist yet, a 0 will be returned instead

type Vector 

type Vector []float64

Vector is the definition of a row vector that contains scalars as 64 bit floats

func (Vector) Add 

func (a Vector) Add(b Vector) Vector

func (Vector) Angle 

func (a Vector) Angle(axis ...Vector) float64

Angle returns the angle in radians from the first Vector to the second, and an error if the two Vectors aren't of equal dimensions (length). For 0-dimension Vectors, the returned angle is 0. For 1-dimension Vectors, the angle is Pi if the second Vector's coordinate is less than the first Vector's coordinate, and 0 otherwise.

Example 
fmt.Println(
	vec{17, 4, 3}.Angle(vec{-1, 15, 7}),
)

Output:

1.351241200672429

func (Vector) Clone 

func (a Vector) Clone() Vector

Clone a vector

Example 
fmt.Println(
	vec{1, 2}.Clone(),
)

Output:

[1 2]

func (Vector) Cross 

func (a Vector) Cross(b Vector) (Vector, error)

Cross product of two vectors

Example 
fmt.Println(
	vec{0, 1, 2}.Cross(vec{3, 2, 1}),
)

Output:

[-3 6 -3] <nil>

func (Vector) Dot 

func (a Vector) Dot(b Vector) float64

Dot product of two vectors

Example 
fmt.Println(
	vec{0, 2}.Dot(vec{2, 0}),
)

Output:

0

func (Vector) Equal 

func (a Vector) Equal(b Vector) bool

Equal compares that two vectors are equal to each other

Example 
fmt.Println(
	vec{2, 1}.Equal(vec{1, 2}),
)

Output:

false

func (Vector) Invert 

func (a Vector) Invert() Vector

Invert inverts the vector, and then returns it

Example 
fmt.Println(
	vec{19, 0, 3}.Invert(),
)

Output:

[-19 -0 -3]

func (Vector) Magnitude 

func (a Vector) Magnitude() float64

Magnitude of a vector

Example 
fmt.Println(
	vec{1, 2}.Magnitude(),
)

Output:

2.23606797749979

func (Vector) Rotate 

func (a Vector) Rotate(angle float64, axis ...Vector) Vector

Rotate is rotating a vector around an abitrary vector axis If no axis are specified it will default to rotate around the Z axis

If a vector with more than 3-dimensions is rotated, it will cut the extra dimensions and return a 3-dimensional vector.

NOTE: the ...Vector is just syntactic sugar that allows the vector axis to not be specified and default to the Z axis, if multiple axis is passed the first will be set as the rotational axis

Example 
fmt.Println(
	vec{1, 0, 0}.Rotate(math.Pi/2, vector.Y),
)

Output:

[6.123233995736757e-17 0 -1]

func (Vector) Scale 

func (a Vector) Scale(size float64) Vector

Scale vector with a given size

Example 
fmt.Println(
	vec{1, 2}.Scale(2),
)

Output:

[2 4]

func (Vector) Sub 

func (a Vector) Sub(b Vector) Vector

Sub subtracts a vector with another vector or a set of vectors

Example 
fmt.Println(
	vec{1, 4}.Sub(vec{0, 2}),
)

Output:

[1 2]

func (Vector) Sum 

func (a Vector) Sum(vectors ...Vector) Vector

Sum a vector with a vector or a set of vectors

Example 
fmt.Println(
	vec{0, 2}.Sum(vec{1, 4}),
)

Output:

[1 6]

func (Vector) Swizzle added in v0.1.1 

func (a Vector) Swizzle(swizzleIndices ...int) (Vector, error)

Swizzle returns a clone of the input vector altered using the provided swizzling indices. For example, with `vector := {1, 3, 9}`, `vector.Swizzle(2,1,2,0)` will return `Vector{9,3,9,1}`. Swizzle will return the swizzled vector, and an error if one of the provided indices is out of bounds.

func (Vector) Unit 

func (a Vector) Unit() Vector

Unit returns a direction vector with the length of one.

Example 
fmt.Println(
	vec{1, 2}.Unit(),
)

Output:

[0.4472135954999579 0.8944271909999159]

func (Vector) X 

func (a Vector) X() float64

X is corresponding to doing a Vector[0] lookup, if index 0 does not exist yet, a 0 will be returned instead

func (Vector) Y 

func (a Vector) Y() float64

Y is corresponding to doing a Vector[1] lookup, if index 1 does not exist yet, a 0 will be returned instead

func (Vector) Z 

func (a Vector) Z() float64

Z is corresponding to doing a Vector[2] lookup, if index 2 does not exist yet, a 0 will be returned instead

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.