Konstantinos Gavalas

typingvid - Creating beautiful typing animations from the command line

2022-09-25T00:00:00+00:00

Typingvid is a command line utility that allows users to quickly generate typing animation videos using different keyboard layouts and themes. This page documents everything that one needs to know to create their own animations, extend the tool by adding new layouts, or contribute to the further development of the project.

For a quick tour of the tool’s capabilities, jump to the Examples section.

Typingvid is open-source and licensed under the MIT license. You can browse the tool’s source code on Github.

Installation

Using a package installer

The latest stable version of the script is available on the Python Package Index (PyPI) and can easily be installed using your favorite Python package installer (e.g. pip):

pip install typingvid

or:

python3 -m pip install typingvid

To check If everything went smoothly, you can try running:

typingvid --help

From source

Another option is to clone the entire GitHub repository of the project as follows:

git clone https://github.com/GavalasDev/typingvid
cd typingvid
chmod +x typingvid.py
./typingvid.py --help

Usage

The standard format of a typingvid command is the following:

typingvid -t TEXT [-l LAYOUT] [-o OUTPUT] [OPTIONS]

To see all available options, use:

typingvid --help

For example:

typingvid -t "hello world"

will generate an animation video using the default layout (en) and store it at the default output location (output.mp4).

The extension of the OUTPUT variable (option -o) defines the type of the output file. For example, to generate a simple GIF:

typingvid -t "lorem ipsum" -o "/path/to/file.gif"

For more examples, see the Examples section.

Understanding layouts

Typingvid was designed for multiple layout support since the very beginning. Each layout consists of two core files, a YAML file describing the properties of the layout (stored under directory layouts/) and an SVG file describing the looks of the layout (stored under directory assets/).

Single language layouts

The simplest (and most commonly needed) case is single language layouts. As an example, we’ll look into the inner workings of the en layout, describing the most common English keyboard layout (QWERTY):

YAML

# contents of file layouts/en.yml
file: keyboard-en.svg

fonts:
  - Noto-Sans-Mono

The YAML file describing a single language layout should include two fields:

file: name of the SVG file to be used with this layout (relative to assets/)
fonts: a list containing a single font name available on the user’s device (NOTE: including more than one font converts the layout into a multi-language layout)

SVG

The SVG file ultimately defines how the keyboard will look in the final video. Extra attention should be paid to two important details:

The dimensions of the file should closely match those of the provided .svg files (1943 x 685)
The ID of each object representing a key of the keyboard (usually a rectangle) should match the character on it (e.g. see properties of the rectangle around character K in the following image)

A key press is simulated by direct modification of the properties of different objects in the SVG file. As an example, if the input text is “HELLO”:

The appropriate SVG file is loaded (as determined by the selected layout)
Object with ID “H” is located and darkened
Frame 1 is rendered
Object with ID “H” is located and reset
Frame 2 is rendered
Steps 2-5 are repeated for characters “E”, “L”, …

Because special characters are not valid SVG IDs (e.g. spaces, new lines, etc.) more expressive IDs are used to represent them (e.g. “space”, “enter”, etc.). For all available special characters, check the provided SVG files.

Inkscape don’t allow IDs from different languages (e.g. “か” or “Ω”) thus forcing us to manually edit the resulting .svg files in order to change the IDs.

Multi-language layouts

YAML

An interesting application of the tool (and the reason I developed it in the first place) is support for multi-language layouts. An example GIF (using the enjp layout) can be seen below:

The main difference with single language layouts is in the YAML files defining them. For example, the enjp layout looks like this:

# contents of file layouts/enjp.yml
file: keyboard-enjp.svg

fonts:
  - Noto-Sans-Mono
  - Noto-Sans-Mono-CJK-JP

mapping:
  'backtick':  ろ
  'minus':  ほ
  'equals':  へ
  'backslash':  む
  'comma':  ね
  'period':  る
  'forwardslash': め
  '1':  ぬ
  '2':  ふ
  '3':  あ
  '4':  う
  '5':  え
  '6':  お
  '7':  や
  '8':  ゆ
  '9':  よ
  '0':  わ
  'Q':  た
  'W':  て
  'E':  い
  [...]

The most obvious difference is the addition of the mappings collection, which clearly defines the mapping between the two layouts (languages). Another less obvious difference is the addition of an extra member to the fonts list. Even if the font to be used for both languages is the same, it should be explicitly stated (otherwise the layout is interpreted as single language).

Multi-language layouts can also be used for mappings between different layouts of the same language, like QWERTY and AZERTY (see layout qwerty_azerty).

SVG

SVGs files describing multi-language layouts look exactly the same as the ones describing single language layouts, with IDs inherited only from the first language (e.g. from English in the enjp layout).

Creating your own layouts

To create a new layout, either for a new language or a new keyboard look, all you need to do is create a new YAML file describing the layout (or copy one of the existing ones) within layouts/ and an appropriate SVG file within assets/ as described above.

The name of the layout is inherited from the name of the YAML file, thus if the file you created is layouts/entest.yml you can select the corresponding layout using:

typingvid -l entest -t "lorem ipsum"

New layouts (especially for other languages) are also greatly appreciated as pull requests on GitHub.

Examples

The simplest command format is the following:

