[vspline] 01/72: Initial commit of README.rst

Sun Jul 2 09:02:36 UTC 2017

This is an automated email from the git hooks/post-receive script.

kfj-guest pushed a commit to branch master
in repository vspline.

commit c6483641d7c182ff6435ba93153c70dbb55eaf9f
Author: Kay F. Jahnke <kfjahnke at gmail.com>
Date:   Wed Oct 12 17:34:36 2016 +0200

    Initial commit of README.rst
---
 README.rst | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..11a1727
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,106 @@
+===================================================================
+vspline - generic C++ code to create and evaluate uniform B-splines
+===================================================================
+
+------------
+Introduction
+------------
+
+vspline aims to provide a free, comprehensive and fast library for uniform B-splines.
+
+Uniform B-splines are a method to provide a 'smooth' interpolation over a set of
+uniformly sampled data points. They are commonly used in signal processing as they
+have several 'nice' qualities - an in-depth treatment and comparison to other
+interpolation methods can be found in the paper 'Interpolation Revisited' [CIT2000]_
+by Philippe Thévenaz, Member, IEEE, Thierry Blu, Member, IEEE, and Michael Unser,
+Fellow, IEEE.
+
+While there are several freely available packets of B-spline code, I failed to find
+one which is comprehensive, efficient and generic at once. vspline attempts to be
+all that, making use of generic programming in C++, and of common, but often underused
+hardware features in modern processors. Overall, there is an emphasis on speed, even
+if this makes the code more complex. I tried to eke as much performance out of the
+hardware at my disposal as possible, only compromising when the other design goals
+would have been compromised.
+
+While some of the code is quite low-level, there are reasonably high-level mechanisms
+to interface with vspline, allowing easy access to it's functionality without requiring
+users to familiarize themselves with the internal workings. High-level approach is
+provided via class 'bspline' defined in bspline.h, and via the remap functions
+defined in remap.h.
+
+While I made an attempt to write code which is portable, vspline is only tested with
+gcc on Linux. It may work in other environments, but it's unlikely it will do so
+without modification. An installation of Vigra_ is needed to compile, installation
+of Vc_ is optional but recommended.
+
+vspline is relatively new, the current version might qualify as late beta.
+I have made efforts to cover 'reasonable' use cases, but I'm sure there are
+corner cases and unexpected scenarios where my code fails. The code is not
+well shielded against inappropriate parameters. The intended audience is
+developers rather than end users; if the code is used as the 'engine' in
+a well-defined way, parametrization can be tailored by the calling code.
+Parameter checking is avoided where it gets in the way of speedy operation.
+
+-----
+Scope
+-----
+
+There are (at least) two different approaches to tackle B-splines as a mathematical problem. The first one is to look at them as a linear algebra problem. Calculating the B-spline coefficients is done by solving a set of equations, which can be codified as banded diagonal matrices with slight disturbances at the top and bottom, resulting from boundary conditions. The mathematics are reasonably straightforward and can be efficiently coded (at least for lower-degree splines), but I found i [...]
+
+The second approach to B-splines comes from signal processing, and it's the one which I found most commonly used in the other implementations I studied. It generates the B-spline coefficients by applying a forward-backward recursive digital filter to the data and usually implements boundary conditions by picking appropriate initial causal and anticausal coefficients. Once I had understood the process, I found it elegant and beautiful - and perfectly general, lending itself to the impleme [...]
+
+I have made an attempt to generalize the code so that it can handle
+
+- arbitrary real data types and their aggregates [1]_
+- a reasonable selection of boundary conditions
+- used in either an implicit or an explicit scheme of extrapolation
+- arbitrary spline orders
+- arbitrary dimensions of the spline
+- in multithreaded code
+- using the CPU's vector units if possible
+
+On the evaluation side I provide
+
+- evaluation of the spline at point locations in the defined range
+- evaluation of the spline's derivatives
+- mapping of arbitrary coordinates into the defined range
+- evaluation of nD arrays of coordinates (generalized remap() function)
+- coordinate-transformation based remap function
+
+The code at the very core of my B-spline coefficient generation code evolved from the code by Philippe Thévenaz which he published here_, with some of the boundary condition treatment code derived from formulae which Philippe Thévenaz communicated to me. Next I needed code to handle multidimensional arrays in a generic fashion in C++. I chose to use Vigra_. Since my work has a focus on signal (and, more specifically image) processing, it's an excellent tool, as it provides a large body o [...]
+
+I did all my programming on a Kubuntu_ system, running on an intel(R) Core (TM) i5-4570 CPU, and used GNU gcc_ to compile the code. While I am confident that the code will run on other CPUs, I have not tested it with different compilers or operating systems (yet).
+
+.. _here: http://bigwww.epfl.ch/thevenaz/interpolation/
+.. _Vigra: http://ukoethe.github.io/vigra/
+.. _Vc: https://compeng.uni-frankfurt.de/index.php?id=vc 
+.. _Kubuntu: http://kubuntu.org/
+.. _gcc: https://gcc.gnu.org/
+
+.. [CIT2000] Interpolation Revisited by Philippe Thévenaz, Member,IEEE, Thierry Blu, Member, IEEE, and Michael Unser, Fellow, IEEE in IEEE TRANSACTIONS ON MEDICAL IMAGING, VOL. 19, NO. 7, JULY 2000, available online here_
+
+.. _online here: http://bigwww.epfl.ch/publications/thevenaz0002.pdf
+
+.. [1] I use 'aggregate' here to mean a collection of identical elements, in contrast to what C++ defines as an aggregate type. So aggregates would be pixels, vigra TinyVectors, and, also, complex types.
+
+-------------
+Documentation
+-------------
+
+There is reasonably comprehensive documentation for vspline, generated with doxygen, in the doc folder. TODO: link here to static HTML
+
+----------
+History
+----------
+
+Some years ago, I needed uniform B-splines for a project in python. I looked for code in C which I could easily wrap with cffi_, as I intended to use it with pypy_, and found K. P. Esler's libeinspline_. I proceeded to code the wrapper, which also contained a layer to process Numpy_ nD-arrays, but at the time I did not touch the C code in libeinspline. The result of my efforts is still available from the repository_ I set up at the time. I did not use the code much and occupied myself wi [...]
+
+.. _cffi: https://cffi.readthedocs.org/en/latest/
+.. _pypy: http://pypy.org/
+.. _libeinspline: http://einspline.sourceforge.net/
+.. _Numpy: http://www.numpy.org/
+.. _repository: https://bitbucket.org/kfj/python-bspline
+
+
+

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/vspline.git

