Skip to content
Permalink
Browse files

Vector functions: Fix vector.direction() function, improve documentat…

…ion (#6801)

vector.direction() now returns a normalised vector with direction p1 to p2.
  • Loading branch information...
paramat authored and SmallJoker committed Dec 21, 2017
1 parent 18b9210 commit d04c41ad80650822be0ff3d18f253a0dbd570116
Showing with 38 additions and 41 deletions.
  1. +5 −26 builtin/common/vector.lua
  2. +33 −15 doc/lua_api.txt
@@ -63,34 +63,13 @@ function vector.distance(a, b)
end

function vector.direction(pos1, pos2)
local x_raw = pos2.x - pos1.x
local y_raw = pos2.y - pos1.y
local z_raw = pos2.z - pos1.z
local x_abs = math.abs(x_raw)
local y_abs = math.abs(y_raw)
local z_abs = math.abs(z_raw)
if x_abs >= y_abs and
x_abs >= z_abs then
y_raw = y_raw * (1 / x_abs)
z_raw = z_raw * (1 / x_abs)
x_raw = x_raw / x_abs
end
if y_abs >= x_abs and
y_abs >= z_abs then
x_raw = x_raw * (1 / y_abs)
z_raw = z_raw * (1 / y_abs)
y_raw = y_raw / y_abs
end
if z_abs >= y_abs and
z_abs >= x_abs then
x_raw = x_raw * (1 / z_abs)
y_raw = y_raw * (1 / z_abs)
z_raw = z_raw / z_abs
end
return {x=x_raw, y=y_raw, z=z_raw}
return vector.normalize({
x = pos2.x - pos1.x,
y = pos2.y - pos1.y,
z = pos2.z - pos1.z
})
end


function vector.add(a, b)
if type(b) == "table" then
return {x = a.x + b.x,
@@ -2248,25 +2248,43 @@ The following functions provide escape sequences:

Spatial Vectors
---------------
* `vector.new(a[, b, c])`: returns a vector:
For the following functions, `v`, `v1`, `v2` are vectors, `p1`, `p2` are positions:

* `vector.new(a[, b, c])`:
* Returns a vector.
* A copy of `a` if `a` is a vector.
* `{x = a, y = b, z = c}`, if all `a, b, c` are defined
* `vector.direction(p1, p2)`: returns a vector
* `vector.distance(p1, p2)`: returns a number
* `vector.length(v)`: returns a number
* `vector.normalize(v)`: returns a vector
* `vector.floor(v)`: returns a vector, each dimension rounded down
* `vector.round(v)`: returns a vector, each dimension rounded to nearest int
* `vector.apply(v, func)`: returns a vector
* `vector.equals(v1, v2)`: returns a boolean
* `vector.sort(v1, v2)`: returns minp, maxp vectors of the cuboid defined by v1 and v2
* `{x = a, y = b, z = c}`, if all of `a`, `b`, `c` are defined numbers.
* `vector.direction(p1, p2)`:
* Returns a vector of length 1 with direction `p1` to `p2`.
* If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`.
* `vector.distance(p1, p2)`:
* Returns zero or a positive number, the distance between `p1` and `p2`.
* `vector.length(v)`:
* Returns zero or a positive number, the length of vector `v`.
* `vector.normalize(v)`:
* Returns a vector of length 1 with direction of vector `v`.
* If `v` has zero length, returns `{x = 0, y = 0, z = 0}`.
* `vector.floor(v)`:
* Returns a vector, each dimension rounded down.
* `vector.round(v)`:
* Returns a vector, each dimension rounded to nearest integer.
* `vector.apply(v, func)`:
* Returns a vector where the function `func` has been applied to each component.
* `vector.equals(v1, v2)`:
* Returns a boolean, `true` if the vectors are identical.
* `vector.sort(v1, v2)`:
* Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`.

For the following functions `x` can be either a vector or a number:

* `vector.add(v, x)`: returns a vector
* `vector.subtract(v, x)`: returns a vector
* `vector.multiply(v, x)`: returns a scaled vector or Schur product
* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
* `vector.add(v, x)`:
* Returns a vector.
* `vector.subtract(v, x)`:
* Returns a vector.
* `vector.multiply(v, x)`:
* Returns a scaled vector or Schur product.
* `vector.divide(v, x)`:
* Returns a scaled vector or Schur quotient.

Helper functions
----------------

3 comments on commit d04c41a

@paramat

This comment has been minimized.

Copy link
Member Author

replied Dec 22, 2017

@rubenwardy I was trained by hmmmm to always add a very concise summary phrase at the start of the first line of the commit message. It's useful because you can then scan your eye down the start of the commit messages and see the subject, without reading the whole line.
Looking at commit messages you can see most devs do this.

I can see in this case it's borderline redundant, however 'Vector functions' is still more useful to the eye than the rest of the line, so i think this is fairly reasonable.

@rubenwardy

This comment has been minimized.

Copy link
Member

replied Dec 22, 2017

I disagree on that as you end up with pointless labels and inconsistency, but whatever.

The commit message is still bad as it is vague and overflows. At least remove the duplication, and maybe shorten to "docs".

Builtin Vectors: Fix direction() function, improve documentation

@paramat

This comment has been minimized.

Copy link
Member Author

replied Dec 22, 2017

Yes it was a bit duplicated and redundant, and too long, not great. Seems to overflow at 69 characters, it's a pain to count so mistakes happen. 'builtin vectors' is better, but my version is similar to yours so can't be particularly vague =)
Anyway i'll keep your request in mind.

Please sign in to comment.
You can’t perform that action at this time.