Requirements

The only external library that is absolutely necessary to make Ponca work is Eigen, the swiss army knife of linear algebra. Some examples will require additional libraries in an effort to keep them lean and legible. We'll try to keep these dependencies to the minimum necessary, promised.

The modules are also compatible with CUDA, so that you may run Ponca on the GPU, provided you own an NVidia graphics card. This is an efficient way to make Ponca available through CUDA-compatible languages such as Matlab or Python. Eigen can be compiled by nvcc (NVIDIA CUDA Compiler Driver), see Eigen documentation for more details.

Download

The Ponca library is currently under active development and some functionalities have already been implemented and thoroughly tested. If you want to get a taste of these prime features, use the latest package available here: https://github.com/poncateam/ponca/releases/latest/.

You may also want to monitor our efforts in developing the library, in which case you will want to access the development repository and use the master branch:

git clone https://github.com/poncateam/ponca.git

Installation

Ponca is an header-only library. It could not be easier to install: the only thing you have to do is to include the main header in your code.

#include <Ponca/Ponca>

Use as cmake subdirectory

Ponca can be included in existing cmake projects using add_subdirectory, as demonstrated at https://github.com/poncateam/ci-submodule-helper. In this example, Ponca is included as a git submodule, and included in the main CMakeLists.txt as follow:

find_package(Eigen3 QUIET)
 
add_subdirectory(ponca)
 
add_executable(test main.cpp)
target_link_libraries(test Ponca::Fitting)

Cmake package

We also provide a relocatable cmake package, generated by the install target. Example of file CMakeLists.txt using Ponca's cmake package:

cmake_minimum_required(VERSION 3.11)
 
project(PoncaTest LANGUAGES CXX)
 
find_package(Ponca REQUIRED)
 
add_executable(test main.cpp)
target_link_libraries(test Ponca::Fitting)

CPM

CPM is a CMake package manager that allows to download, compiles and manages dependancies with a single line of cmake. Ponca is compatible with CPM. Once the CPM.cmake file downloaded, the following script will get you started with the library:

cmake_minimum_required(VERSION 3.11)
project(PoncaTest LANGUAGES CXX)
 
include(CPM.cmake) # Or any path to the downloaded file
CPMAddPackage("gh:poncateam/ponca#master") # This will download ponca and run its cmake automatically
 
add_executable(test main.cpp)
target_link_libraries(test PRIVATE Ponca::Fitting) # Or any other Ponca defined modules

You may also specify other branches, tags or commit and options within the CPMAddPackage call. See CPM documentation for more information.

Compilation

If you want to see Ponca in action, you will of course have to compile examples. And the same is true if you want to get the latest version of the documentation you are presently reading (well, not the exact same documentation, unless you've already compiled it, but then why are you reading this?). In both cases, you will have to use cmake, e.g.:

cmake . -B build # Creates build folder and run cmake in it

Available cmake options:

## USER OPTIONS
##
 
OPTION( PONCA_CONFIGURE_EXAMPLES   "Include compilation rules for built-in examples"      ON)
OPTION( PONCA_CONFIGURE_DOC        "Include compilation rules for built-in documentation" ON)
OPTION( PONCA_CONFIGURE_TESTS      "Include compilation rules for built-in tests"         ON)
OPTION( PONCA_GENERATE_IDE_TARGETS "Generate targets to show source files in IDEs"        ON)
 
##
## END USER OPTIONS

Then compile using

cmake --build . --target TARGET

with TARGET equals to:

ponca-doc: generate documentation using Doxygen (requires PONCA_CONFIGURE_DOC)
ponca-examples: compile examples (requires PONCA_CONFIGURE_EXAMPLES)
install: generate relocable cmake package and install to CMAKE_INSTALL_PREFIX. Also install the documentation if previously compiled.
buildtests: compile tests (requires PONCA_CONFIGURE_TESTS)
test: run tests (you may also use ctest directly

Reducing compile time

Note: This section is not available for MSVC (windows default compiler). If MSVC is detected, the Instantiate target will become an empty library hence CMake code remains valid.

The (quite heavy) use of templates in some modules may increase compilation times. In order to alleviate the burden, we provide a shared library that pre-instantiate what we believe to be classical usage of the library. This shift most of the compilation burder to the shared library instead of a more frequently compiled code.

In order to benefit from using the library the only step necessary is to link with Ponca::Instantiate

target_link_libraries(your_target PUBLIC Ponca::Instantiate)

CMake will automatically build the Instantiate library the first time required. Depending on the option, this can be quite long.

Instantiation parameters

By default, the Instantiate library will compile every use case we thought of: 2D, 3D, float, double, with and without normal... Each parameters typically double the compilation time of the library without a target needed it. Fortunately, multiple flags can be passed in order to select more carefully what is needed:

PONCA_INSTANTIATE_ALL [On by default, should be turned off. Has priority over every other flags]
PONCA_INSTANTIATE_DOUBLE
PONCA_INSTANTIATE_FLOAT
PONCA_INSTANTIATE_2D
PONCA_INSTANTIATE_3D
PONCA_INSTANTIATE_POINTPOSITION
PONCA_INSTANTIATE_POINTPOSITIONNORMAL
PONCA_INSTANTIATE_SMOOTHWEIGHT
PONCA_INSTANTIATE_CONSTANTWEIGHT
PONCA_INSTANTIATE_NOWEIGHT
PONCA_INSTANTIATE_SPACEDER
PONCA_INSTANTIATE_SCALESPACEDER

Each flag can be turned on/off. In order for anything to be compiled, you need to select at least a dimension, a scalar type, a point type, a filter and, for derivatives, a derivative type.

First steps

You're now ready to play with Ponca! Checkout the user manual here: User Manual.

If you get stuck or have a problem/bug using Ponca, please open an issue here: https://github.com/poncateam/ponca/issues. Remember that the library is under development so we are pleased to get your feedback.