math2d

Documentation

Overview

Package math2d provides a set of fixed-point 2D operations that work with image.Point vectors and int32 angles.

The angle unit is equal to 1/4294967296 of the full angle. The int32 type can represent angles from -FullAngle/2 to FullAngle/2 - 1 (inclusive).

The fixed-point CORDIC algorithm used by this package is at least 10 times faster than using math.Cos and math.Sin on the ISA that does not support cos/sin in hardware. If the ISA provides hardware cos/sin the CORDIC is about 2 times slower than using math.Cos/math.Sin but it does not use FPU context which could be an advantage in some cases.

The accuracy of the fixed-point CORDIC algorithm depends on many factors but is usually much worse than the accuracy of any algorithm based on cos/sin and floating-point calculations (see "Numerical Accuracy and Hardware Tradeoffs for CORDIC Arithmetic for Special Purpose Processors", K. Kota, J. Cavallaro, http://scholarship.rice.edu/bitstream/handle/1911/20039/Kot1993Jul1NumericalA.PDF)

Index

• Constants
• func A(v image.Point, n int) (f image.Point, m int)
• func F(v image.Point, n int) image.Point
• func I(v image.Point, n int) image.Point
• func Polar(v image.Point) (r int, angle int32)
• func Rotate(v image.Point, angle int32) image.Point

Constants

const (
	FullAngle        = 1 << 32       // 2π rad = 360°
	RightAngle int32 = FullAngle / 4 // π/2 rad = 90°
)

Angle constants. FullAngle does not fit in int32 but can be used to calculate smaller angle constants.

Functions

func A

func A(v image.Point, n int) (f image.Point, m int)

A converts an integer vector to a fixed-point one ensuring that both f.X and f.Y values fit in the n-bit signed fixed-point number and at last one of f.X or f.Y has exactly n-1 significant bits plus a sign bit. A returns the converted vector and the length of its fractional part (can be negative if the number of significant bits was reduced). For zero v it returns (v, n-1). Use A to normalize the vector before passing it to the Rotate or Polar functions to improve accuracy.

func F

func F(v image.Point, n int) image.Point

F returns image.Point{v.X<<n, v.Y<<n}. It provides a convenient way to convert an integer vector to a fixed-point one. If you want to ensure a specific number of significant bits use A instead.

func I

func I(v image.Point, n int) image.Point

I provides a convenient way to convert a fixed-point vector to an integer one. It supports positive and negative n so it can be used to invert F and A as below

I(F(v, n), n) == v // true if no overflow
I(A(v, n))    == v // true if no overflow and no significant bit reduction

func Polar

func Polar(v image.Point) (r int, angle int32)

Polar returns the polar form of v. The internal calculations require that v.Mul(2) must not overflow.

func Rotate

func Rotate(v image.Point, angle int32) image.Point

Rotate rotates the vector v by the given angle.

Rotate can also be used to convert a vector in the polar form (R, theta) to the rectangular one as below

Rotate(image.Pt(R, 0), theta)

Moreover, it can be used to calculate trigonometric functions as below

Rotate(image.Pt(1<<n, 0), alpha)

The returned vector contains {cos(alpha), sin(alpha)} with n-bit fractional part. Since the cosine and sine are calculated simultaneously, the returned vector can be also thought of as a fractional representation of tangent and cotangent.

The internal calculations require that v.Mul(2) must not overflow.