[vspline] 01/01: put LICENSE and README.rst back into master

Sat Sep 9 08:53: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 41c66483bd0f015c92eff59c796faf245c3e1f4c
Author: Kay F. Jahnke <kfjahnke at gmail.com>
Date:   Sat Sep 9 08:52:19 2017 +0000

    put LICENSE and README.rst back into master
---
 LICENSE    |  27 +++++++++++
 README.rst | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 180 insertions(+)

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..d4ebd66
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,27 @@
+vspline - generic C++ code for creation and evaluation
+          of uniform b-splines
+
+        Copyright 2015, 2016 by Kay F. Jahnke
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..1417fb4
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,153 @@
+===================================================================
+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++11, 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
+g++ and clang++ 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]_
+- coming in strided memory
+- 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 ('remap' function)
+- coordinate-fed remap function ('index_remap')
+- functor-based remap, aka 'transform' function
+- functor-based 'apply' 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 choice, as it provides a large body [...]
+
+I did all my programming on a Kubuntu_ system, running on an intel(R) Core (TM) i5-4570 CPU, and used GNU gcc_ and clang_ to compile the code in C++11 dialect. While I am confident that the code runs on other CPUs, I have not tested it with other 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/
+.. _clang: http://http://clang.llvm.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, which can be generated
+by running doxygen:
+
+doxygen vspline.doxy
+
+in vspline's base folder.
+
+There is also online documentation here:
+
+https://kfj.bitbucket.io
+
+-----
+Speed
+-----
+
+While performance will vary widely from system to system and between different compiles, I'll quote some measurements from my own system. I include benchmarking code (roundtrip.cc in the examples folder). Here are some measurements done with "roundtrip", working on a full HD (1920*1080) RGB image, using single precision floats internally - the figures are averages of several runs:
+
+::
+
+  testing bc code MIRROR spline degree 3
+  avg 32 x prefilter:........................ 13.093750 ms
+  avg 32 x remap from unsplit coordinates:... 59.218750 ms
+  avg 32 x remap with internal spline:....... 75.125000 ms
+  avg 32 x index_remap ...................... 57.781250 ms
+
+  testing bc code MIRROR spline degree 3 using Vc
+  avg 32 x prefilter:........................ 9.562500 ms
+  avg 32 x remap from unsplit coordinates:... 22.406250 ms
+  avg 32 x remap with internal spline:....... 35.687500 ms
+  avg 32 x index_remap ...................... 21.656250 ms
+
+As can be seen from these test results, using Vc on my system speeds evaluation up a good deal. When it comes to prefiltering, a lot of time is spent buffering data to make them available for fast vector processing. The time spent on actual calculations is much less. Therefore prefiltering for higher-degree splines doesn't take much more time (when using Vc):
+
+::
+
+  testing bc code MIRROR spline degree 5 using Vc
+  avg 32 x prefilter:........................ 10.687500 ms
+
+  testing bc code MIRROR spline degree 7 using Vc
+  avg 32 x prefilter:........................ 13.656250 ms
+
+Using double precision arithmetics, vectorization doesn't help so much, and prefiltering is actually slower on my system when using Vc. Doing a complete roundtrip run on your system should give you an idea about which mode of operation best suits your needs.
+
+----------
+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