typingvid -t 'www.gavalas.dev' -o "out.gif"

The display defaults to uppercase lettering. If lowercase lettering is preferred, the --force-lowercase option can be used:

typingvid.py -t 'www.gavalas.dev' --force-lowercase -o "out.gif"

The speed of the output video/gif can be controlled by the -s option:

typingvid.py -t 'www.gavalas.dev' --force-lowercase -s 10 -o "out.gif"

If the completed text is hard to read, the --hold-last-frame option allows us to specify a set time (in seconds) for the final frame to be held on screen:

typingvid -t 'www.gavalas.dev' --force-lowercase -s 10 --hold-last-frame 2 -o "out.gif"

Finally, the --invert-colors option can be utilized (at least with the default layouts) for the creation of dark themed videos:

typingvid -t 'www.gavalas.dev' --force-lowercase -s 10 --hold-last-frame 2 --invert-colors -o "out.gif"

Layouts

Typingvid comes with support for multiple layouts/languages. To specify the desired layout use the -l option:

typingvid -l gr -t "ΟΠΕΡ ΕΔΕΙ ΔΕΙΞΑΙ" --hold-last-frame 2 -o "out.gif"

To see all available layouts use:

typingvid --all-layouts

Dual-language layouts are also available, for example:

typingvid -l enjp -t "byte" -o out.gif

Layouts can also be customized, for more information check the Understanding Layouts section.

License

The tool is licensed under the MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT).

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions.

Spigot algorithms for the digits of pi in Python

2021-05-09T00:00:00+00:00

Introduction

If you ever had to work on a Python project that required the computation of a large number of π’s digits and wanted to generate them on the spot instead of downloading them from the web, you might have stumbled upon a series of innocent looking functions based on so-called Spigot Algorithms. A Spigot Algorithm is an algorithm meant to produce digits of a transcendental number sequentially from left to right while maintaining a low profile in terms of memory usage, something very important for older computing devices.

The Rabinowitz-Wagon algorithm

One of the first known algorithms of this type comes from A. Sale who, in 1968, devised a method to evaluate the digits of e[1]. Twenty years later, D. Saada proposed the use of a similar algorithm for the computation of π and in 1991 so did math hacker Stanley Rabinowitz.

The latter further explored the concept in 1995 with his colleague Stan Wagon in an article in The American Mathematical Monthly[2]. In 2004 Jeremy Gibbons addressed one of the biggest weaknesses of the Rabinowitz-Wagon algorithm—the fact that the computation is bounded by design (meaning that one has to commit in advance to compute a certain number of digits)—in a separate American Mathematical Monthly article[3]. His proposed solution took advantage of the concept of streaming algorithms, something that allowed the calculation to run indefinitely.

Rabinowitz and Wagon’s algorithm was based on the following expression derived from the Leibniz formula for π:

$$\pi = 2 + {1 \over 3} \left(2 + {2 \over 5} \left(2 + {3 \over 7} \left(\cdots\left(2 + {i \over 2i + 1}\bigg(\cdots\bigg)\right)\right)\right)\right) \tag1$$

One implementation of such an algorithm comes from Dik T. Winter, Achim Flammenkamp and others[4] in the form of the following tiny ANSI C program which calculates 15000 decimal places of π:

a[52514],b,c=52514,d,e,f=1e4,g,h;main(){for(;b=c-=14;h=printf("%04d",e+d/f))for(e=d%=f;g=--b*2;d/=g)d=d*b+f*(h?a[b]:f/5),a[b]=d%--g;}

Gibbons later used the same expression to create his first streaming algorithm for the digits of π. A slightly altered version of his Haskell implementation is showcased below.

import Data.Ratio

type LFT = (Integer, Integer, Integer, Integer)

extr :: LFT -> Integer -> Rational
extr (q,r,s,t) x = (q * x + r)%(s * x + t)

-- apply stream to create an infinite list of output terms, each of type c.
stream :: (b->c) -> (b->c->Bool) -> (b->c->b) -> (b->a->b) -> b -> [a] -> [c]
stream next safe prod cons z (x:xs)
  = if    safe z y
    then y : stream next safe prod cons (prod z y) (x:xs)
    else stream next safe prod cons (cons z x) xs
      where y = next z

-- when a transformation is represented by its four coefficients q,r,s and t 
-- arranged as a matrix, function composition corresponds to matrix multiplication.
comp :: LFT -> LFT -> LFT
comp (q,r,s,t) (u,v,w,x) = (q*u+r*w,q*v+r*x,s*u+t*w,s*v+t*x)

-- generate pi based on the Leibniz series for pi
leibniz_pi = stream next safe prod cons init lfts where
    init      = (1,0,0,1)
    lfts      = [(k, 4*k+2, 0, 2*k+1) | k<-[1..]]
    next z    = floor (extr z 3)
    safe z n  = (n == floor (extr z 4))
    prod z n  = comp (10, -10*n, 0, 1) z
    cons z z' = comp z z'

main = print (take 10 leibniz_pi)

$ ./main
[3,1,4,1,5,9,2,6,5,3]

If you’d like to tinker around with the code, I’ve uploaded it to Replit where you can also test it out for a larger number of digits.

Through various optimizations he then condensed the code into the following much smaller, but rather obscure, Haskell program.

