Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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 d04c41a
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 41 deletions.
31 changes: 5 additions & 26 deletions builtin/common/vector.lua
Expand Up @@ -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,
Expand Down
48 changes: 33 additions & 15 deletions doc/lua_api.txt
Expand Up @@ -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
----------------
Expand Down

3 comments on commit d04c41a

@paramat
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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
Copy link
Member

@rubenwardy rubenwardy commented on d04c41a Dec 22, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.