diff --git a/README.md b/README.md index 4ec5574..4cc84dc 100644 --- a/README.md +++ b/README.md @@ -1,127 +1,131 @@ -# HYPERCURVE -![Hybrid hypercurve](doc/png/hybrid.png) +# Hypercurve Documentation +![Hybrid Hypercurve](doc/png/hybrid.png) -# What is it ? +## What is it? -Hypercurve is a library allowing you to combine several curve algorithms into a single 2D envelope. It is designed to be used in audio applications, for people who know how to enjoy a finely shaped curve. -As shown above, you can perfectly combine gaussian curve with diocles cissoid curve, and plenty of other curve algorithms. -The library can be used in C++, Lua, Csound and Faust. +Hypercurve is a library that allows you to combine several curve algorithms into a single 2D envelope. It is designed to be used in audio applications, for those who appreciate a finely shaped curve. +As shown above, you can perfectly combine Gaussian curves with Diocles cissoid curves and many other curve algorithms. +The library can be used in C++, Lua, Csound, and Faust. -Every curve algorithm is different. In audio applications, we use to assign envelopes to any kind of parameter. In computer music, the way a value goes up and down in time has a big influence on how we hear a sound. Thus, the possibility to create finely shaped envelopes is truly essential. This is the purpose of Hypercurve. +Every curve algorithm is different. In audio applications, we use envelopes to control any kind of parameter. In computer music, the way a value changes over time has a significant influence on how we perceive sound. Thus, the ability to create finely shaped envelopes is essential. This is the purpose of Hypercurve. -The above hypercurve is a combination of 1/8 diocles curve, 1/8 toxoid curve, 2/8 mouth curve, and 4/8 gauss curve. - - -## Implemented curve algorithms +The above hypercurve is a combination of 1/8 Diocles curve, 1/8 Toxoid curve, 2/8 Mouth curve, and 4/8 Gaussian curve. +## Implemented Curve Algorithms - Cissoid (Diocles curve) - Cubic - Power curve (choose your power of x) - Bezier (Cubic & Quadratic) - Cubic Spline - Not implemented in Csound yet -- Catmull Rom Spline -- Hanning / Hamming / Blackamn -- Gauss +- Catmull-Rom Spline +- Hanning / Hamming / Blackman +- Gaussian - Toxoid (aka duplicatrix_cubic) - Catenary (aka funicular) - Tightrope Walker curve - Mouth curve - Bicorn curve -- Easing curves - from https://github.com/ai/easings.net - translated to C++ -- Typed curves : inspired from Csounds [GEN16](http://www.csounds.com/manual/html/GEN16.html) -- User defined curves - pass it a function (or a lambda in C++), that returns y for any x between 0 and 1. Not implemented in Csound. - -## How to install, and make it work +- Easing curves - from [easings.net](https://github.com/ai/easings.net) - translated to C++ +- Typed curves: inspired by Csound's [GEN16](http://www.csounds.com/manual/html/GEN16.html) +- User-defined curves: pass it a function (or a lambda in C++), that returns y for any x between 0 and 1. Not implemented in Csound. -Go to [Releases](https://github.com/johannphilippe/hypercurve/releases), and download the latest version. +## How to Install and Use It +Go to [Releases](https://github.com/johannphilippe/hypercurve/releases) and download the latest version. -### Csound install +### Csound Install -To install HYPERCURVES opcodes for Csound, the recommanded way is to move the csound_hypercurve library to the plugins repository of Csound. +To install HYPERCURVE opcodes for Csound, move the `csound_hypercurve` library to the plugins repository of Csound. -Usually, the following instructions will work. If Csound is installed in another location, just change the following path : +* **Windows:** Move `csound_hypercurve.dll` to `C:/Program Files/Csound6_x64/plugins64/`. +* **MacOS:** Move `libcsound_hypercurve.dylib` to `/Library/Frameworks/CsoundLib64.framework/Versions/6.0/Resources/Opcodes64`. +* **Linux (Debian):** Move `libcsound_hypercurve.so` to `/usr/local/lib/csound/plugins64/`. -* On Windows, move `csound_hypercurve.dll` to `C:/Program Files/Csound6_x64/plugins64/`. -* On MacOS, move `libcsound_hypercurve.dylib` to `/Library/Frameworks/CsoundLib64.framework/Versions/6.0/Resources/Opcodes64` -* On Linux (debian), move `libcsound_hypercurve.so` to `/usr/local/lib/csound/plugins64/` +### Lua Use -### Lua use +On any OS where Hypercurve is compiled, you can write a Lua script using Hypercurve in the Hypercurve directory and execute it from the terminal with `./luajit myscript.lua`. Replace `myscript.lua` with the name of your script. +On Windows, use `./luajit.exe myscript.lua`. -On every OS Hypercurve is compiled for, you can write a lua script using Hypercurve in the Hypercurve directory and just use it from the terminal with `./luajit myscript.lua`. Just change `myscript.lua` to the name of your script. -On Windows, it should be ̀`./luajit.exe myscript.lua`. -## How to use it +## How to Use It +There are four ways to use it: in C++, Csound, Faust, or Lua. CMake will help you build libraries that can be used in those languages. You will find C++ examples under `hypercurve_test/test.cpp`, Csound examples under `csound_opcode/test.csd`, and Lua examples under `lua_module/test.lua`. -There are three ways to use it : in C++, Csound, Faust or in Lua. Cmake will help you build libraries that can be used in those languages. You will find C++ example under hypercurve_test/test.cpp, Csound example under csound_opcode/test.csd, and Lua example under lua_module/test.lua. - -The basic syntax stands as follow : +The basic syntax is as follows: * `hypercurve(integer size, double y_start, {segment_list});` -Where `size` is the size in samples, `y_start` is the starting point of the curve, and segment list is a list of segments. -* `segment(double frac, double y_destination, curve_type crv);` -Where `frac` is the fractional size of the segment (fraction between 0 and 1), `y_destination` is the target point, and `crv` a curve algorithm picked from hypercurve. + - `size`: The size in samples + - `y_start`: The starting point of the curve + - `segment_list`: A list of segments +* `segment(double frac, double y_destination, curve_type crv);` + - `frac`: The fractional size of the segment (fraction between 0 and 1) + - `y_destination`: The target point + - `crv`: A curve algorithm picked from Hypercurve -## A simple C++ example +## A Simple C++ Example ```c++ -#include"hypercurve.h" +#include "hypercurve.h" using namespace hypercurve; + const int definition = 16384; double y_start = 0; + curve c(definition, y_start, - { - // segment(fractional_size, y_destination, curve - segment(fraction(1,2), 1.0, share(cissoid_curve(1))), - segment(0.5, 0.0, share(blackman_curve())) - }); +{ + // segment(fractional_size, y_destination, curve) + segment(fraction(1, 2), 1.0, share(cissoid_curve(1))), + segment(0.5, 0.0, share(blackman_curve())) +}); + // Then access samples with double *get_samples() c.get_samples(); ``` -## A simple Csound example +## A Simple Csound Example ```csound instr 1 - icrv = hc_hypercurve(2048, 0, - hc_segment(1/2, 1, hc_diocles_curve(1)), - hc_segment(1/2, 0, hc_hanning_curve())) - kenv = tablei:k(linseg:k(0, p3, 1), icrv, 1) - ao = vco2(0.3, 300) * kenv - outs(ao, ao) + icrv = hc_hypercurve(2048, 0, + hc_segment(1/2, 1, hc_diocles_curve(1)), + hc_segment(1/2, 0, hc_hanning_curve())) + kenv = tablei:k(linseg:k(0, p3, 1), icrv, 1) + ao = vco2(0.3, 300) * kenv + outs(ao, ao) endin ``` -## A simple Lua example +## A Simple Lua Example ```lua package.cpath = package.cpath .. ";/your/path/to/hypercurve/?.so;" local hc = require("liblua_hypercurve") local definition = 16384 local y_start = 0 + local crv = hc.hypercurve(definition, y_start, - { - hc.segment(1/2, 1.0, hc.cissoid_curve(1.0)), - hc.sement(1/2, 0.0, hc.cubic_curve(0.0)) - }) -// Write as 24 bits 48KHz wav +{ + hc.segment(1/2, 1.0, hc.cissoid_curve(1.0)), + hc.segment(1/2, 0.0, hc.cubic_curve(0.0)) +}) + +-- Write as 24 bits 48KHz wav hc.write_as_wav("path/to/outfile.wav", crv) ``` -## A simple Faust example +## A Simple Faust Example - -```Faust +```faust hc = library("hypercurve.lib"); definition = 16384; y_start = 0; -curve = hc.hypercurve(definition, y_start ( - hc.segment(1/2, 1.0, hc.cissoid_curve(1.0)), - hc.segment(1/2, 0.0, hc.cubic_curve) + +curve = hc.hypercurve(definition, y_start, ( + hc.segment(1/2, 1.0, hc.cissoid_curve(1.0)), + hc.segment(1/2, 0.0, hc.cubic_curve) )); // Run with interpolation @@ -131,114 +135,119 @@ env = hc.runi(curve, os.phasor(1, 1)); # Build -First clone the repo with submodules : -``` git clone https://github.com/johannphilippe/hypercurve.git --recurse-submodules ``` -You should check that Lua is installed on your system. If it is not, or if compilation retrns error, you should install a Lua 5.1 version to the standard installation path. Make sure you have the dynamic library installed, and the headers `lauxlib.h` and `lua.h` are available on your system. -Then : +First, clone the repo with submodules: + +```bash +git clone https://github.com/johannphilippe/hypercurve.git --recurse-submodules ``` + +Ensure that Lua is installed on your system. If not, or if compilation returns errors, install a Lua 5.1 version in the standard installation path. Make sure you have the dynamic library installed, and the headers `lauxlib.h` and `lua.h` are available on your system. + +```bash cd hypercurve mkdir build && cd build cmake .. -DBUILD_ALL=TRUE make ``` -If you just want to build for Faust, Lua or Csound, then just use -``` + +If you only want to build for a specific language, use: + +```bash cmake .. -DBUILD_CSOUND_OPCODE=TRUE cmake .. -DBUILD_LUA_MODULE=TRUE cmake .. -DBUILD_FAUST_LIB=TRUE ``` -On some platforms (e.g. Windows) you might need to set the Lua paths with the following options : -``` -cmake .. -DBUILD_LUA_MODULE=TRUE -DLUA_INCLUDE_DIR=/you/dir/include -DLUA_LIBRARIES=/path/to/lua.lib -``` +On some platforms (e.g., Windows), you may need to set the Lua paths with the following options: + +```bash +cmake .. -DBUILD_LUA_MODULE=TRUE -DLUA_INCLUDE_DIR=/your/dir/include -DLUA_LIBRARIES=/path/to/lua.lib +``` -Windows build for Lua is a bit more complicated, due to the way Windows searches for dynamic libraries. Wheter you provide `LUA_LIBRARIES` yourself or let CMake find it, you will need the `.lib` and `.dll` libraries of Lua to share the same name (except the extension) and the same path (as it is the case in standard Lua distributions). This will allow CMake to copy the Lua `.dll` dynamic library next to `lua_hypercurve` in the bin folder. +For Windows builds, ensure that the `.lib` and `.dll` libraries of Lua share the same name and path. This will allow CMake to copy the Lua `.dll` dynamic library next to `lua_hypercurve` in the bin folder. -In order to build the Faust library, you will need [Quom](https://pypi.org/project/quom/) to be installed in your system. See the Faust [README](faust_lib/README.md) +To build the Faust library, you will need [Quom](https://pypi.org/project/quom/) installed on your system. See the Faust [README](faust_lib/README.md). The PNG writer [fpng](https://github.com/richgel999/fpng) used for hypercurve has SSE support. This can be enabled with `-DSSE=1`. -The resulting binaries will all be located in `bin` directory. On Windows, `lua_hypercurve.dll` and `hypercurve.dll` require `sndfile.dll` to be in the same folder. `lua_hypercurve.dll` also requires the Lua `.dll` you linked against (e.g. `lua5.1.dll`). -This must be considered when packaging the library to be embedded or used by another application. +The resulting binaries will be located in the `bin` directory. On Windows, `lua_hypercurve.dll` and `hypercurve.dll` require `sndfile.dll` in the same folder. `lua_hypercurve.dll` also requires the Lua `.dll` you linked against (e.g., `lua5.1.dll`). This must be considered when packaging the library for use in other applications. -# WASM/WASI port +## WASM/WASI Port -After hours of tests, I'm struggling with this. I have not much knowledge about web, neither about Web Assembly. -I probably need help. +After hours of testing, I'm struggling with this. I have little knowledge about web technologies or Web Assembly. I probably need help. # TODO -* Interpolating curve parameters : something like `hc_diocles(hc_linspace(0.5 , 1, 1024))` to create interpolating parameters with hypercurve itself -* Remove "_curve" suffix from everywhere (useless) +* Interpolating curve parameters: something like `hc_diocles(hc_linspace(0.5 , 1, 1024))` to create interpolating parameters with hypercurve itself +* Remove the "_curve" suffix from everywhere (unnecessary) +* Fix: Lagrange polynomial returns NaN and doesn't scale well +* Fixed: Major scaling issue when creating complex curves (going below 1 after exceeding 1) +* Fix: Remove `#include OpcodeBase.cpp` +* Move to template (float, double, or long double) +* Use `MYFLT` instead of `double` for Csound -* To fix : Lagrange polynomial returns nan, and doesn't scal well -* Fixed : Major scaling issue when creating complex curves (going down after being more than 1) -* To fix : remove #include OpcodeBase.cpp -* Move to template (float or double or long double) -* Same for Csound -> MYFLT instead of double -Ideas : +## Ideas + * Inversion across the axis of another curve -* Rename vinvert to reflect the fact it's not vertical symmetry, but linear axis vertical reflection +* Rename `vinvert` to reflect that it's not vertical symmetry but linear axis vertical reflection * Implement real vertical symmetry -* Implement that for full curves also -* Reflect those changes to doc +* Implement for full curves as well +* Reflect these changes in the documentation -* Subdivide segments (only take an upsampled half for example) -* Interp(0.25) returns an interpolation of two curves (crv1 * 0.25, crv2 * 0.75) -* extract curve -> subsample from audio, or another method (based on relevant samples) -* Abs for waveforms -* Virtual 3D manipulation (rotate z axis, but in reality the curve is still 2D) +* Subdivide segments (e.g., only take an upsampled half) +* `Interp(0.25)` returns an interpolation of two curves (`crv1 * 0.25, crv2 * 0.75`) +* Extract curve -> subsample from audio or another method (based on relevant samples) +* Implement absolute value for waveforms +* Virtual 3D manipulation (rotate z-axis, but the curve remains 2D) -* Improve hc_resize to resize curve without creating new one (temp memory) -* Documentation on hc_resize, and hc_cubic_spline_curve -* Propagate resize to Lua, Faust and C++ api +* Improve `hc_resize` to resize the curve without creating a new one (use temporary memory) +* Documentation on `hc_resize` and `hc_cubic_spline_curve` +* Propagate resizing to Lua, Faust, and C++ APIs -* Csound Gen automatic number : does not take "f" statements into account (collision) +* Csound Gen automatic number: does not take "f" statements into account (collision) * Expose random generators to frontends (Lua, Csound, Faust). -* Lagrange interpolation for curve extraction ? +* Lagrange interpolation for curve extraction? + +## Curves to Implement -## Curves to implement * Cardioid / hypercardioid -* Elastic curve : https://mathcurve.com/courbes2d.gb/linteaire/linteaire.shtml -* Simple log/exp ? +* Elastic curve: [Elastic Curve](https://mathcurve.com/courbes2d.gb/linteaire/linteaire.shtml) +* Simple logarithmic/exponential? * Kulp quartic -* Puntiforme https://mathcurve.com/courbes2d/puntiforme/puntiforme.shtml -* Legendre polynome -* Ideas here https://mathcurve.com/courbes2d/courbes2d.shtml +* Puntiforme: [Puntiforme Curve](https://mathcurve.com/courbes2d/puntiforme/puntiforme.shtml) +* Legendre polynomial +* More ideas: [Math Curves](https://mathcurve.com/courbes2d/courbes2d.shtml) ## AI Hypercurves -NOTE : Start with markov models training first, not to burn your hands. -Find an environment : C++ ? Ruby (lack audio libs..) ? Python (lack hypercurve support) ? Lua (lack everything else support) ? - -Idea to implement a nn or another ML stuff to generate Hypercurves with a prior : -* Prior : generates curves -* No prior : reacts with curves to audio input (will be delayed, since curve is a large scale compared to audio) +**Note:** Start with Markov models training first to avoid complexity. +Find a suitable environment: C++? Ruby (lacks audio libraries)? Python (lacks hypercurve support)? Lua (lacks support for everything else)? -* First create a dataset with audio -* Take RMS of audio and determine curve boundaries - * Other parameters could be possible (like check the filtering by finding the resonant - most powerful - frequency, or f0) -* Train model - - With labels : hypercurves - - Without : with test to see which one fits best (difference of curves, or something more sophisticated) - - -* Try RAVE with interpolated unipolar audio examples (wont work because it is thought to make fast changes for audio construction) ? +Idea: Implement a neural network or another machine learning model to generate Hypercurves with a prior: +* **Prior:** Generates curves. +* **No prior:** Reacts with curves to audio input (there will be a delay, since curves operate on a larger scale compared to audio). +* First, create a dataset with audio. +* Take the RMS of the audio and determine curve boundaries. + * Other parameters could be possible (e.g., check the filtering by finding the resonant - most powerful - frequency, or `f0`). +* Train the model: + * With labels: hypercurves. + * Without: testing which one fits best (difference of curves, or something more sophisticated). -# External libraries +* Try RAVE with interpolated unipolar audio examples (may not work due to its design for quick changes in audio construction). -The project uses LuaJIT as a submodule, allowing you to try HYPERCURVE out of the box. +# External Libraries -It also includes source files from several open-source projects : -* [AsciiPlot](https://github.com/joehood/asciiplotter) source code with license under src/asciiplot folder. -* [lua-compat-5.3](https://github.com/keplerproject/lua-compat-5.3) which provides an API compatibility from 5.1 to 5.3 -* [fpng](https://github.com/richgel999/fpng) - a great C++ PNG reader/writer.`` -* [this work](https://github.com/ai/easings.net) +The project uses LuaJIT as a submodule, allowing you to try Hypercurve out of the box. +It also includes source files from several open-source projects: +* [AsciiPlot](https://github.com/joehood/asciiplotter): Source code with license under `src/asciiplot` folder. +* [lua-compat-5.3](https://github.com/keplerproject/lua-compat-5.3): Provides an API compatibility from 5.1 to 5.3. +* [fpng](https://github.com/richgel999/fpng): A great C++ PNG reader/writer. +* [Easing Curves](https://github.com/ai/easings.net): Derived from this work and licensed as GNU General Public License 3. -# LICENSE +# License -The core of HYPERCURVE is licensed wit MIT. -Easing curves - located in curve_lib.h - are derived from [this work](https://github.com/ai/easings.net) and thus are licensed as GNU General Public License 3. +The core of Hypercurve is licensed under the MIT License. +Easing curves, located in `curve_lib.h`, are derived from [this work](https://github.com/ai/easings.net) and are thus licensed under the GNU General Public License 3. diff --git a/Version.md b/Version.md index 4b6e51e..529a6ac 100644 --- a/Version.md +++ b/Version.md @@ -4,7 +4,7 @@ First release # 0.0.2 -## New +## New - Faust (FFI) implementation - "_curve" suffix for all curve algorithm (curve_base) in every frontend (including Lua) @@ -24,5 +24,3 @@ First release - Fixed size issues with 0 padding when one sample is missed (fractional size divided by 3, 6, 9 ...) - Fixed Cubic Spline allocation issues - PNG memory issue - writing out of bounds - - diff --git a/doc/README.md b/doc/README.md index 74d035a..beb431f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,147 +1,110 @@ -# Hypercurve documentation - +# Hypercurve Documentation + ![Hybrid Hypercurve](png/hybrid.png) -Hypercurve is a library of 2D curves designed to process audio envelopes, applied to any audio parameter. -It is available in several frontends : C++, Lua, and Csound. +Hypercurve is a library of 2D curves designed to process audio envelopes, applied to any audio parameter. It is available in several frontends: C++, Lua, Faust, and Csound. -- [Hypercurve documentation](#hypercurve-documentation) - - [Hypercurve basic syntax](#hypercurve-basic-syntax) - - [Import hypercurve](#import-hypercurve) - - [Hypercurve class](#hypercurve-class) +## Table of Contents + +- [Hypercurve Documentation](#hypercurve-documentation) + - [Hypercurve Basic Syntax](#hypercurve-basic-syntax) + - [Import Hypercurve](#import-hypercurve) + - [Hypercurve Class](#hypercurve-class) - [Segment](#segment) - - [Control point](#control-point) + - [Control Point](#control-point) - [Curve Base](#curve-base) - - [Diocles cissoid curve](#diocles-cissoid-curve) - - [Cubic curve](#cubic-curve) - - [Power curve](#power-curve) - - [Hamming Hanning Blackman curves](#hamming-hanning-blackman-curves) - - [Gaussian curve](#gaussian-curve) - - [Toxoid curve](#toxoid-curve) - - [Catenary curve](#catenary-curve) - - [Tightrope Walker curve](#tightrope-walker-curve) - - [Quadratic Bezier curve](#quadratic-bezier-curve) - - [Cubic Bezier curve](#cubic-bezier-curve) - - [Cubic spline curve](#cubic-spline-curve) - - [Catmull Rom spline curve](#catmull-rom-spline-curve) - - [Polynomial curve](#polynomial-curve) - - [User defined curve](#user-defined-curve) - - [Typed Curve](#typed-curve) - - [Mouse Curve](#mouse-curve) - - [Bicorn Curve](#bicorn-curve) - - [Lagrange polynomial curve](#lagrange-polynomial-curve) - - [Logarithmic and exponential Curve](#logarithmic-and-exponential-curve) - - [Easing curves](#easing-curves) - - [Manipulation Tools](#manipulation-tools) - - [Hypercurve Operators](#hypercurve-operators) - - [Mirror curve base](#mirror-curve-base) - - [Concatenate hypercurves](#concatenate-hypercurves) - - [Utilities](#utilities) + - [Diocles Cissoid Curve](#diocles-cissoid-curve) + - [Cubic Curve](#cubic-curve) + - [Power Curve](#power-curve) + - [Hamming, Hanning, Blackman Curves](#hamming-hanning-blackman-curves) + - [Gaussian Curve](#gaussian-curve) + - [Toxoid Curve](#toxoid-curve) + - [Catenary Curve](#catenary-curve) + - [Tightrope Walker Curve](#tightrope-walker-curve) + - [Quadratic Bezier Curve](#quadratic-bezier-curve) + - [Cubic Bezier Curve](#cubic-bezier-curve) + - [Cubic Spline Curve](#cubic-spline-curve) + - [Catmull-Rom Spline Curve](#catmull-rom-spline-curve) + - [Polynomial Curve](#polynomial-curve) + - [User Defined Curve](#user-defined-curve) + - [Typed Curve](#typed-curve) + - [Mouse Curve](#mouse-curve) + - [Bicorn Curve](#bicorn-curve) + - [Lagrange Polynomial Curve](#lagrange-polynomial-curve) + - [Logarithmic and Exponential Curve](#logarithmic-and-exponential-curve) + - [Easing Curves](#easing-curves) + - [Manipulation Tools](#manipulation-tools) + - [Hypercurve Operators](#hypercurve-operators) + - [Mirror Curve Base](#mirror-curve-base) + - [Concatenate Hypercurves](#concatenate-hypercurves) + - [Utilities](#utilities) 8 [Utilities](#utilities) -## Hypercurve basic syntax - +## Hypercurve Basic Syntax -Here is a simple example of syntax with possible use cases : +Here is a simple example of syntax with possible use cases: - - -C++ : +### C++: ```c++ - -auto crv = hypercurve::hypercurve( 2048, 0, { - // In C++, segment is expecting a curve_base of type shared_ptr - +auto crv = hypercurve::hypercurve(2048, 0, { +// In C++, segment is expecting a curve_base of type shared_ptr hypercurve::segment(0.5, 1, hypercurve::share(hypercurve::cubic_curve())), - hypercurve::segment(0.5, 0, hypercurve::share(hypercurve::diocles_curve(1))) - }); - // Get samples values like below - +// Get sample values double sample = crv.get_sample_at(1024); - double *samples = crv.get_samples(); - -// Write the curve as PNG file - +// Write the curve as a PNG file hypercurve::png png; - bool fill = true; - bool waveform = false; - png.draw_curve(samples, crv.get_definition(), fill, waveform); - png.write_png("my/path/to.png"); -// Write the curve as WAV file (Sndfile is linked to hypercurve) - -SndfileHandle sf(path , SFM_WRITE, SF_FORMAT_WAV | SF_FORMAT_PCM_24, 1, 48000); - +// Write the curve as a WAV file (Sndfile is linked to hypercurve) +SndfileHandle sf(path, SFM_WRITE, SF_FORMAT_WAV | SF_FORMAT_PCM_24, 1, 48000); sf.writef(crv.get_samples(), crv.get_definition()); - ``` - - -Lua : - -```Lua - -local crv = hc.hypercurve(2048, 0, { - -hc.segment(0.5, 1, hc.cubic_curve()) +### Lua: +```lua +local crv = hc.hypercurve(2048, 0, { +hc.segment(0.5, 1, hc.cubic_curve()), hc.segment(0.5, 0, hc.cissoid_curve(1)) - }) - - crv:ascii_display("MyHybridCurve", "half cubic, half cissoid", "*") -local fill = true -- optional default to true - -local is_waveform = false -- optional, default to false ,waveform will scale the png from -1 to 1 - -local draw_grid = true -- optional, default to true - -local invert_color = false -- optional, default to false +local fill = true -- optional, defaults to true +local is_waveform = false -- optional, defaults to false, waveform will scale the PNG from -1 to 1 +local draw_grid = true -- optional, defaults to true +local invert_color = false -- optional, defaults to false crv:write_as_png("path_to/curve.png", is_waveform, fill, draw_grid, invert_color) -- arguments after path are optional +crv:write_as_wav("path/curve.wav") -crv:write_as_wav( "path/curve.wav" ) - - --- rescale the curve - +-- Rescale the curve crv:scale(-1, 1) -local samp = crv:get_sample_at(1024) - -local samps = crv:get_samples() - +local samp = crv:get_sample_at(1024) +local samps = crv:get_samples() ``` - - -Csound : - -```Csound +### Csound: +```csound icrv = hc_hypercurve(0, 2048, 0, - hc_segment(0.5, 1, hc_cubic_curve()), +hc_segment(0.5, 0, hc_cissoid_curve(1)) +) -hc_segment(0.5, 0, hc_cissoid_curve(1))) - -// Arguments after path are optional +// Arguments after path are optional // is_waveform (0 or 1) default to 0 // fill (0 or 1) default to 1 // draw_grid (0 or 1) default to 1 @@ -150,817 +113,606 @@ hc_write_as_png(icrv, "my/path/curve.png", 0, 1, 1, 1) // Alias for hc_hypercurve is hc_gen gidiocles = hc_gen(0, 2048, 0, - hc_segment(1/2, 1, hc_diocles_curve(0.51)), - hc_segment(1/2, 0, hc_diocles_curve(1.5))) +hc_segment(1/2, 1, hc_diocles_curve(0.51)), +hc_segment(1/2, 0, hc_diocles_curve(1.5))) // It can then be used as any FTable, with Csound opcodes that use FTables kenv = tablei:k(linseg(0, p3, 1), gidiocles, 1) - ``` - -Faust : -``` +### Faust: + +```faust curve = hc.hypercurve(2048, 0, ( - hc.segment(0.5, 1, hc.cubic_curve()), - hc.segment(0.5, 0, hc.cissoid_curve(0.6)) - )); +hc.segment(0.5, 1, hc.cubic_curve()), +hc.segment(0.5, 0, hc.cissoid_curve(0.6)) +)); env = hc.run(curve, os.phasor(1, 1)); - ``` - - -## Import hypercurve - +## Import Hypercurve -C++ : +### C++: ```c++ - -#include"hypercurve.h" - +#include "hypercurve.h" ``` -Lua : - -```Lua +### Lua: +```lua -- In the following line, replace .so with your library extension (dll on Windows or dylib on Macos) - package.cpath = package.cpath .. ";/your/path/to/hypercurve/?.so" - -local hc = require("liblua_hypercurve") - +local hc = require("liblua_hypercurve") ``` -Csound : +### Csound: -In csound you can manually import the library like below, or simply put the library in csound plugins path. - -```Csound +In Csound, you can manually import the library as shown below, or simply place the library in the Csound plugins path. +```csound - --opcode-lib=/your/path/to/libcsound_hypercurve.so - - ``` -Faust : -``` +### Faust: + +```faust hc = library("hypercurve.lib"); ``` - -## Hypercurve class +## Hypercurve Class - -C++ : +### C++: ```c++ - auto crv = hypercurve::curve(size_t size_in_samples, double y_start, std::vector segment_list); // With possible alias - auto crv = hypercurve::curve(size_t size_in_samples, double y_start, std::vector segment_list); - ``` -Lua : - -```Lua - -local crv = hc.hypercurve(integer size_in_samples, number y_start, table {segments}) +### Lua: +```lua +local crv = hc.hypercurve(integer size_in_samples, number y_start, table {segments}) ``` -Csound : - -```Csound - -icrv = hc_hypercurve(int isize_in_samples, float iy_start, isegment1 , [isegment2, isegment3...]) +### Csound: +```csound +icrv = hc_hypercurve(int isize_in_samples, float iy_start, isegment1, [isegment2, isegment3...]) ``` -Faust : -``` -curve = hc.hypercurve(int size_in_samples, float y_start, (list_of_segments) ); +### Faust: + +```faust +curve = hc.hypercurve(size_in_samples, y_start, (list_of_segments)); ``` ## Segment -An hypercurve is composed with a list of one or more segments. Each segment have a fractional size (0-1 range), a destination in y axis, and a curve_base wich represents the algorithm. +A hypercurve is composed of one or more segments. Each segment has a fractional size (0-1 range), a destination on the y-axis, and a curve_base, which represents the algorithm. -C++ : +### C++: ```c++ - auto seg = hypercurve::segment(double fractional_size, double y_destination, std::shared_ptr curve_type); - ``` -Lua : - -```Lua - -local seg = hc.segment(number fractional_size, number y_destination, curve_base) +### Lua: +```lua +local seg = hc.segment(number fractional_size, number y_destination, curve_base) ``` -Csound : - -```Csound - -iseg = hc_segment(float fractional_size, float y_destination, curve_base icrv_base) +### Csound: +```csound +iseg = hc_segment(float fractional_size, float y_destination, curve_base, icrv_base) ``` -Faust : -``` -seg = hc.segment(float fractional_size, float y_destination, curve_base crv_base); +### Faust: + +```faust +seg = hc.segment(fractional_size, y_destination, curve_base, crv_base); ``` -## Control point +## Control Point -Some curve_base algorithms need control points to process their interpolation : splines and bezier curves. -A control point is a simple point in 2D space with x and y position. Be careful that control points x position is an absolute position in the segment. If you specify a control point with x = 0.5, then the control point will stand in the middle of the segment. +Some curve_base algorithms need control points to process their interpolation, such as splines and bezier curves. +A control point is a simple point in 2D space with x and y positions. Note that the x position is an absolute position within the segment. If you specify a control point with x = 0.5, the control point will stand in the middle of the segment. -C++ : +### C++: ```c++ - hypercurve::control_point(0.5, 0.8); // Alias hypercurve::point(0.5, 0.8); // Can also be passed with {} hypercurve::quadratic_bezier_curve({0.5, 0.8}); - ``` -Lua : - -```Lua +### Lua: +```lua hc.control_point(0.5, 0.8) -- Alias hc.point(0.5, 0.8) - ``` -Csound : - -```Csound +### Csound: +```csound hc_control_point(0.5, 0.8) // Alias hc_point(0.5, 0.8) - ``` -Faust : -``` +### Faust: + +```faust hc.control_point(0.5, 0.7); hc.point(0.3, 0.8); ``` - - -C++ : - -```c++ - -hypercurve::share( ) - -``` - -Lua : - -```Lua - -hc. - -``` - -Csound : - -```Csound - -hc_ - -``` - -Faust : -``` -hc. -``` - ## Curve Base - +In Hypercurve, a curve base represents the algorithm of a specific curve. Some of them take one or several constant parameters. +You should remember that algorithms implementations are often approximations of the curve equations. +Indeed, many curve equations are not easy to scale and normalize, as their behavior tends to infinity. +So in many cases (e.g., Hamming, Gaussian, etc.), I had to find a logical rule to force the curves to respect Hypercurve composition rules (normalizable, scalable). -In Hypercurve, a Curve base represents the algorithm of a specific curve. Some of them take one or several constant parameters. -You should remember algorithms implementations are most of the time approximations of the curve equations. -Indeed, many curve equations are not easy to scale and normalize, since their behavior tends to infinity. -So in many cases (e.g. hamming, gaussian...) I had to find a logical rule to force the curves to respect Hypercurve composition rules (normalizable, scalable). +### Diocles Cissoid Curve +![Diocles Cissoid](png/diocles.png) +Diocles curve takes one argument `a` which must be in the range `0.5 < a < inf`. The more `a` increases, the more linear the curve becomes. Otherwise, the Diocles curve is a concave curve. -#### Diocles cissoid curve - -![Diocles cissoid](png/diocles.png) - -Diocles curve takes 1 argument `a` which must be in range `0.5 < a < inf`. The more a increases, the more linear the curve becomes. Otherwise, diocles curve is a concave curve. - -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::diocles_curve(double a) ); - // Alias - hypercurve::share( hypercurve::cissoid_curve(double a) ); - ``` -Lua : - -```Lua - -hc.diocles_curve(number a) +#### Lua: +```lua +hc.diocles_curve(number a) -- Alias - hc.cissoid_curve(a) - ``` -Csound : - -```Csound +#### Csound: +```csound hc_diocles(float iarg_a) - // Alias - hc_cissoid(float iarg_a) - ``` -Faust : -``` -hc.diocles_curve(float a); +#### Faust: +```faust +hc.diocles_curve(a); // Alias - -hc.cissoid(float a); - +hc.cissoid(a); ``` - -#### Cubic curve +### Cubic Curve - -![Cubic curve](png/cubic.png) +![Cubic Curve](png/cubic.png) -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::cubic_curve() ); - ``` -Lua : - -```Lua +#### Lua: +```lua hc.cubic_curve() - ``` -Csound : - -```Csound +#### Csound: +```csound hc_cubic_curve() - ``` - -Faust : -``` -hc.cubic_curve; +#### Faust: +```faust +hc.cubic_curve; ``` +### Power Curve +![Power Curve](png/power9.png) -#### Power curve - - -![Power curve](png/power9.png) - -The power curve takes one argument, which is the exponent of power operation. The more `power` is important, the more concave the curve is. -A power of 1 will create a linear curve. +The power curve takes one argument, which is the exponent of the power operation. The more `power` is significant, the more concave the curve is. A power of 1 will create a linear curve. -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::power_curve(double power) ); - ``` -Lua : - -```Lua - -hc.power_curve(number power) +#### Lua: +```lua +hc.power_curve(number power) ``` -Csound : - -```Csound +#### Csound: +```csound hc_power_curve(float ipower) - ``` +#### Faust: -Faust : +```faust +hc.power_curve(exponent); ``` -hc.power_curve(float exponent); - -``` - - -#### Hamming Hanning Blackman curves +### Hamming, Hanning, Blackman Curves - * Hanning -![Hanning curve](png/hanning.png) +![Hanning Curve](png/hanning.png) * Hamming -![Hamming curve](png/hamming.png) +![Hamming Curve](png/hamming.png) * Blackman -![Blackman curve](png/blackman.png) +![Blackman Curve](png/blackman.png) -The Hamming implementation is an approximation, since the curve itself starts at y = 0.08 for x = 0. So it had to be stretched up a little bit to allow hypercurve to do its job. +The Hamming implementation is an approximation, as the curve itself starts at y = 0.08 for x = 0. So it had to be stretched up a little bit to allow Hypercurve to do its job. -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::hamming_curve() ); - hypercurve::share( hypercurve::hanning_curve() ); - hypercurve::share( hypercurve::blackman_curve() ); - ``` -Lua : - -```Lua +#### Lua: +```lua hc.hamming_curve() - hc.hanning_curve() - hc.blackman_curve() - ``` -Csound : - -```Csound +#### Csound: +```csound hc_hamming_curve() - hc_hanning_curve() - hc_blackman_curve() - ``` +#### Faust: -Faust : -``` +```faust hc.hamming; hc.hanning; hc.blackman; ``` -#### Gaussian curve - -![Gaussian curve](png/gaussian.png) +### Gaussian Curve -The gaussian curve takes two parameterrs `A` and `c`. The most important parameter is `c`. A lower value will result in a more carved curve. Higher values will look more like a roundish curve. The `A` parameter does not seem really significant in this implementation. Though, changing it does not return strictly the same results. `c` argument is usually in range `0 < c < inf` +![Gaussian Curve](png/gaussian.png) -C++ : +The Gaussian curve takes two parameters `A` and `c`. The most important parameter is `c`. Lower values result in a more carved curve. Higher values look more like a roundish curve. The `A` parameter is not very significant in this implementation, though changing it does not return strictly the same results. The `c` argument is usually in the range `0 < c < inf`. -```c++ +#### C++: +```c++ hypercurve::share( hypercurve::gaussian_curve(double A, double c) ); - // Alias - hypercurve::share( hypercurve::gauss_curve(double A, double c) ); - - - ``` -Lua : - -```Lua - -hc.gaussian_curve(number A, number c) +#### Lua: +```lua +hc.gaussian_curve(number A, number c) -- Alias - -hc.gauss_curve(number A, number c) - +hc.gauss_curve(number A, number c) ``` -Csound : - -```Csound +#### Csound: +```csound hc_gaussian_curve(float iA, float ic) - // Alias - hc_gauss_curve(float iA, float ic) - ``` -Faust : -``` -hc.gaussian_curve(float A, float c); +#### Faust: +```faust +hc.gaussian_curve(A, c); // Alias - -hc.gauss_curve(float A, float c); - +hc.gauss_curve(A, c); ``` -#### Toxoid curve +### Toxoid Curve -![Toxoid curve](png/toxoid.png) +![Toxoid Curve](png/toxoid.png) -The parameter `a` is usually in range `0 < a < inf`. Low values for `a` will return more concave results, while higher values will return more convex curves. +The parameter `a` is usually in the range `0 < a < inf`. Low values for `a` return more concave results, while higher values return more convex curves. -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::toxoid_curve(double a) ); - // Alias - hypercurve::share( hypercurve::duplicatrix_cubic_curve(double a) ); - ``` -Lua : - -```Lua - -hc.toxoid_curve(number a) +#### Lua: +```lua +hc.toxoid_curve(number a) -- Alias - -hc.duplicatrix_cubic_curve(number a) - +hc.duplicatrix_cubic_curve(number a) ``` -Csound : - -```Csound +#### Csound: +```csound hc_toxoid_curve(float ia) - // Alias - hc_duplicatrix_cubic_curve(float ia) - ``` -Faust : -``` -hc.toxoid_curve(float a); +#### Faust: +```faust +hc.toxoid_curve(a); // Alias - -hc.duplicatrix_cubic_curve(float a); - +hc.duplicatrix_cubic_curve(a); ``` - -#### Catenary curve +### Catenary Curve -![Catenary curve](png/catenary.png) +![Catenary Curve](png/catenary.png) -Relevant values for `a` argument are in range `0 < a < 2`. The more `a` tends to 0, the more it is concave. +Relevant values for the `a` argument are in the range `0 < a < 2`. The more `a` tends to 0, the more concave it becomes. -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::catenary_curve(double a) ); - // Alias - hypercurve::share( hypercurve::funicular_curve(double a) ); - ``` -Lua : - -```Lua - -hc.catenary_curve(number a) +#### Lua: +```lua +hc.catenary_curve(number a) -- Alias - -hc.funicular_curve(number a) - +hc.funicular_curve(number a) ``` -Csound : - -```Csound +#### Csound: +```csound hc_catenary_curve(float ia) - // Alias - hc_funicular_curve(float ia) - ``` -Faust : -``` -hc.catenary_curve(float a); -hc.funicular_curve(float a); -``` - - - +#### Faust: -#### Tightrope Walker curve +```faust +hc.catenary_curve(a); +hc.funicular_curve(a); +``` - -![Tightrope Walker curve](png/tightrope.png) +### Tightrope Walker Curve -In this particular case, `a` must be superior to `abs(b)` and `a` must be superior to `0` (quite logical here). -Here, it is the distance between `a` and `abs(b)` that will is interesting. A big distance (e.g. a = 1.0, b = 0.1) will create a hardcore concave curve (useful for quick attack envelopes). But a smaller distance (a = 1.01, b = 1) will create a big bump before the attack segment. +![Tightrope Walker Curve](png/tightrope.png) +In this particular case, `a` must be greater than `abs(b)` and `a` must be greater than `0` (quite logical here). The distance between `a` and `abs(b)` is the interesting part. A large distance (e.g., a = 1.0, b = 0.1) creates a highly concave curve (useful for quick attack envelopes). But a smaller distance (e.g., a = 1.01, b = 1) creates a big bump before the attack segment. -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::tightrope_walker_curve(double a, double b) ); - ``` -Lua : - -```Lua - -hc.tightrope_walker_curve(number a, number b) +#### Lua: +```lua +hc.tightrope_walker_curve(number a, number b) ``` -Csound : - -```Csound +#### Csound: +```csound hc_tightrope_walker_curve(float ia, float ib) - ``` - - - -#### Quadratic Bezier curve +### Quadratic Bezier Curve -![Quadratic Bezier curve](png/quadratic_bezier.png) +![Quadratic Bezier Curve](png/quadratic_bezier.png) -Quadratic bezier curve must be passed a control point. This point will shape the curve. Notice that the x position of the point must be defined in absolute coordinates of the segment. So for example the point : `point{0.5, 0.2}` will be located in the middle of the segment. +The quadratic bezier curve must be passed a control point. This point will shape the curve. Note that the x position of the point must be defined in absolute coordinates within the segment. So, for example, the point `point{0.5, 0.2}` will be located in the middle of the segment. -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::quadratic_bezier_curve( hypercurve::control_point cp ) ); - ``` -Lua : - -```Lua - -hc.quadratic_bezier_curve( hc.control_point cp ) +#### Lua: +```lua +hc.quadratic_bezier_curve( hc.control_point cp ) ``` -Csound : - -```Csound +#### Csound: +```csound hc_quadratic_bezier_curve( hc_control_point cp ) - ``` -Faust : -``` -hc.quadratic_bezier_curve(hc.control_point cp); +#### Faust: +```faust +hc.quadratic_bezier_curve(cp); ``` - -#### Cubic Bezier curve -![Cubic bezier curve](png/cubic_bezier.png) +### Cubic Bezier Curve -Same as for quadratic bezier curve, except that you need to specify two control points here. Make sure that the second point is located after the first one, else your curve might be coming back in the x axis, wich as an audio envelope might mean return back in the past (not so good). +![Cubic Bezier Curve](png/cubic_bezier.png) -C++ : +Same as for the quadratic bezier curve, except that you need to specify two control points here. Make sure that the second point is located after the first one, else your curve might be coming back in the x axis, which as an audio envelope might mean returning back in the past (not so good). -```c++ +#### C++: +```c++ hypercurve::share( hypercurve::cubic_bezier_curve( hypercurve::control_point cp1, hypercurve::control_point cp2) ); - ``` -Lua : - -```Lua - -hc.cubic_bezier_curve(hc.control_point cp1, hc.control_point cp2) +#### Lua: +```lua +hc.cubic_bezier_curve(hc.control_point cp1, hc.control_point cp2) ``` -Csound : - -```Csound +#### Csound: +```csound hc_cubic_bezier_curve(hc_control_point cp1, hc_control_point cp2) - ``` - -Faust : -``` -hc.cubic_bezier_curve(hc.control_point cp1, hc.control_point cp2); +#### Faust: +```faust +hc.cubic_bezier_curve(hc.control_point cp1, hc.control_point cp2); ``` - -#### Cubic spline curve +### Cubic Spline Curve -![Cubic Spline curve](png/cubic_spline.png) +![Cubic Spline Curve](png/cubic_spline.png) -Cubic spline curve is similar to Csound's [GEN08](http://www.csounds.com/manual/html/GEN08.html). You pass it a list of any number of control points. The difference with Bezier curves is that your segment will actually pass through all of these control points. This curve may sometime need to be rescaled, since the deviation of the curve can go across the limits of your y origin and destination. X coordinates of control points must be absolute coordinates (inside the segment, so between 0 and 1). +Cubic spline curve is similar to Csound's [GEN08](http://www.csounds.com/manual/html/GEN08.html). You pass it a list of any number of control points. The difference with Bezier curves is that your segment will actually pass through all of these control points. This curve may sometimes need to be rescaled, since the deviation of the curve can go beyond the limits of your y origin and destination. X coordinates of control points must be absolute coordinates (inside the segment, so between 0 and 1). -C++ : +#### C++: ```c++ - hypercurve::share(hypercurve::cubic_spline_curve(std::vector cp_list) ); - ``` -Lua : - -```Lua +#### Lua: +```lua hc.cubic_spline_curve(table {hc.control_point}) - ``` -Csound : - -```Csound +#### Csound: +```csound hc_cubic_spline_curve(hc_control_point p1, [hc_control_point p2, ...]) - ``` - -Faust : -``` -hc.cubic_spline_curve( (hc.control_point point_list) ); +#### Faust: +```faust +hc.cubic_spline_curve( (hc.control_point point_list) ); ``` - -#### Catmull Rom spline curve +### Catmull-Rom Spline Curve -![Catmull Rom Spline curve](png/catmul_rom.png) - -Another spline curve. Like cubic bezier it receives 2 control points. BUT the catmull rom control points X coordinates must be outside the segment. So cp1.x must be < 0 and cp2.x must be > 1. +![Catmull-Rom Spline Curve](png/catmul_rom.png) -C++ : +Another spline curve. Like cubic bezier, it receives two control points. However, the Catmull-Rom control points' x coordinates must be outside the segment. So `cp1.x` must be < 0 and `cp2.x` must be > 1. -```c++ +#### C++: +```c++ hypercurve::share( hypercurve::catmull_rom_spline_curve( hypercurve::control_point cp1, hypercurve::control_point cp2) ); - ``` -Lua : - -```Lua - -hc.catmull_rom_spline_curve(hc.control_point cp1, hc.control_point cp2) +#### Lua: +```lua +hc.catmull_rom_spline_curve(hc.control_point cp1, hc.control_point cp2) ``` -Csound : - -```Csound +#### Csound: +```csound hc_catmull_rom_spline_curve(hc_control_point cp1, hc_control_point cp2) - ``` -Faust : -``` -hc.catmull_rom_spline_curve(hc.control_point cp1, hc.control_point cp2); +#### Faust: +```faust +hc.catmull_rom_spline_curve(hc.control_point cp1, hc.control_point cp2); ``` +### Polynomial Curve -#### Polynomial curve - -The polynomial curve accepts an infinite number of arguments (up to 64 for Csound) and will evaluate curve with a polynomial expression : +The polynomial curve accepts an infinite number of arguments (up to 64 for Csound) and will evaluate the curve with a polynomial expression: `(arg1*x)^3 + (arg2*x)^2 + (arg1*x)^1` -In audio context, it is safer to scale the hypercurve in which you use a polynomial, as its y scale may be uncertain. Use the `normalize` or `scale` method on your hypercurve to do so. +In an audio context, it is safer to scale the hypercurve in which you use a polynomial, as its y scale may be uncertain. Use the `normalize` or `scale` method on your hypercurve to do so. -![Polynomial curve](png/polynomial.png) - +![Polynomial Curve](png/polynomial.png) -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::polynomial_curve( {1.34, -1, -0.5, 0.1} ) ); - ``` -Lua : +#### Lua: -```Lua +```lua hc.polynomial_curve(1.34, -1, -0.5, 0.1) ``` -Csound : +#### Csound: -```Csound +```csound hc_polynomial_curve(1.34, -1, -0.5, 0.1) - ``` +#### Faust: -Faust : -``` +```faust hc.polynomial_curve( (float arguments_list) ); - ``` -#### User defined curve +### User Defined Curve +User-defined curve allows you to pass your own function that will return `y` for each `x` between 0 and 1. -User defined curve allows you to pass your own function that will return `y` for each `x` between 0 and 1. - -![User defined curve](png/cubic.png) - +![User Defined Curve](png/cubic.png) -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::user_defined_curve( [](double x){ return x * x * x; } )); - ``` -Lua : +#### Lua: -```Lua +```lua hc.user_defined(function(x) return x * x * x end ) -- Alternatively, you can pass it a named function function my_own_cubic(x) @@ -969,288 +721,257 @@ end hc.user_defined_curve(my_own_cubic) ``` -Csound : - -```Csound -;Not implemented +#### Csound: +```csound +; Not implemented ``` -Faust : -``` -// Not implemented +#### Faust: +```faust +// Not implemented ``` -#### Typed Curve +### Typed Curve +Typed curve allows you to define a curve factor between -10 and 10 (concave or convex). It is based on Csound [GEN16 formula](http://www.csounds.com/manual/html/GEN16.html). Because of Hypercurve architecture, an increasing segment of typed curve will be inverted (concave instead of convex and convex instead of concave) in comparison to Csound GEN16. So type > 0 means convex, type < 0 means concave. -Typed curve allows you to define a curve factor between -10 and 10 (concave or convex). It is based on Csound [GEN16 formula](http://www.csounds.com/manual/html/GEN16.html). Because of Hypercurve architecture, a increasing segment of typed curve will be inverted (concave instead of convex and convex instead of concave) in comparison to csound GEN16. So type > 0 means convex, type < 0 means concave - -![Typed curve](png/typed.png) - +![Typed Curve](png/typed.png) -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::typed_curve(-5)); - ``` -Lua : +#### Lua: -```Lua +```lua hc.typed_curve(-5) ``` -Csound : +#### Csound: -```Csound +```csound hc_typed_curve(-5) - ``` -Faust : -``` -hc.typed_curve(9.5); +#### Faust: +```faust +hc.typed_curve(9.5); ``` - -#### Mouse Curve - +### Mouse Curve -![Mouth curve](png/mouth.png) - +![Mouse Curve](png/mouth.png) -C++ : +#### C++: ```c++ - -hypercurve::share( hypercurve::mouth_curve()); +hypercurve::share( hypercurve::mouth_curve() ); // Alias -hypercurve::share( hypercurve::kiss_curve()); - +hypercurve::share( hypercurve::kiss_curve() ); ``` -Lua : +#### Lua: -```Lua +```lua hc.mouth_curve() -- Alias hc.kiss_curve() ``` -Csound : +#### Csound: -```Csound +```csound hc_mouth_curve() // Alias hc_kiss_curve() - ``` -Faust : -``` +#### Faust: + +```faust hc.mouth_curve(); // Alias hc.kiss_curve(); - ``` -#### Bicorn Curve +### Bicorn Curve +![Bicorn Curve](png/bicorn.png) -![Bicorn curve](png/bicorn.png) - - -C++ : +#### C++: ```c++ - -hypercurve::share( hypercurve::bicorn_curve(bool )); +hypercurve::share( hypercurve::bicorn_curve(bool ) ); // Alias -hypercurve::share( hypercurve::cocked_hat_curve(bool)); - +hypercurve::share( hypercurve::cocked_hat_curve(bool) ); ``` -Lua : +#### Lua: -```Lua +```lua hc.bicorn_curve(bool 0 or 1) -- Alias hc.cocked_hat_curve(bool 0 or 1) ``` -Csound : +#### Csound: -```Csound +```csound hc_bicorn_curve(bool 0 or 1) // Alias hc_cocked_hat_curve(bool 0 or 1) - ``` -Faust : -``` +#### Faust: + +```faust hc.bicorn_curve(bool 0 or 1); // Alias hc.cocked_hat_curve(bool 0 or 1); - ``` +### Lagrange Polynomial Curve +![Lagrange Polynomial Curve](png/lagrange.png) -#### Lagrange polynomial curve +Like cubic spline, Lagrange interpolation takes a list of control points with 0 < x < 1. - -![Lagrange curve](png/lagrange.png) - -Like cubic spline, lagrange interpolation takes a list of control points with 0 < x < 1. - -C++ : +#### C++: ```c++ - hypercurve::share( hypercurve::lagrange_polynomial_curve( {control_point(0.2, 0.8), control_point(0.4, 0.1)} ) ); - ``` -Lua : +#### Lua: -```Lua +```lua hc.lagrange_polynomial_curve( hc.control_point(0.2, 0.8), hc.control_point(0.4, 0.2) ) ``` -Csound : - -```Csound -hc_lagrange_polynomial_curve( hc_control_point(0.2, 0.8), hc_control_point(0.4, 0.2)) +#### Csound: +```csound +hc_lagrange_polynomial_curve( hc_control_point(0.2, 0.8), hc_control_point(0.4, 0.2) ) ``` -Faust : -``` -hc.lagrange_polynomial_curve( (hc.control_point(0.2, 0.8), hc.control_point(0.4, 0.1)) ); -``` +#### Faust: -#### Logarithmic and exponential Curve +```faust +hc.lagrange_polynomial_curve( (hc.control_point(0.2, 0.8), hc.control_point(0.4, 0.1)) ); +``` +### Logarithmic and Exponential Curve -![Logarithmic curve](png/logarithmic.png) -![Exponential curve](png/exponential.png) - +![Logarithmic Curve](png/logarithmic.png) +![Exponential Curve](png/exponential.png) -C++ : +#### C++: ```c++ - -hypercurve::share( hypercurve::logarithmic_curve()); -hypercurve::share( hypercurve::exponential_curve()); - +hypercurve::share( hypercurve::logarithmic_curve() ); +hypercurve::share( hypercurve::exponential_curve() ); ``` -Lua : +#### Lua: -```Lua +```lua hc.logarithmic_curve() hc.exponential_curve() ``` -Csound : +#### Csound: -```Csound +```csound hc_logarithmic_curve() hc_exponential_curve() - ``` -Faust : -``` +#### Faust: + +```faust hc.logarithmic_curve(); hc.exponential_curve(); ``` -#### Easing curves +### Easing Curves + +Hypercurve contains implementations of [Easings](https://easings.net). Easings take no argument. -Hypercurve contains implementation of [Easings](easings.net). Easings take no argument. +#### Csound Example: -Csound example : -```Csound +```csound hc_ease_in_sine_curve() hc_ease_out_sine_curve() hc_ease_inout_sine_curve() ``` -All easing from [Easings](easings.net) is avaiabe (just replace the "sine" with another type). +All easings from [Easings](https://easings.net) are available (just replace "sine" with another type). -Another one has been added for convenience, and it takes an exponent argument : -```Csound +Another one has been added for convenience, and it takes an exponent argument: + +```csound hc_ease_in_power_curve(int exponent) hc_ease_out_power_curve(int exponent) hc_ease_inout_power_curve(int exponent) ``` +## Manipulation Tools -### Manipulation Tools - -#### Hypercurve Operators - -Hypercurves can be combined with + - * / operators -You are allowed to combine curve and numbers with these operators (for example mycurve * 2). -In Csound and Faust, those are implemented as separate functions. +### Hypercurve Operators +Hypercurves can be combined with `+`, `-`, `*`, and `/` operators. You are allowed to combine curves and numbers with these operators (e.g., `mycurve * 2`). +In Csound and Faust, these are implemented as separate functions. - -C++ : +#### C++: ```c++ +hypercurve::curve c1(2048, 0, {hypercurve::segment(1, 1, hypercurve::share(hypercurve::cubic_curve()))}); +hypercurve::curve c2(2048, 0, {hypercurve::segment(1, 1, hypercurve::share(hypercurve::diocles_curve(1)))}); +hypercurve::curve sum = c1 + c2; +hypercurve::curve sub = c1 - c2; +hypercurve::curve prod = c1 * c2; +hypercurve::curve div = c1 / c2; +// Or +c1 += c2; +c1 -= c2; +c1 *= c2; +c1 /= c2; - hypercurve::curve c1(2048, 0, {hypercurve::segment(1, 1, hypercurve::share(hypercurve::cubic_curve()))}); - hypercurve::curve c2(2048, 0, {hypercurve::segment(1, 1, hypercurve::share(hypercurve::diocles_curve(1)))}); - hypercurve::curve sum = c1 + c2; - hypercurve::curve sub = c1 - c2; - hypercurve::curve prod = c1 * c2; - hypercurve::curve div = c1 / c2; - // Or - c1 += c2; - c1 -= c2; - c1 *= c2; - c1 /= c2; - - // It works for all mathematic operators +, -, /, * +// It works for all mathematical operators `+`, `-`, `/`, `*` ``` -Lua : - -```Lua +#### Lua: - local c1 = hc.hypercurve(2048, 0, {hc.segment(1, 1, hc.cubic_curve())}) - local c2 = hc.hypercurve(2048, 0, {hc.segment(1, 1, hc.diocles_curve(1))}) - local add = c1 + c2 - local sub = c1 - c2 - local prod = c1 * c2 - local div = c1 / c2 +```lua +local c1 = hc.hypercurve(2048, 0, {hc.segment(1, 1, hc.cubic_curve())}) +local c2 = hc.hypercurve(2048, 0, {hc.segment(1, 1, hc.diocles_curve(1))}) +local add = c1 + c2 +local sub = c1 - c2 +local prod = c1 * c2 +local div = c1 / c2 ``` -Csound : +#### Csound: -```Csound - icrv1 = hc_hypercurve(2048, 0, hc_segment(1, 1, hc_cubic_curve())) - icrv2 = hc_hypercurve(2048, 0, hc_segment(1, 1, hc_diocles_curve(1))) - icrv_sum = hc_add(icrv1, icrv2) - icrv_sub = hc_sub(icrv1, icrv2) - icrv_prod = hc_mult(icrv1, icrv2) - icrv_div = hc_div(icrv1, icrv2) +```csound +icrv1 = hc_hypercurve(2048, 0, hc_segment(1, 1, hc_cubic_curve())) +icrv2 = hc_hypercurve(2048, 0, hc_segment(1, 1, hc_diocles_curve(1))) +icrv_sum = hc_add(icrv1, icrv2) +icrv_sub = hc_sub(icrv1, icrv2) +icrv_prod = hc_mult(icrv1, icrv2) +icrv_div = hc_div(icrv1, icrv2) - icrv_sum = hc_add(icrv1, 2) - // ... +icrv_sum = hc_add(icrv1, 2) ``` +#### Faust: -Faust : -``` +```faust crv1 = hc.hypercurve(2048, 0, (hc.segment(1, 1, hc.cubic_curve))); crv2 = hc.hypercurve(2048, 0, (hc.segment(1, 1, hc.diocles_curve(1)))); @@ -1258,193 +979,159 @@ crv_sum = hc.sum(crv1, crv2); crv_sub = hc.sub(crv1, crv2); crv_mult = hc.mult(crv1, crv2); crv_div = hc.div(crv1, crv2); - ``` +### Invert Curve Base +Vertical symmetry of the curve base. -#### Invert curve base - -Vertical symetry of the curve base. - - -C++ : +#### C++: ```c++ - hypercurve::invert(hypercurve::share( hypercurve::cubic_curve() )); - ``` -Lua : - -```Lua +#### Lua: +```lua hc.invert(hc.cubic_curve()) - ``` -Csound : - -```Csound +#### Csound: +```csound hc_invert(hc_cubic_curve()) - ``` -Faust : -``` +#### Faust: + +```faust hc.invert(hc.cubic_curve()); ``` +### Mirror Curve Base +This function will create a symmetry of the curve on an `x_start/y_start - x_destination/y_destination` axis. -#### Mirror curve base - -This function will make a symetry of the curve on a x_start/y_start - x_destination/y_destination axis - -C++ : +#### C++: ```c++ - hypercurve::mirror(hypercurve::share( hypercurve::cubic_curve() )); - ``` -Lua : - -```Lua +#### Lua: +```lua hc.mirror(hc.cubic_curve()) - ``` -Csound : - -```Csound +#### Csound: +```csound hc_mirror(hc_cubic_curve()) - ``` -Faust : -``` +#### Faust: + +```faust hc.mirror(hc.cubic_curve()); ``` +### Scale Hypercurve +These functions allow you to scale or normalize a hypercurve between min and max y values. +The `scale` function allows you to rescale an entire hypercurve, while `normalize` or `norm` will scale between 0 and 1. - -#### Scale hypercurve - -This functions will allow you to scale or normalize an hypercurve between min and max y values -The scale function allows you to rescale an entire HYPERCURVE, while normalize or norm will scale between 0 and 1. - -C++ : +#### C++: ```c++ - hypercurve::curve c(4096, 0, {hypercurve::segment(1, 1, hypercurve::cubic_curve())}); - c.scale(-1, 1); - // normalize scales between 0 and 1 - c.normalize(); - c.norm(); - // Now "c" curve y start is -1 and its destination is 1 - +hypercurve::curve c(4096, 0, {hypercurve::segment(1, 1, hypercurve::cubic_curve())}); +c.scale(-1, 1); +// normalize scales between 0 and 1 +c.normalize(); +c.norm(); +// Now "c" curve y start is -1 and its destination is 1 ``` -Lua : +#### Lua: -```Lua - local crv = hc.hypercurve(4096, 0, {hc.segment(1, 1, hc.cubic_curve())}) - crv:scale(-1, 1) - crv:normalize() - crv:norm() +```lua +local crv = hc.hypercurve(4096, 0, {hc.segment(1, 1, hc.cubic_curve())}) +crv:scale(-1, 1) +crv:normalize() +crv:norm() ``` -Csound : +#### Csound: -```Csound - - icrv = hc_hypercurve(4096, 0, hc_segment(1, 1, hc_cubic_curve())) - // This function won't make a copy, it will only scale the corresponding curve - hc_scale(icrv, -1, 1) - hc_normalize(icrv) - hc_norm(icrv) +```csound +icrv = hc_hypercurve(4096, 0, hc_segment(1, 1, hc_cubic_curve())) +// This function won't make a copy, it will only scale the corresponding curve +hc_scale(icrv, -1, 1) +hc_normalize(icrv) +hc_norm(icrv) ``` +#### Faust: -Faust : -``` +```faust crv = hc.hypercurve(2048, 0, (hc.segment(1, 1, hc.cubic_curve()))) hc.scale(crv, -1, 1); hc.normalize(crv); hc.norm(crv); ``` +## Concatenate Hypercurves -### Concatenate hypercurves +This function allows you to concatenate two or more curves. -This function allows to contacenate two or more curves - -C++ : +#### C++: ```c++ - curve concatenated = hypercurve::concatenate(size_t new_size, {hypercurve::curve &crv1, hypercurve::curve &crv2, [...] } ) -// concat is an alias (also, the same function exist as a hypercurve::curve constructor) +// concat is an alias (also, the same function exists as a hypercurve::curve constructor) ``` -Lua : - -```Lua +#### Lua: +```lua local new_crv = hc.concatenate(new_size, {curve_list}) -- hc.concat is an alias - ``` -Csound : - -```Csound +#### Csound: +```csound iconcatenated = hc_concatenate(inew_ftable_number, inew_size, icrv1, [icrv2, ...] ) ; hc_concat is an alias - ``` -Faust : -``` +#### Faust: + +```faust // Not implemented yet ``` +## Utilities - -### Utilities - - -#### Export as PNG +#### Export as PNG -C++ : +#### C++: ```c++ - -write_as_png( +write_as_png(...) ``` -Lua : +#### Lua: ```Lua - - +// Not implemented yet ``` -Csound : +#### Csound: ```Csound - -iconcatenated = hc_concatenate(inew_ftable_number, inew_size, icrv1, [icrv2, ...] ) -; hc_concat is an alias - +// Not implemented yet ``` Faust : @@ -1452,5 +1139,3 @@ Faust : // Not implemented yet ``` - - diff --git a/faust_lib/README.md b/faust_lib/README.md index 4f24b3c..63912db 100644 --- a/faust_lib/README.md +++ b/faust_lib/README.md @@ -1,4 +1,4 @@ -# Hypercurve for Faust +# Hypercurve for Faust The CMakeLists.txt file will generate a header only file that will later be included in the faustlibrary. In order to do that, you need to have [Quom](https://github.com/Viatorus/quom) installed.