leibniz_pi = g(1,0,1,1,3,3) where
   g(q,r,t,k,n,l) = if 4*q+r-t<n*t
     then n : g(10*q,10*(r-n*t),t,k,div(10*(3*q+r))t-10*n,l)
     else g(q*k,(2*q+r)*l,t*l,k+1,div(q*(7*k+2)+r*l)(t*l),l+2)
main = print (take 10 leibniz_pi)

By translating this code, we get one of the most common Python functions for the generation of π found across the web:

# From https://mail.python.org/pipermail/edu-sig/2006-July/006810.html
# John Zelle 4-5-06
# (edited for Python 3)
def leibniz_pi():
    """generator for digits of pi"""
    q,r,t,k,n,l = 1,0,1,1,3,3
    while True:
        if 4*q+r-t < n*t:
            yield n
            q,r,t,k,n,l = (10*q,10*(r-n*t),t,k,(10*(3*q+r))//t-10*n,l)
        else:
            q,r,t,k,n,l = (q*k,(2*q+r)*l,t*l,k+1,(q*(7*k+2)+r*l)//(t*l),l+2)

pi = leibniz_pi()
print([next(pi) for _ in range(10)])

$ python3 digits.py
[3, 1, 4, 1, 5, 9, 2, 6, 5, 3]

Notice the use of the yield keyword which makes the function behave like an iterator. This generator function pattern is what allows us to iterate through as many digits as we might need without having to keep them all in memory or calculate them beforehand.

If you’d like to learn more about how Gibbons’ spigot algorithm uses expression (1) and the concept of streaming algorithms to produce the digits of π, the original paper does a great job at explaining the entire process while also going through some of the basics of lazy functional programming in Haskell.

Using Lambert’s expression

In the final pages of his 2004 paper, Gibbons presents two more spigot algorithms for the digits of π based on different expressions that are more efficient than the one originally used by Rabinowitz and Wagon. The first one is known as Lambert’s expression:

$$\pi = {4 \over 1 + {1^2 \over 3 + {2^2 \over 5 + {3^2 \over 7 + \cdots}}}} \tag2$$

from which the following Haskell program can be derived:

import Data.Ratio

type LFT = (Integer, Integer, Integer, Integer)

-- apply stream to create an infinite list of output terms, each of type c.
stream :: (b->c) -> (b->c->Bool) -> (b->c->b) -> (b->a->b) -> b -> [a] -> [c]
stream next safe prod cons z (x:xs)
  = if    safe z y
    then y : stream next safe prod cons (prod z y) (x:xs)
    else stream next safe prod cons (cons z x) xs
      where y = next z

-- when a transformation is represented by its four coefficients q,r,s and t 
-- arranged as a matrix, function composition corresponds to matrix multiplication.
comp :: LFT -> LFT -> LFT
comp (q,r,s,t) (u,v,w,x) = (q*u+r*w,q*v+r*x,s*u+t*w,s*v+t*x)

-- generate pi based on Lambert's expression 
lamberts_pi = stream next safe prod cons init lfts where
  init                 = ((0,4,1,0), 1)
  lfts                 = [(2*i-1, i*i, 1, 0) | i<-[1..]]
  next ((q,r,s,t),i)   = floor ((q*x+r) % (s*x+t)) where x = 2*i-1
  safe ((q,r,s,t),i) n = (n == floor ((q*x+2*r) % (s*x+2*t)))
        where x=5*i-2
  prod (z,i) n         = (comp (10, -10*n, 0, 1) z, i)
  cons (z,i) z'        = (comp z z', i+1)
  
main = print (take 10 lamberts_pi)

$ ./main
[3,1,4,1,5,9,2,6,5,3]

You can try out this version of the code here.

After condensing the code like before, what I got was the following:
(I’d love to hear about any further optimizations you might come up with.)

lamberts_pi= g(0,4,1,0,4,1) where
   g(q,r,s,t,n,i) = if n == div(q*(5*i-2)+2*r)(s*(5*i-2)+2*t)
     then n : g(10*q-10*n*s, 10*r-10*n*t,s,t,div(10*((q-n*s)*(2*i-1)+r-n*t))(s*(2*i-1) + t), i)
     else g((2*i-1)*q+r, i*i*q, (2*i-1)*s + t, i*i*s, div((5*i*i-1)*q + (2*i+1)*r)((5*i*i-1)*s+(2*i+1)*t),i+1)
main = print (take 10 lamberts_pi)

and by translating to Python:

def gibbons_lamberts_pi():
    q,r,s,t,n,i = 0,4,1,0,4,1
    while True:
        if n == (q*(5*i-2)+2*r)//(s*(5*i-2)+2*t):
	    yield n
	    q,r,s,t,n,i = 10*q-10*n*s,10*r-10*n*t,s,t,(10*((q-n*s)*(2*i-1)+r-n*t))//(s*(2*i-1)+t),i
        else:
	    q,r,s,t,n,i = (2*i-1)*q+r,i*i*q,(2*i-1)*s+t,i*i*s,((5*i*i-1)*q+(2*i+1)*r)//((5*i*i-1)*s+(2*i+1)*t),i+1
pi = gibbons_lamberts_pi()
print([next(pi) for _ in range(10)])

$ python3 lamberts.py
[3, 1, 4, 1, 5, 9, 2, 6, 5, 3]

This program is about five times faster than the one using expression (1) although we can still do better. The following Python function which is also very popular and based on Lambert’s expression, is actually quite faster than the one proposed by Gibbons.

# Found here: https://gist.github.com/deeplook/4947835#file-pi_digits-py
# Modified to become unbounded.
def lamberts_pi():
    k, a, b, a1, b1 = 2, 4, 1, 12, 4
    while True:
        p, q, k = k * k, 2 * k + 1, k + 1
        a, b, a1, b1 = a1, b1, p * a + q * a1, p * b + q * b1
        d, d1 = a / b, a1 / b1
        while d == d1:
            yield int(d)
            a, a1 = 10 * (a % b), 10 * (a1 % b1)
            d, d1 = a / b, a1 / b1
pi = lamberts_pi()
print([next(pi) for _ in range(10)])

$ python3 pi_digits.py
[3, 1, 4, 1, 5, 9, 2, 6, 5, 3]

This algorithm appears as an example for the power of the ABC programming language and its unbounded numbers in a book called The ABC Programmer’s Handbook, originally published in 1990 (see here).

HOW TO PI:
    PUT 2, 4, 1, 12, 4 IN k, a, b, a', b'
    WHILE 1=1:
        NEXT APPROXIMATION
        PRINT COMMON DIGITS
NEXT APPROXIMATION:
    PUT k**2, 2*k+1, k+1 IN p, q, k
    PUT a', b', p*a+q*a', p*b+q*b' IN a, b, a', b'
PRINT COMMON DIGITS:
    PUT floor(a/b), floor(a'/b') IN d, d'
    WHILE d = d':
        WRITE d<<1
        PUT 10*(a mod b), 10*(a' mod b') IN a, a'
        PUT floor(a/b), floor(a'/b') IN d, d'

It also appears as an example within the official Ruby repository since 1998 (see here).

#!/usr/local/bin/ruby

k, a, b, a1, b1 = 2, 4, 1, 12, 4
loop do
  # Next approximation
  p, q, k = k*k, 2*k+1, k+1
  a, b, a1, b1 = a1, b1, p*a+q*a1, p*b+q*b1
  # Print common digits
  d = a / b
  d1 = a1 / b1
  while d == d1
    print d
    $stdout.flush
    a, a1 = 10*(a%b), 10*(a1%b1)
    d, d1 = a/b, a1/b1
  end
end

Obviously the Python implementation shown above is just a direct translation of these programs. A summary of how this algorithm works is provided by the authors of The ABC Programmer’s Handbook:

The program works by repeatedly refining a so-called continued fraction that represents pi. The first approximation is $4 \over 1$, the second is $4 \over {1 + {1 \over 3}}$, which is $12 \over 4$. In the next, the 3 is replaced by $3 + {4 \over 5}$, and in the next after that, the 5 is replaced by $5 + {9 \over 7}$ and so on, so that each part of the fraction is $k^2 \over {2k+1+…}$ for $k = 0, 1, 2, …$

In the program, a/b represents one approximation of the fraction, and a’/b’ the next. If there are any leading digits in common, then these are printed, and the next approximation is calculated.

This is by far the fastest algorithm I’ve found that’s based on Lambert’s expression.

Using Gosper’s series

Gibbons concludes his paper by introducing an algorithm based on an even more efficient expression for π attributed to Bill Gosper:

$$\small{\pi = 3 + {1 \times 1 \over 3 \times 4 \times 5} \times \left( 8 + {2 \times 3 \over 3 \times 7 \times 8} \times \left( \cdots 5i-2 + {i(2i-1) \over 3(3i+1)(3i+2)} \times \cdots \right) \right)\tag3}$$

The complete Haskell program derived from this series is the following:

import Data.Ratio

type LFT = (Integer, Integer, Integer, Integer)

-- apply stream to create an infinite list of output terms, each of type c.
stream :: (b->c) -> (b->c->Bool) -> (b->c->b) -> (b->a->b) -> b -> [a] -> [c]
stream next safe prod cons z (x:xs)
  = if    safe z y
    then y : stream next safe prod cons (prod z y) (x:xs)
    else stream next safe prod cons (cons z x) xs
      where y = next z

-- when a transformation is represented by its four coefficients q,r,s and t arranged as a matrix, function composition corresponds to matrix multiplication.
comp :: LFT -> LFT -> LFT
comp (q,r,s,t) (u,v,w,x) = (q*u+r*w,q*v+r*x,s*u+t*w,s*v+t*x)

-- generate pi based on Gospers's series 
gospers_pi = stream next safe prod cons init lfts where
  init                 = ((1,0,0,1), 1)
  lfts                 = [let j = 3*(3*i+1)*(3*i+2)
                          in (i*(2*i-1),j*(5*i-2),0,j) | i<-[1..]]
  next ((q,r,s,t),i)   = div (q*x+5*r) (s*x+5*t) where x = 27*i-12
  safe ((q,r,s,t),i) n = (n == div (q*x+125*r) (s*x+125*t))
                         where x=675*i-216
  prod (z,i) n         = (comp (10, -10*n, 0, 1) z, i)
  cons (z,i) z'        = (comp z z', i+1)
  
