.TH getting-started 7 "February 2012" "numm" "Numm Tutorials"
.SH NAME
getting started \- numm installation and usage
.SH SYNOPSIS
numm-run \fIFILE\fR
.br
.B import numm
.SH DESCRIPTION
numm is a python library \(em
the bastard child of
\fBProcessing.org\fR and \fBMATLAB\fR,
if you will \(em
that fuses \fBpython\fR, \fBnumpy\fR, and \fBgstreamer\fR
together to create a numerical-computing environment
for multimedia generation, analysis, and interaction.
.SS Installation
A \fBDebian\fR package is provided for ease of installation
on Debian and derivative operating systems,
such as \fBUbuntu\fR;
we recommend you abandon alternative systems and install Debian,
but in the interim direct your attention to  virtualization software
such as \fBVirtualBox\fR.
.PP
The following command downloads and installs numm:
.EX
% wget http://numm.org/numm/releases/python-numm_0.1-1_all.deb
% sudo dpkg -i python-numm_0.1-1_all.deb
.EE
.SS Usage
At its simplest, \fBnumm\fR provides three pairs of invertable functions
that connect common media formats with \fBnumpy\fR:
.PP
Images
represented as (\fIheight\fR, \fIwidth\fR, \fIcolor\fR)
\fBnumpy.uint8\fR arrays.
.IP \(bu 4
image2np(\fIpath\fR) \(-> np
.IP \(bu 4
np2image(\fInp\fR, \fIpath\fR)
.PP
Sounds
as (\fIframes\fR, \fIchannels\fR) \fBnumpy.int16\fRs
.IP \(bu 4
sound2np(\fIpath\fR) \(-> np
.IP \(bu 4
np2sound(\fInp\fR, \fIpath\fR)         # XXX: must be .wav
.PP
Videos
as (\fIframes\fR, \fIheight\fR, \fIwidth\fR, \fIcolor\fR) \fBnumpy.uint8\fRs
.IP \(bu 4
video2np(\fIpath\fR) \(-> np
.IP \(bu 4
np2video(\fInp\fR, \fIpath\fR)         # XXX: must be .mkv
.PP
For rapid-prototyping of interactive numpy-based audio-visual experiments,
the numm package has a real-time mode.
The \fBnumm\fR package installs a program named \fBnumm-run\fR,
which launches
(and reloads on modification)
python scripts that may implement any subset of the following functions,
which are asynchronously called as needed:
.IP \(bu 4
video_in(\fIa\fR)                      # webcam
.IP \(bu 4
video_out(\fIa\fR)                     # mutate \fIa\fR in-place to set video
.IP \(bu 4
audio_in(\fIa\fR)                      # mic
.IP \(bu 4
audio_out(\fIa\fR)                     # mutate \fIa\fR for audio output
.IP \(bu 4
mouse_in(\fItype\fR, \fIpx\fR, \fIpy\fR, \fRbutton\fR)
.IP \(bu 4
keyboard_in(\fItype\fR, \fIkey\fR)
.SH SEE ALSO
.BR numm-run (1),
.BR numm.one-bit-instrument (7),
.BR numm.spectral-analysis (7)