# 2Geom: easy 2D graphics library

## What is this?

2Geom is a C++ 2D geometry library geared towards robust processing of
computational geometry data associated with vector graphics. The primary
design consideration is ease of use and clarity. It is dual-licensed
under LGPL 2.1 and MPL 1.1.

The library is descended from a set of geometric routines present in
Inkscape, a vector graphics editor based around the Scalable Vector
Graphics format, the most widespread vector graphics interchange format
on the Web and a W3C Recommendation. Due to this legacy, not all parts
of the API form a coherent whole (yet).

Rendering is outside the scope of this library, and it is assumed
something like libcairo or similar is employed for this.  2geom
concentrates on higher level algorithms and geometric computations.


## Features List

* C++ 17
* Functional programming style.
* Points
* Efficient affine transformations
* Rectangles
* Convex Hulls
* Bounded error
* General purpose paths:
  + Exact elliptical arcs
  + Area
  + Centroid and bending moments
* Path Locations:
  + Determination of special spots (e.g. maximum curvature)
  + Splitting
  + Point, tangent, curvature at location
  + Efficient arc length and inverse arc length
* Path algebra:
  + Computations such as offset curves can be written with their mathematical definition
    and still get a bounded error, efficient curve. (preliminary trials indicate offset
    done this way out performs the method used in Inkscape)
* Arbitrary distortion (with bounded error):
  + Mesh distorts
  + Computational distorts such as the GIMP's 'vortex' plugin
  + 3d mapping (perspective, flag, sphere)
* Exact boolean ops (elliptic arcs remain elliptic arcs)
* Efficient 2d database
* Implicit function plotting
* NURBs input and output
* Tunable path simplification
* PDoF constraint system for CAD/CAGD


## Dependencies

To build 2Geom, you will need:

* C++ 17
* [Boost](http://www.boost.org/) (headers only)
* [glib](https://wiki.gnome.org/Projects/GLib)
* [GNU Scientific Library](http://www.gnu.org/software/gsl/)
* [double-conversion](https://github.com/google/double-conversion)
* [cairo](https://www.cairographics.org/)
* [Ragel](http://www.colm.net/open-source/ragel/) (if you want to modify the SVG path parser)
* [GTK+ 2](http://www.gtk.org/) (for demo programs)


## Building

2Geom uses CMake as the build and configuration system. To build, type:

    mkdir build && cd build
    cmake ..
    make

To run tests and performance tests:

    make test
    make perf

**Note**: Tests are disabled by default. To enable tests pass `-D2GEOM_TESTING=ON` to `cmake` command.

Also check out some of the interactive programs in src/toys.

Documentation is generated from source comments using Doxygen.
Run `doxygen` in the project root to generate documentation in
`doc/html`.


## API / ABI Stability

Version 1.0 of 2Geom marks its first official release.  With this
release the library's API/ABI is considered stable:

 * All public APIs will not be renamed or have their parameters changed
   without providing backwards-compatible aliases.

 * New functionality added to these APIs will not change their meaning
   or fundamental behaviors.

 * If an API needs to be removed or replaced, it will be declared
   deprecated but will remain in the API until the next major version.
   Warnings will be issued when the deprecated method is called.

 * We'll only break backwards compatibility of these APIs if a bug or
   security hole makes it completely unavoidable.

Improvements that would break the API/ABI will be noted in our bug
tracker, for a future release.

2Geom does not follow Semantic Versioning. Instead, version numbers
match major Inkscape release versions.


## Further information

Communications related to 2Geom development happen on a
[SourceForge mailing list](https://lists.sourceforge.net/lists/listinfo/lib2geom-devel).

The primary user of 2Geom is [Inkscape](https://inkscape.org/en/).
API-breaking changes to 2Geom will require corresponding changes to
Inkscape.

# win32 instructions
## Installation
- Download the latest mingw, gsl, and gtk bundles from [http://inkscape.modevia.com/win32libs/?C=M;O=D](http://inkscape.modevia.com/win32libs/?C=M;O=D)
- Also download Boost from SourceForge and unpack it in a directory of your choice (you specify it's path later on)
- Obtain, compile and install Inkscape svn following these instructions http://inkscape.org/win32/win32buildnotes.html
- unpackage the gsl bundle into the directory with the gtk bundle
- download cmake; install at `C:\cmake`
- check the directories in mingwenv.bat. Are they set correctly for you? (ignore RAGEL_BIN)
- make a build directory
- open cmd.exe
    ```
    mingwenv.bat
    cmake -G "MinGW Makefiles" c:\path\to\2geom # be sure you have a CAPITAL '-G' there!
    cmake -i # especially mind to set the install dir to where you want it installed (probably the gtk folder, e.g. c:/gtk210))
    mingw32-make
    ```
- copy the resulting `.exe` files into the inkscape install directory

If you want to be able to compile the ragel defined svg-parser as well,
you must download ragel from [here](http://www.cs.queensu.ca/~thurston/ragel/)
Unpack the windows binary package into a dir of your own choice.
Check whether ragel's dir is set correctly in mingwenv.bat (RAGEL_BIN).
Make sure you have ragel.exe and rlcodegen.exe in the dir you specify.
If your package does not contain rlcodegen.exe you can copy rlgen-cd.exe
and rename it to rlcodegen.exe :-)

## PYTHON BINDINGS
To install python bindings, you need python2 and cython(>=0.16). Get cython from
[http://www.lfd.uci.edu/~gohlke/pythonlibs/#cython](http://www.lfd.uci.edu/~gohlke/pythonlibs/#cython)
and install it to `$PYTHON_PATH\Libs\site-packages`
32-bit version is your safest bet.
cmake should be able to find cython now. Make sure that `PYTHON_PATH` is set
correctly to python2 in mingwenv.bat.

Continue with installation as described above. When running "cmake -i",
remember to choose to build cython bindings and also lib2geom as a
shared library!

If you get errors about missing DLL file, try copying lib2geom.dll to
cython-bindings directory.

Note: If you have both python2 and python3 installed, make sure cmake uses
python2. To ensure this, choose "advanced options" when running "cmake -i",
scroll and set PYTHON_INCLUDE_DIR and PYTHON_LIBRARY accordingly.

## TROUBLESHOOTING
If things don't work out, here is a list of things you can try.
Type `make --version`. It should display:
```
E:\inkscapelpe>mingw32-make --version
GNU Make 3.80
Copyright (C) 2002  Free Software Foundation, Inc.
```
Or something very similar. If it does not, probably windows finds a different
make (Borland's or another?). Type `set path=`, then start again with
`mingwenv.bat` etc...