main = print (take 10 gospers_pi)

$ ./main
[3,1,4,1,5,9,2,6,5,3]

You can try out this version of the code here.

By condensing the program like before and converting it to Python, what we get is the following:

def gospers_pi():
    q,r,t,n,i = 1,0,1,8,1
    while True:
        if n == (q*(675*i-216)+125*r)//(125*t):
            yield n
            q,r = 10*q,10*r-10*n*t
        else:
            q,r,t,i = i*(2*i-1)*q,3*(3*i+1)*(3*i+2)*((5*i-2)*q+r),3*(3*i+1)*(3*i+2)*t,i+1
        n = (q*(27*i-12)+5*r) // (5*t)
pi = gospers_pi()
print([next(pi) for _ in range(10)])

$ python3 gospers.py
[3, 1, 4, 1, 5, 9, 2, 6, 5, 3]

This function performs slightly better than the one Gibbons proposed based on Lamberts expression.

The open problem

Jeremy Gibbons concludes his paper by making a conjecture that, if proven, would substantially improve his spigot algorithm based on Gosper’s series. The conjecture is the following:

Define the following functions: $$ \begin{align} n(z,i) &= \left\lfloor {z\left(\tfrac{27i + 15} {5}\right)} \right\rfloor\\ p((z,i),n) &= (z\big(\begin{smallmatrix} 10 & -10n\\0 & 1\end{smallmatrix}\big), i) \\ c((z,i),z') &= (zz',i+1)\\ s((z,i),n) &= (n = \left\lfloor {z\left(\tfrac{675i - 216} {125}\right)} \right\rfloor)\\ \end{align} $$ For $i = 1,2\dots$, let $$ \begin{align} x_i &= \big(\begin{smallmatrix} i(2i-1) & 3(3i+1)(3i+2)(5i-2)\\0 & 3(3i+1)(3i+2)\end{smallmatrix}\big)\\ u_0 &= (\big(\begin{smallmatrix}1 & 0\\0 & 1\end{smallmatrix}\big), 1)\\ u_i &= p(v_i, y_i)\\ v_i &= c(u_{i-1}, x_i)\\ y_i &= n(v_i)\\ \end{align} $$ Then $s(v_i,y_i)$ holds for all $i$.

