otherlab / geode

A computational geometry library for C++ and Python

Geode: The Otherlab computational geometry library

Geode is an open source library of computational geometry and associated mathematical utilities together with a fast, lightweight python binding layer. The license is standard three-clause BSD (see the included LICENSE file or LICENSE).

For questions or discussion, email [email protected].

Dependencies

For C++:

• cmake >= 3.3: A build system (GPL)
• gmp >= 4.0: Arbitrary precision arithmetic (LGPL)
• cblas: C wrappers for BLAS (BSD license)

For Python:

• python >= 2.7: A scripting language (Python Software Foundation (PSF) license)
• numpy >= 1.5: Efficient multidimensional arrays for Python (BSD license)
• setuptools >= 0.6: A packaging system for Python (PSF license)

Optional dependencies (see below for how to disable these):

• py.test >= 2.1: Simple python testing (MIT license)
• scipy: Scientific computation for Python (BSD license)
• openexr: High dynamic range floating point image format (BSD license)
• libpng: Lossless image format (Custom noncopyleft license)
• libjpeg: Lossy image format (Custom noncopyleft license)

Geode makes extensive use of C++11 features, so a relatively recent C++ compiler is necessary.

Windows

This has been built and run successfully with the Visual Studio 2015 preview. We are working to make this more streamlined and robust (as well as fixing the hundreds of compiler warnings), but the following worked for me:

Install the following dependencies:

• WinPython 64bit version 2.7.9.2 (This includes numpy and scipy)
• CMake
• MPIR (commit 3a9dd527a2f87e6eff8cab8b54b0b1f31e0826fa but tweaked for VS2015) ** This will require installing vsyasm ** Remove definition of snprintf from /build.vc12/cfg.h ** You may need to set Tools->Options->Projects and Solutions->Build and Run->"Maximum number of parallel project builds" to 1 to avoid parallel builds clobbering config headers

Create a config.py and point gmp to installation of mpir: gmp_libpath = '#/../mpir/build.vc12/x64/Debug' gmp_include='#/../mpir' gmp_publiclibs='mpir.lib'

Setup Command Prompt environment: Python from: ...\WinPython-64bit-2.7.9.2\scripts\env.bat VS dev tools using: "C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\Tools\VsDevCmd.bat" Select x64 tools using: "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64

Create a build directory separate from the sources (optional, but recommended): mkdir build

Build with: cmake ../ make

If you wish to install geode to a different location (such as a python virtualenv), add -DCMAKE_BUILD_PREFIX=/path/to/wherever to the cmake command.

Install with: make install

To use geode outside of project directory or for test_worker to pass you must add geode to your PYTHONPATH: set PYTHONPATH=<path_to_dir_outside_repo>\geode;%PYTHONPATH%

Installation

If necessary, dependencies can be installed via one of

# Debian/Ubuntu
sudo apt install cmake g++ python-dev python-pip python-numpy pkg-config libjpeg-dev libpng-dev zlib1g-dev libgmp-dev
sudo apt-get install python-scipy python-pytest libpng-dev libjpeg-dev libopenexr-dev # optional
pip install numpy

# Homebrew (recommended)
brew install cmake openexr gfortran python #Note: gfortran brew is now part of gcc, so although previous versions can still be accessed, brew install gcc is the preferred method
sudo pip install --upgrade pip setuptools numpy scipy pytest #numpy and scipy can be

# MacPorts (not recommended).  If you have python 2.7, replace py26 with py27.
sudo port -v install python26 py26-numpy cmake
sudo port -v install py26-scipy py26-py libpng jpeg openexr # optional
sudo port -v install gcc47 # If clang is unavailable

Geode can then be installed from source via

git clone https://github.com/otherlab/geode.git
cd geode

# Install c++ headers and libraries to /usr/local
cmake . && make && make install

At this point, you have a choice of either developer mode or install mode

Install mode

sudo make install

This will also install python bindings if enabled.

Developer mode

The libraries are built into geode if you want to use them without installing. To point python imports to your development tree, run one of

sudo python setup.py develop
python setup.py develop --prefix=$HOME

To link against this built version of geode, add this to your project's own CMakeLists.txt:

include(path/to/geode/CMakeLists.txt)
target_link_libraries(foo geode)

If you've installed geode, you can instead use:

find_package(Geode REQUIRED)
target_link_libraries(foo geode)

which will allow you to develop with geode in C++ as if it was installed.

Post install

