lace / vg Goto Github PK

View Code? Open in Web Editor NEW

120.0 4.0 15.0 345 KB

Vector-geometry toolbelt for 3D points and vectors

Home Page: https://vgpy.dev/

License: BSD 2-Clause "Simplified" License

Python 99.77% Shell 0.23%

numpy vector vectors linear-algebra geometry shortcuts toolbelt 3d-points 3d-vectors

vg's Introduction

vg

A very good vector-geometry toolbelt for dealing with 3D points and vectors. These are simple NumPy operations made readable, built to scale from prototyping to production.

📖 See the complete documentation: https://vgpy.dev/

Examples

Normalize a stack of vectors:

# 😮
vs_norm = vs / np.linalg.norm(vs, axis=1)[:, np.newaxis]

# 😀
vs_norm = vg.normalize(vs)

Check for the zero vector:

# 😣
is_almost_zero = np.allclose(v, np.array([0.0, 0.0, 0.0]), rtol=0, atol=1e-05)

# 🤓
is_almost_zero = vg.almost_zero(v, atol=1e-05)

Find the major axis of variation (first principal component):

# 😩
mean = np.mean(coords, axis=0)
_, _, pcs = np.linalg.svd(coords - mean)
first_pc = pcs[0]

# 😍
first_pc = vg.major_axis(coords)

Compute pairwise angles between two stacks of vectors:

# 😭
dot_products = np.einsum("ij,ij->i", v1s.reshape(-1, 3), v2s.reshape(-1, 3))
cosines = dot_products / np.linalg.norm(v1s, axis=1) / np.linalg.norm(v2s, axis=1)
angles = np.arccos(np.clip(cosines, -1.0, 1.0))

# 🤯
angles = vg.angle(v1s, v2s)

Installation

pip install numpy vg

Usage

import numpy as np
import vg

projected = vg.scalar_projection(
  np.array([5.0, -3.0, 1.0]),
  onto=vg.basis.neg_y
)

Development

First, install Poetry.

After cloning the repo, run ./bootstrap.zsh to initialize a virtual environment with the project's dependencies.

Subsequently, run ./dev.py install to update the dependencies.

Acknowledgements

This collection was developed at Body Labs by Paul Melnikow and extracted from the Body Labs codebase and open-sourced as part of blmath by Alex Weiss. blmath was subsequently forked by Paul Melnikow and later the vx namespace was broken out into its own package. The project was renamed to vg to resolve a name conflict.

License

The project is licensed under the two-clause BSD license.

vg's People

Contributors

Stargazers

Watchers

Forkers

githubkusi h-jia kijidada joseph-hurtado mr-mbello rjbashar geogubd debnoob dancebean longjun123456 alexhenderson ruthvikmukkamala lgtm-migrator ageron blsqr

vg's Issues

Add a compatibility layer

Since Python modules are installed in a global namespace, breaking changes to APIs can be very difficult to deal with, especially in a toolbelt like this one, since it's intended to be used by whole ecosystems of packages. If a breaking change is introduced here it needs to be updated at every point in the dependency tree, all at once, which is challenging.

I don't want to freeze the API forever, so instead the solution should be to provide a stable compatibility layer for libraries. For example, instead of import vg, a library would use import v1 as vg from vg. That way, libraries will be inured to future breaking changes, so long as 1.x or later version is used.

Convenience for application code means that import vg will keep working, and use the latest version.

It could also be possible to import next as vg from vg to provide experimental APIs before they've reached a point of stability.

I'd like to include this before the next major version is released.

Add `vg.asserts.almost_unit_length()` or similar

Allow `vg.average()` to accept in a list

As far as semantic sugar goes, it's not as useful if you have to wrap it in a np.array() call.

Rename `vg.orient()` to `vg.aligned_with()`

Drop support for Python 2 (in next major version)

Python 2 is deprecated and will not be supported in future versions of vg. This will be marked as a breaking change.

Error when installing the package

I get this error while installing the module:

C:\WINDOWS\system32>pip install vg
Collecting vg
  Using cached https://files.pythonhosted.org/packages/34/42/aad07165a66eb402ec60d2e40640b585ca56b748b42e9923c1242be4d06b/vg-1.2.1.tar.gz
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "C:\Users\reas\AppData\Local\Temp\pip-install-2c8clwqs\vg\setup.py", line 10, in <module>
        readme = f.read()
      File "c:\program files (x86)\python37-32\lib\encodings\cp1252.py", line 23, in decode
        return codecs.charmap_decode(input,self.errors,decoding_table)[0]
    UnicodeDecodeError: 'charmap' codec can't decode byte 0x8d in position 1618: character maps to <undefined>

Add `vg.mean` method

To replace code removed in lace/polliwog#96.

Error using signed_angle with vector array

Hello!

I am calling

angles = vg.signed_angle(vec1_array.T, points.T, look, units='rad')

with shapes

('points', (3, 8))
('vec1_array', (3, 8))
('look', (3, 1))

However, I get the error:

Traceback (most recent call last):
  File "./extract_fe_pictures.py", line 113, in <module>
    test_code('skywalker_2013_mod', plot=False, interactive=False, export_path='.', verbose=False)
  File "./extract_fe_pictures.py", line 28, in test_code
    safe_poly.plot()
  File "/home/george/ros_workspaces/uav_ftc/src/uav_ftc/src/uav_ftc/polytope_utils.py", line 1271, in plot
    face_points = self._get_face_points(temp_polytope)
  File "/home/george/ros_workspaces/uav_ftc/src/uav_ftc/src/uav_ftc/polytope_utils.py", line 853, in _get_face_points
    angles = vg.signed_angle(vec1_array.T, points.T, look, units='rad')
  File "/usr/local/lib/python2.7/dist-packages/vg/core.py", line 297, in signed_angle
    return sign * angle(v1, v2, look, units=units)
  File "/usr/local/lib/python2.7/dist-packages/vg/core.py", line 251, in angle
    v1, v2 = [reject(v, from_v=look) for v in (v1, v2)]
  File "/usr/local/lib/python2.7/dist-packages/vg/core.py", line 125, in reject
    return vector - project(vector, onto=from_v)
  File "/usr/local/lib/python2.7/dist-packages/vg/core.py", line 92, in project
    return scalar_projection(vector, onto=onto)[:, np.newaxis] * normalize(onto)
  File "/usr/local/lib/python2.7/dist-packages/vg/core.py", line 112, in scalar_projection
    check(locals(), "onto", (k, 3))
  File "/usr/local/lib/python2.7/dist-packages/vg/shape.py", line 93, in check
    return check_value(locals_namespace[name], shape, name=name)
  File "/usr/local/lib/python2.7/dist-packages/vg/shape.py", line 54, in check_value
    raise ValueError("{} with shape {}; got {}".format(preamble, shape, a.shape))
ValueError: onto must be an array with shape (8, 3); got (3, 1)

I believe I have set the dimensions correctly.
Am I missing something?

Thanks!

Optimize `vg.shape.check` so `locals()` does not need to be passed in

The call to locals() makes vg.shape.check() much slower than it needs to be in the (very likely) success case. As an optimization, as a convenience to the caller, we could modify it to fetch locals from the stack rather than requiring the caller to pass them in.

See this comment thread which explains the approach: lace/blmath#17 (comment)

Feature request: Reflections, trasformation matrix

Why not add the reflections of a vector for given plane normal?
Or even, functions for building trasformation matrix for given actions

Thank you

Clarify what goes in `vg` vs `polliwog`

Since there is a closely related library, polliwog which does a lot of computational geometry, it's useful to clarify what belongs here vs. there.

Accordingly, the idea is to clarify this library's purpose:

A vector-geometry toolbelt for dealing with 3D points and vectors

and say that anything more complicated is general computational geometry, and goes in polliwog.

In particular, transformation matrices will be scoped to polliwog.

Accordingly, the matrix functions will be removed in the next major release.

Refs:

Clarify that `vg.apex()` can take a non-normalized vector

Pretty sure this is true. Worth triple-checking this and then clarifying in the docs.

Floating point error when calculating angle?

Code:

import numpy as np
import vg
vec1 = np.array((1, 3, 3))
vec2 = np.array((1, 3, 3))
print(vg.angle(vec1, vec2))

Expected result: 0, right?