If the conjecture holds, the Haskell program becomes:

piG3 = g(1,180,60,2) where
  g(q,r,t,i) = let (u,y)=(3*(3*i+1)*(3*i+2),div(q*(27*i-12)+5*r)(5*t))
               in y : g(10*q*i*(2*i-1),10*u*(q*(5*i-2)+r-y*t),t*u,i+1)
main = print (take 10 piG3)

$ ./main
[3,1,4,1,5,9,2,6,5,3]

Or, translated into Python:

def gospers_pi_unproven():
    q,r,t,i = 1, 180, 60, 2
    while True:
        u,y = 3*(3*i+1)*(3*i+2), (q*(27*i-12)+5*r)//(5*t)
        yield y
        q,r,t,i = 10*q*i*(2*i-1),10*u*(q*(5*i-2)+r-y*t),t*u,i+1
pi = gospers_pi_unproven()
print([next(pi) for _ in range(10)])

$ python3 piG3.py
[3, 1, 4, 1, 5, 9, 2, 6, 5, 3]

This version of the program is considerably faster than all other spigot type algorithms I’ve tested. Of course, because the conjecture is still unproven, this algorithm is not guaranteed to produce the correct digits for π indefinitely (although I did in fact test it successfully up to one million digits).

Side by side comparison and summary

Even though spigot algorithms are not that useful today, it is very nice seeing how they perform on modern hardware. Below is a graph showcasing the difference in speed between the various algorithms introduced throughout this article.

A side by side comparison of different spigot algorithms

If you'd like to learn more about how I tested and timed the various algorithms you can see some of the code I used by clicking here.

You can see how the algorithm derived from the Leibniz series, originally proposed by Rabinowitz and Wagon and later improved by Gibbons is extremely slow compared to the others. On the other end of the spectrum, the algorithm produced using Gosper’s expression is about 10 times faster, although still based on an unproven conjecture.

Even though there is probably no reason for you to generate a large number of π’s digits by yourself, especially using slow spigot algorithms, I hope you found this small glimpse into the past of computing as interesting as I did. If you have any suggestions or comments, please feel free to contact me using any method of communication listed on the sidebar of this page.

References

A. H. J. Sale, “The Calculation of e to Many Significant Digits,” The Computer Journal, vol. 11, no. 2, pp. 229–230, Aug. 1968, doi: 10.1093/comjnl/11.2.229. [Online]. Available: https://academic.oup.com/comjnl/article-lookup/doi/10.1093/comjnl/11.2.229
S. Rabinowitz and S. Wagon, “A Spigot Algorithm for the Digits of Pi,” The American Mathematical Monthly, vol. 102, no. 3, pp. 195–203, Mar. 1995, doi: 10.1080/00029890.1995.11990560. [Online]. Available: https://www.tandfonline.com/doi/full/10.1080/00029890.1995.11990560
J. Gibbons, “Unbounded Spigot Algorithms for the Digits of Pi,” The American Mathematical Monthly, vol. 113, no. 4, pp. 318–328, Apr. 2006, doi: 10.1080/00029890.2006.11920310. [Online]. Available: https://www.tandfonline.com/doi/full/10.1080/00029890.2006.11920310
J. Arndt and C. Haenel, Pi - Unleashed. Springer Science & Business Media, 2001.