On linux you may have to update the shared library cache via ldconfig if this is the first time you've installed. Make sure /usr/local/lib (or wherever you installed libgeode.so) is included in the cache's search path.

Testing

Unit tests can be run via

cd geode
py.test

Extra configuration

If additional build configuration is necessary, run ccmake instead of cmake. CMake includes documentation generated from the geode build system.

For developers wishing to use without installing, see more options in Developer mode section below

These options can also be passed via command line to cmake. Run ccmake for a complete list. Use CMAKE_BUILD_TYPE=Debug for a much slower build with many more assertions:

cmake -DCMAKE_BUILD_TYPE=Debug

Acknowledgements

Parts of geode come from the PhysBAM simulation library developed by Ron Fedkiw et al. at Stanford University.

For random numbers, we use the Random123 library of John Salmon et al. at D. E. Shaw Research. Random123 is included inline in core/random/random123.

The interval arithmetic in exact/Interval is based on code by Robert Bridson and Tyson Brochu.

geode's Issues

Expose rotation interpolation to Python

Frame interpolation is already exposed, not so for standalone rotations.

jpeg flag for image orientation ignored

JpgImage should be aware of this and allocate accordingly.

Make python to Nested conversion handle lists of lists and rectangular 2D numpy arrays

Rename in-place normalize

The distinction between normalize and normalized is clever but unnecessarily surprising to anyone who hasn't seen it. We should rename normalized to normalize, and normalize to inplace_normalize or something.

Python proxy functions should use keyword arguments wherever possible

And also, for all functions with default arguments, python proxies with said defaults should be available.

Make expression templates work for multidimensional arrays

This should be fairly easy.

Python-exposed functions should have doc strings

Make segment_segment_distance_and_normal compute KKT-valid normals in all cases

The segment_segment_distance_and_normal routine fails the KKT conditions in certain degenerate cases. This occurs only when the closest points are vertices of both segments, since the normal computed by segment_point_distance_and_normal is not consistent with the other segment.

Unit tests that catch this case are already written: to reproduce remove the

// TODO: Make stronger assertions unconditional once the code is fixed` conditions in `segment_tests

in Segment.cpp introduced by 22287e9.

Array::project should return Subarray

This will require modifying Subarray to measure strides in bytes, rather than units of sizeof(T).

Simplify expression templates

1. We should replace all the typedef business with auto and decltype.
2. All argument arrays should be made copyable, by conversion to RawArray if necessary.

Enforce use of new_ constructor for classes derived from Object

Classes that are derived from Object have access to Object's protected constructor. This allows construction outside of the new_ operator which will break Ref/Ptr operation.

One option would be to add an argument of a private 'token' type to Object's constructor only constructible (via friend scope) from new_ (This would unfortunately add another argument to all constructors in derived classes). Is this worth it? Is there a better option?

Support Python 3

It seems like this might be easy nowadays, so we should give it a try.

Set up commit emails

Deprecate .try in favor of a standard format

set_backtrace can cause hangs in multithreaded programs

Not sure why: I'm going to disable it and use a different mechanism rather than diagnose it now. Apparently the exit() call at the end of backtrace_and_abort doesn't guarantee a kill.

When we switch to xdress, make Ref/Ptr/Weak use boost::shared_ptr under the hood

Weak pointers are too useful not to have, but we still need our own to enforce nonzeroness, better assertions, etc.

Standardize barycentric coordinate usage between segments and triangles

People typically use 1 barycentric coordinate for segments and 3 for triangles. This is inconvenient for template code. I think we should standardize on 2 for triangles, which is better since it the sum = 1 constraint is enforced by construction.

Replace mesh/TriangleSubdivision with Pixar's OpenSubdiv library

This will also be an opportunity to decide how we want to organize external libraries in core.

PropManager should be a full-fledged python sequence

1. len(), [], and in should work.
2. Iteration should traverse the props in the correct order.

Once this is fixed we can use the generic sequence wrapping features elsewhere as desired.

TriMesh methods that return a new mesh should be available

TriMesh is awkwardly imperative. Ideally, two versions of functions like invert() should be available, and the in-place invert() should return a reference to the mesh.

Remove dependency on gmm

Reimplement triangle distance functions to be similar to Segment case

They currently probably lose accuracy for bad triangles. See Segment.cpp for examples of (hopefully) robust distance / normal / weight algorithms.

nanosvg treats cubic bezier - line - shorthand bezier incorrectly