Adding background music to Conway’s Game of Life

2020-09-03T00:00:00+00:00

Conway’s Game of Life never ceases to amaze with the complex patterns that arise from its deceivingly simple rule set. An infinite, two-dimensional orthogonal grid of square cells, each of which is in one of two possible states, alive or dead. A cruel place where lonely cells die and happy cells reproduce. The rules are as follows:

Every cell interacts with its eight neighbours, which are the cells that are horizontally, vertically, or diagonally adjacent. At each step in time, the following transitions occur:

Any live cell with fewer than two live neighbours dies, as if by underpopulation.

Any live cell with two or three live neighbours lives on to the next generation.

Any live cell with more than three live neighbours dies, as if by overpopulation.

Any dead cell with exactly three live neighbours becomes a live cell, as if by reproduction.

Wikipedia, Conway’s Game of Life

Implementing the game

Implementing the game’s algorithm in Python is actually pretty easy:

import numpy as np

def update(frameNum, img, grid, N): 
    newGrid = grid.copy() 
    for i in range(N): 
        for j in range(N): 
            # for each pixel calculate the 8-neighbor sum incorporating the needed wrap-around of x and y
            total = int((grid[i, (j-1)%N] + grid[i, (j+1)%N] + 
                         grid[(i-1)%N, j] + grid[(i+1)%N, j] + 
                         grid[(i-1)%N, (j-1)%N] + grid[(i-1)%N, (j+1)%N] + 
                         grid[(i+1)%N, (j-1)%N] + grid[(i+1)%N, (j+1)%N])/255) 
  
            if grid[i, j]  == 255: 
                if (total < 2) or (total > 3): 
                    newGrid[i, j] = 0 
            else: 
                if total == 3: 
                    newGrid[i, j] = 255 
  
    img.set_data(newGrid) 
    grid[:] = newGrid[:]

def randomGrid(size): 
    return np.random.choice((255, 0), size*size, p=[0.2, 0.8]).reshape(size, size) #return a random grid with more pixels off than on

For obvious reasons, instead of a truly infinite grid, we use a finite, square grid that wraps around to form a torus-like surface.
To test the two functions we can generate and plot a random grid and then plot it again after running update():

import matplotlib.pyplot as plt 

grid = np.array([]) 
grid = randomGrid(100) 
fig, ax = plt.subplots(figsize=(9,9))
img = ax.imshow(grid, interpolation='nearest', cmap='Greys_r')

update(2, img, grid, 100)
fig, ax = plt.subplots(figsize=(9,9))
img = ax.imshow(grid, interpolation='nearest', cmap='Greys_r')

For example we can see how the cell at (0, 0) which is initially dead and has precisely 3 neighbours (at (1, 100), (100, 0) and (100, 100)) becomes alive in the second snapshot.

Adding music to the mix

Many people have used Conway’s Game of Life to produce music, but I had something different in mind.
I realized that, to people that didn’t understand the rules or weren’t as interested in dumb mathematical games as I was, the simple black and white GIFs and videos that we usually use to showcase the game appeared very dull. One solution would be making cells more colorful, but that would either involve messing with the underlying rules of the game, or adding a huge amount of randomness, fundamentally altering the game either way. Another solution, which I finally decided to implement, would be to sync the game to music, updating the grid according to the rhythm of the music.

Attempt #1 — Using rhythm detection

To make the game respond to music I first had to find a way to get meaningful information (from a computer’s perspective) out of the actual sound clips. The first and simplest thing I naturally thought about was tempo (bpm).

import IPython # for interactive previews of audio clips and videos
import moviepy.editor as mpe # for combining audio and video tracks
import essentia.standard as es # for analysis of the audio tracks

For testing I’m using a small clip from the song Feel Good by Syn Cole provided for free by NoCopyrightSounds:

song_filepath = 'audio/feelgood_crop.wav'

audio = es.MonoLoader(filename=song_filepath)()
duration = len(audio)/44100.0 #in seconds
print("Song duration: {:.2f} sec".format(duration))
IPython.display.Audio(song_filepath)

Song duration: 31.00 sec

To extract the bpm value straight from the sound clip I used a super cool open-source library called Essentia, that provides very easy to use Python bindings.
Using the RhythmExtractor2013 algorithm we get predictions for the bpm of the song as well as the precise location of each detected beat:

rythm_extractor = es.RhythmExtractor2013(method="multifeature")
bpm, beats, beats_confidence, _, beats_intervals = rythm_extractor(audio)

print("BPM: {:.2f}\nFirst beat at {:.2f} sec".format(bpm, beats[0]))

BPM: 123.90
First beat at 0.50 sec

We can try to visualize the detected beats by plotting both the waveform of the audio and the estimated beat positions (red lines):

from pylab import plot, show, figure, imshow
import matplotlib.pyplot as plt
plt.rcParams['figure.figsize'] = (15, 6)

plot(audio)
for beat in beats:
    plt.axvline(x=beat*44100, color='red')

plt.title("Audio waveform and estimated beat positions")
plt.show()

This does not really give us any useful information about the predicted beat locations. To see if the algorithm really predicts the correct locations we can instead mark each of those locations with a distinctive beep sound and listen to the result:

marker = es.AudioOnsetsMarker(onsets=beats, type='beep')
marked_audio = marker(audio)
es.MonoWriter(filename='audio/export.mp3')(marked_audio)

IPython.display.Audio('audio/export.mp3')

And indeed we can hear that the algorithm did a pretty good job at predicting the beat locations and the tempo of the song.

For songs with a constant tempo, like the one I’m using for testing, we can in fact ignore the beat positions and only use the bpm value.
We can now make our first attempt at putting everything together:

# movement(frames) per beat
mpb = 1

import matplotlib.pyplot as plt  
import matplotlib.animation as animation
from math import ceil

fps = int(mpb * bpm / 60)

# Yet again we start with a random grid
grid = np.array([]) 
grid = randomGrid(100) 

fig, ax = plt.subplots(figsize=(15,15))
img = ax.imshow(grid, interpolation='nearest', cmap='Greys_r')
ani = animation.FuncAnimation(fig, update, fargs=(img, grid, 100, ), 
                              frames = ceil(fps * duration), 
                              interval=1, 
                              save_count=50);

ani.save('temp/render.mp4', fps=fps, extra_args=['-vcodec', 'libx264'])
plt.close()

After rendering the animation we pass the clip to moviepy to add the background music:

my_clip = mpe.VideoFileClip('temp/render.mp4')
audio_background = mpe.AudioFileClip(song_filepath)
final_clip = my_clip.set_audio(audio_background)

final_clip.write_videofile("save/output1.mp4", verbose=False)

And we can finally preview the result:

IPython.display.Video('save/output1.mp4', width=625, embed=True)

The result, even if not that stunning, is very much a success! The movement does truly seem to follow the tempo of the song, so mission accomplished right?
Well, not really.
Even though this method works pretty well for songs with a constant tempo, when we try using it for other songs we start seeing its limitations.
One of the best examples for this is a piano composition called Sad Day by Benjamin Tissot (provided for free by bensound.com).

This is how the predicted beats for this song sound like:

IPython.display.Audio('audio/sadday-export.mp3')

At this point it was easy to tell that bpm was not really the best metric for achieving my goal. Even though the tempo does appear to be accurate for some parts of the clip, the overall feel of the song is certainly not being portrayed. A sad song like this should not result in a fast animation.
From this point on, the goal was to find a way to get better results across multiple types of music. To make sure I was making progress I decided to use the piano track as a test song for all following attempts.

Generalizing the video creation algorithm

Let’s load the new clip and start working on a better solution.

song_filepath = 'audio/sadday_crop.wav'

audio = es.MonoLoader(filename=song_filepath)()
duration = len(audio)/44100.0 #in seconds
print("Song duration: {:.2f} sec".format(duration))
IPython.display.Audio(song_filepath)

Song duration: 29.22 sec

The first thing that I had to do was finding a consistent way of going from a song and a list of timestamps (e.g. of beats) to a video. To achieve this I created this simple function that first generates all frames needed and saves them to disk and then takes those frames, converts them to clips and combines them all to create a video. This allows us to only switch frames when we reach a new timestamp and totally avoid average values (like bpm).

def animate(timestamps, output_filepath, audiofile=song_filepath):
    grid = np.array([]) 
    grid = randomGrid(100) 

    fig, ax = plt.subplots(figsize=(15,15))
    img = ax.imshow(grid, interpolation='nearest', cmap='Greys_r')

    # generate and save to disk all consecutive frames needed to make the animation
    for i in range(0, len(timestamps) - 1):
        update(i, img, grid, 100)
        plt.savefig("temp/img{}.jpg".format(i))
    
    plt.close()

    # transform those frames to clips with the needed duration
    clips = []
    for i in range(len(timestamps) - 1):
        dur = timestamps[i+1] - timestamps[i] # the duration of the clip is as much as the time between this and the next timestamp
        newclip = mpe.ImageClip("temp/img{}.jpg".format(i)).set_duration(dur)
        clips.append(newclip)
    
    # combine all clips to one
    concat_clip = mpe.concatenate_videoclips(clips, method="compose")
    
    # add the background music and export
    audio_background = mpe.AudioFileClip(audiofile)
    final_clip = concat_clip.set_audio(audio_background)
    final_clip.write_videofile(output_filepath, fps=24)

To test this we can calculate the beat positions of our new sample song and using the output generate a video:

bpm, beats, beats_confidence, _, beats_intervals = rythm_extractor(audio)
animate([0] + beats.tolist() + [duration], "save/output2.mp4")

IPython.display.Video('save/output2.mp4', width=625, embed=True)

The result is as disappointing as I expected (because we are still using beats) but at least we now have a more generalizable way of producing these videos.
Now the only thing that remains is finding an algorithm that returns more meaningful timestamps for our songs.

Attempt #2 — Using onset detection

Looking through different examples from Essentia’s documentation I stumbled upon a way to detect onset locations for a given track (Onset detection) which at a quick glance seemed like a way better idea than just using beat detection.
Wikipedia defines an onset as "The beginning of a musical note or other sound" which actually further increased my expectations. The only problem is that onset detection is still an active research area and the algorithms aren’t quite that good yet.
Either way I decided to give it a try.