The shorthand Bezier will reuse one of the control points of the cubic Bezier, even though there is a line in between. For details, see http://www.w3.org/TR/SVG/paths.html#PathDataCubicBezierCommands.

overloaded functions should have 'overloaded' python callables

for instance, poly_bounding_box and polys_bounding_box should be called from a generic bounding_box() python function which distinguishes based on type.

Rename append_elements to extend

1D Box class needs to be consistent

Currently 1D box is handled as a tuple (which is fine), but saying Box(float,float) should then implicitly also return one.

BoxScalar and the 1D BoxVector should also be as transparently convertible as possible.

Polygon and Polygons should be Array, not std::vector

And also, bounding_box should just work on any array.

Simple classes need exposing to python

Such as Triangle etc. Making them objects is not cool, so maybe something like WrappedQObject.

Reasonable documentation

Sphinx, doxygen, etc.?

Version checking between C++ and Python

Implement some kind of mechanism to verify that installed Python and C++ code is version synchronized.

Make all SVD / eigensystem computations stable

For 2x2 and 3x2, a small finite number of Givens/Jacobi rotations suffice. For 3x3, Eftychis's fast Jacobi iteration is presumably the way to go.

TriMesh should be renamed HalfedgeMesh

TriMesh and TriangleMesh is just too confusing. TriangleMesh should probably also be renamed.

Refactor point vs. vector exact predicates

The simplicity code currently generates unrelated code paths for the following three predicates:

cross(b-a,c-a)
cross(b-a,c)
cross(b,c)

However, if we either (1) use pure integer math or (2) add one bit of extra space to our domain, these three predicates can be replaced with simulation of simplicity code for the third predicate plus a small amount of inline code for the other two.

Check if BoxTree::ranges can be compacted into an offsets array

I.e., is ranges[i].hi == ranges[i+1].lo?

Cannot build from inside core directory

tempfile.py (used by scons) finds core/random/init.py in the local path and tries to import that instead of python's Random. (possibly causing strange errors in the process) Solution might be to file a bug for scons.

Matrix::solve_linear_system should be at most 2x slower than determinant

Whoever wrote the current code hasn't heard of Cramer's rule either.

It should be easy to point other at a different python executable

There are two issues:

1. scons uses which python for configuration. This is easily fixed by an option.
2. Every script has /usr/bin/env python. I'm not sure how best to fix this.

Martin:

I don't think we actually need env, but that doesn't make it any better. We could let the scons build process modify the #! lines in python files (and probably, that would mean the modified python files should go into the install directory).

Geoffrey:

My main constraint is that I don't want to have to "rebuild" after I change a python file. That was the main motivation for the current structure. However, it may be enough to have two different modes: one which leaves them in place and one which moves and tweaks them. setuptools develop is also worth looking it.

Don't rely on environment variables

In order to make deployment easier for non-developers, we should arrange things so that python doesn't require setting environment variables (OTHER and PYTHONPATH). In particular, the code should probably never call getenv() (check this before closing this bug).

other.core.python.real needs to be renamed

It conflicts with numpy.real.

Make Value/Prop work without python convertibility

If T can't be converted to Python, the relevant features should simply be disabled.

Remove debug namespace

This is rarely used, and occasionally gets in the way. Move everything inside it out into the main other namespace.

Need a Conformal class to represent rigid+scaling transforms

Clean up mutable Ray nastiness

The fact that Ray is used imperatively in ray intersection code is very unfortunate.

TriMesh and rendering

It is very unintuitive to work with TriMesh in scripts that render a lot because TriMesh loses normals in csg etc.

render_mesh could automatically add normals (if necessary to a copy). Or TriMesh could be forced to always have (up to date) normals (marked dirty and updated whenever accessed).

A BareTriMesh could be provided for space-critical tasks where a mesh without extra information is necessary.

python export of Box needs work

It's really nasty to work with now, needs more exposed functions, especially since min and max are unwritable in python.

Make most methods in Array/RawArray/ArrayBase and Vector into free functions

Make it easy to define variable arity/type functions, methods, and constructors

In keeping with simplicity, these will be handled by passing the argument tuple through to a single C++ function which does the dispatch.

Make sure all IO is big endian safe

This includes write_numpy and tryfile, for example.

pip install

pip install geode should work.

Make a clean way to define mixed user settable / computable values

Sometimes one wants a property which is set by the user some of the time, and computed from other properties the rest of the time. We should have a clean way to do this. bed_width in Print3dScene is a good example.