The following code, found in Essentia’s documentation gives us a list of timestamps of detected onsets:

import essentia
import essentia.standard as es

audio = es.MonoLoader(filename=song_filepath)()

od1 = es.OnsetDetection(method='hfc')

w = es.Windowing(type = 'hann')
fft = es.FFT()
c2p = es.CartesianToPolar()
pool = essentia.Pool()


for frame in es.FrameGenerator(audio, frameSize = 1024, hopSize = 512):
    mag, phase, = c2p(fft(w(frame)))
    pool.add('features.hfc', od1(mag, phase))

# Compute the actual onsets locations
onsets = es.Onsets()

onsets_hfc = onsets(essentia.array([ pool['features.hfc'] ]), [ 1 ])

And we can once again preview their locations using beeps:

marker = es.AudioOnsetsMarker(onsets=onsets_hfc, type='beep')
marked_audio = marker(audio)
es.MonoWriter(filename='save/onsets.mp3')(marked_audio)

IPython.display.Audio('save/onsets.mp3')

Now this is more like it! The beeps do actually seem to indicate the beginning of musical notes and also portray the overall feel of the song much better. The only thing left to do now is to create the video:

animate([0] + onsets_hfc.tolist() + [duration], "save/output3.mp4")

IPython.display.Video('save/output3.mp4', width=625, embed=True)

Awesome! Now you can almost see the sadness in the video.

If you’d like to see what the output looks like when using an entire song as input, you can find an example on YouTube:

Correcting population density data using satellite imagery

2020-06-01T00:00:00+00:00

To learn more about this challenge you can visit the official page of the NASA Space Apps Covid-19 Challenge.

The contents of this post where originally contained within a jupyter notebook which is available for download on Github

Believing that the most common definition of population density (population of country / area of country) was not the best metric for how close people are living in a given country, we wanted to find a way to calculate a new and improved population density for each country. After observing several nighttime images using Worldview with the VIIRS Nighttime Imagery layer we came to the conclusion that -in most countries- more people live in or around urban centers (indicated by higher light emittance in these areas) and thus instead of using the overall area of a country to calculate the density, we could use a corrected value based on what part of the country is active at night.

For finding the white pixel percentage and doing basic image manipulation we are using the OpenCV (cv2) library:

import cv2
import matplotlib.pyplot as plt

We first load the image we want to test which we have previously captured using Worldview and cropped to only include the country we are interested in (e.g. Greece):

img = cv2.imread('Images/Greece/greece_crop.png')
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) # get a grayscale only version of the image

This is what our input image looks like:

Here, we set the variable that dictates which colors should be considered white and which black (for example here all pixels that are over 51 (20% white) are considered light pixels). This is finely tuned for each image as it is highly dependent on weather conditions:

threshold = 51

height, width = gray.shape[:2]
total, light = 0, 0

Iterating over each pixel of the image we count the light pixels (pixels that are over the threshold) and also change the color of each detected light pixel to red, something that we use to determine if our threshold is correct or not.

for i in range(0, height):
    for j in range(0, width):
        val = gray.item(i, j)
        if val: # this is not a cropped pixel
            total += 1
            if val >= threshold: # this is a light pixel
                light += 1
                # Set the color of detected pixel to red
                img.itemset((i,j,2), 0)
                img.itemset((i,j,1), 0)
                img.itemset((i,j,0), 255)

Finally our program returns the percentage of light pixels in the image (excluding the totally black parts which are the parts we have manually cropped out):

print("{}/{} ({:.3f}%)".format(light, total, light/total * 100))

463511/4126770 (11.232%)

As you can see only 11% of Greece seems to be active during the nighttime!

To see if our threshold is correct we examine the output image to see if all lights (or at least the ones we can detect) are lit up:

In this example we can see how the capital (Athens) and the other large Greek cities (like Thessaloniki, Patras and Larissa) appear way redder than others and can even be spotted without knowledge of their precise location beforehand (give it a try). We can also spot the most popular islands (e.g. Santorini and Mykonos) just by examining how much light they emit.

Choosing a correct threshold value

The biggest problem with a method like this is that slight changes to the threshold value make a huge difference in the final percentage of light pixels detected and objectively choosing the proper value for it does not seem possible. To see how big the effect of the threshold value is, we can plot the resulting percentage against it, as seen below:

thresholds = [0 for i in range(0, 256)]
total = 0

for i in range(0, height):
    for j in range(0, width):
        val = gray.item(i, j)
        if val:
            total += 1
            for x in range(0, val + 1):
                thresholds[x] += 1
thresholds = [round(light / total * 100, 3) for light in thresholds]

import matplotlib.pyplot as plt
fig = plt.figure()
plt.plot(range(0, 256), thresholds)
plt.xlabel('Threshold', fontsize=12)
plt.ylabel('Percentage of light pixels', fontsize=12);

The percentage drops almost vertically around a threshold of about 25 and even though we can confidently say that, in this case, the threshold should be between 45 and 55 by observing the output images, the percentage difference between those values is pretty substantial. This showcases what we feared from the beginning: without a set method for finding the correct threshold value our results are pretty much useless.