#
Coagula
Industrial Strength Color-Note Organ
by rasmus ekman
installation
how it works
painting tools
making sound
keyboard shortcuts
contact
2018 note
This file used to be a Microsoft Windows help file, with nice hyperlinks between topics.
MS killed the HLP format long ago, and I can't be bothered to fix it properly, so this is just a quick cleanup
hack&slash.
Most things that look like links cannot be clicked.
The text explains stuff that is self-evident, and leaves out things that are really quirky.
Just play around with the program instead!
If you want you can have the original RTF format file and images, just holler.
#
System Requirements
You need Windows 95 or later. A monitor which can show thousands of colors is highly recommended.
Installation
Coagula uses the folder (directory) layout to find things.
• The images in the "Filters" folder will be loaded into the Image Browser at startup.
• You may set the default filter folder under the Options menu.
• The image folder is changed at any time; when you open an image.
Getting Started
The quickest way to understand how it works is to start the program, make some marks on the empty
(black) canvas, and hit F5 to generate some sound.
The resulting sound will be played back when it is ready.
Figurative pictures will usually not result in any interesting sound connections - but do whatever you like.
Especially do whatever you like, it can be undone ten times.
Coagula has some image editing tools less common in other image editing programs -- or never seen
before; check out the filtering features, and colour boiling.
Lots of stuff that would be really useful is also missing -- it's not exactly a Photoshop killer. But...
Tip
You can save the image to disk and open it in your favourite real image editor. After editing, save in that
program, switch back to Coagula and select Refresh under the File menu to immediately reload the
image from disk (or just hit the "R" key). This may help make it feasible to disfigure your pictures
productively.
Presentation
Coagula is an image synth. This means that it is both a program for creating and manipulating images,
and a program for generating sound from those images. Coagula reads image data and adds up
masses of sine waves -- each line in the image controls the amplitude of one oscillator at a certain pitch.
The vertical position of a pixel (image point) decides the frequency, while its horizontal position
corresponds to time. You can of course freely set the total time and the frequency range when you render
your image to sound.
The meaning of color
Red and green control stereo placement: Red is sent to left channel, while green controls amplitude of
the right channel. The brighter the colour, the louder the sound.
So, the basic sound generation formula in Coagula is:
Each dot = one blip.
In the diagram, the squares in the left part represent single pixels on your screen.
Orange = much red, a little green; this means loud left channel signal, softer right.
Yellow = max red and max green; this means equal left/right intensity. A dot that is vertically higher in
the image generates a higher-pitched sine blip.
Green = ...well, you get the idea... here the left channel stays quiet.
Blue is is used to smear the blips to dirty, noisy blotches.
This means that:
One blip + blue = a blotch.
The right-hand spectral views were made with a spectral analysis program (vertical is pitch). But they look
much compressed downward since spectral analysis commonly uses linear frequency representation.
Coagula uses exponential pitch, similar to hearing, and musical tones.
Coagula can read JPEG and BMP files, but only save BMP images. All images opened for editing will
be converted to 24-bit.
Tool Boxes
The Brush dialog The Colour boiler
The Image Browser The Echord toolbox
All tool dialogs can be folded up/out by double-clicking the title bar.
Basic Commands
Painting and selection Undo operation
Filters and overlays Image rotation and movement
There are many editing operations; here we just have some sketchy notes about the more specialized
ones. You will find a number of commands under the Edit menu. Some of them are documented
elsewhere, most work more or less like the corresponding command in any other image editor. Mail and
ask if there is some command you need to know more about, or that feels strange or seems to work
badly.
Use the left mouse button to apply the brush, and the right mouse button to select an area.
Extend selection by holding down the SHIFT key on your keyboard when right-clicking the canvas. This
allows for selection of areas of any size
All operations (except rotations and image movement) are applied to the selected area.
Undo
The ten most recent image editing operation can be undone. For some operations, like simple brush
editing (painting), or colour boiling, Coagula will wait one second before setting the next undo level. This
means that such operations will be chained in batches if you do them in quick succession.
Coagula stores ten numbered images in the Undo folder, and these are crudely circulated. Just keep
hitting CTRL+Z to see what you have (eventually you will come back to your most recent image).
CTRL+Y moves forward in the list of undone images.
The images in the Undo folder are kept between sessions, so you can start undoing right after starting
the program.
Filter
Each colour component in each pixel in a reference image (see below) is multiplied with the
corresponding pixel in the current selection of the image. The result of the multiplication is scaled so that
no pixel in the original image will be brighter after the operation, but it may be darker (this makes it
different from filter brushes).
Overlays
When you use a reference image as an "overlay", the pixels are added to the present image. You can
use this to resize an image: Create a new (black) canvas with the right size, and select the image as
overlay. You can also cut/copy and paste any (part of an) image as an overlay. Image data pasted from
the clipboard will also be fitted into the current selection.
Reference image: Any BMP image. This may be the currently selected one in the Image Browser, or it
may be taken from the clipboard. This image will be stretched to fit the current selection (or the whole
image, if there is no selection). If you use an image from the Image Browser, you can set the intensity of
the effect separately for each colour component.
There are keyboard shortcuts for each operation and reference image variant.
Use SHIFT+Left mouse button and drag to move the image freely up-down and left-right.
Use CONTROL+Left mouse button and drag to zoom-rotate the image. Vertical mouse movement
controls zooming level, while horizontal movement controls rotation. This operation uses the initial mouse
insertion point as the origin to rotate about.
Use CONTROL+SHIFT+Mouse drag to skew-flip the image (a parallelogram operation). Vertical mouse
movement controls the amount of vertical shift: The vertical lines to the left of the mouse insertion point
are moved up, while the lines to the right of the insertion point are moved down. The same thing, mutatis
mutandis, is done to horizontal lines, and controlled by horizontal mouse movement. This operation also
uses the initial mouse insertion point as the origin to rotate about.
Note: Both movement and the rotation operations work on the entire image, disregarding any selections.
The Brush toolbox controls what happens when you click and drag the mouse on the Coagula canvas.
The brush is actually a small image, shown in the "Shape and style" box, which is applied to the image
according to the various parameters. The brush uses two colours. They are selected in the palette using
the left and right mouse buttons, respectively. The colours can be faded horizontally or vertically, or mixed
in random amounts over the brush bitmap.
Create any colour: To mix the present brush colour with another colour (eg adding blue), hold down
SHIFT while clicking in the palette. The colour in the selected colour pane will be kept, and the new
chosen colour is added:
This allows construction of (more or less) any colour by combining red/yellow/green colours with grey- or
bluescale hues.
Gradients: You can apply the brush image to the current selection (or the entire image) by hitting the
F12 key. This makes it easy to create gradients (eg for images to be used as filters).
Spray brush: When you select the Spray brush style, the radio button is hidden, instead a slider appears
which sets the intensity of the spray.
Noise brushes are on average darker than faded brushes, since the the selected brush colours are used
as maximum values; the pixel values can be darker but not brighter than the brush colours. The noise
brush bitmap is redrawn with every operation (mouse movement or whatever). Note that "Noise" here
means colour noise, not sound noise -- though the resulting sound may be fairly gritty.
In the Color mix section you select how the brush colour is mixed with the colours already present in the
image. There are four modes of colour mixing:
"Cover" paints over the background.
"Add" will add the brush pixels to the background (the brush image is faded first because the colours
tend to add up to maximum intensity very quickly, so it is best used with dark noise brushes).
"Filter" will increase the intensity of image colours, if the brush colour is brighter than half intensity,
else the image colours will be faded. Try it at first on an image with large coloured areas.
Colour boiler
These options are hidden in the Brush toolbox. If you click the "Boil" option (radio button) in the colour
mixing section a new set of parameters are revealed:
These control cellular automata-type options which allow some involved colour manipulation as well as
blurring. This leans perhaps more to the eyecandy side of things than towards musical usefulness, but I
wanted to try it out, so there...
There are three independent things you can do here:
Brighten or darken the individual image colour components.
Cycle the image colour components (red/green -> blue -> red/green).
Blurring the image.
Brush Patches
You can store sixteen different brushes to recall at any time. Hold down the SHIFT key and click one of
the brush patch buttons to store a parameter set. If the colour boiler is open, its settings will also be
saved. Click one of the brush patch buttons to recall the saved brush parameters. The patches are stored
between sessions in the Windows Registry.
Amount of Effect
The selected brush colours will be used to control how much each colour component in the image is
affected by the boiler. If eg the brush is red and blue, the green component will not change. When boiling
the whole image, rather than painting with the brush, the current brush colours and shape will be
stretched to fit the current selection. To get full effect on all colours all over the image, use a white
rectangle.
Boil
The "Heat" slider adds a positive or negative value to each colour component. Colour values are
wrapped, so if you add more than the maximum intensity (or subtract to less than zero), the colour will
jump to the opposite extreme. As mentioned, the heat value will be multiplied by the corresponding point
in the stretched image of the brush before being added to the image pixel.
Colour Cycling
The "Cycle" slider (lower left) controls how much the colour components will "bleed" into each other,
meaning that a fraction of the intensity of one colour component is added to another (maximum is 20%).
So if the brush is blue and the image has red and green, some blue will be added to those pixels. To keep
this effect from immediately exploding, all colours must not bleed into each other simultaneously.
Therefore green and red are averaged to set the amount of blue added, and only if any blue is present will
the average of red+blue be added to green, and similarly green+blue be added to the red. Red and green
will thus not bleed directly into each other, except via blue.
Blur
The two lower sliders, "Blur" and "Shift", control amount and direction of blurring. This is currently the
only blurring option in the program. "Shift" controls the horizontal direction of blurring. By eg using an all
green brush you can nudge the green colour components while the red and blue coloured parts stay in
place.
Apply to Selection
For maximum confusion, this effect may also be run on the whole image (or the current selection) from a
menu option, under Edit | Color Operations. (Don't forget the keyboard shortcuts now, a choppy but trippy
animation can be had by holding down the "C" key.)
When used from the menu, the brush colours will still be used - stretched to fit the selection - to control
the amount of effect in the selection.
As explained in the presentation, Coagula will use the red and green colour components of each pixel to
generate left and right channel sine waves.
Since version 1.6, the blue colour component is used to control the noisiness of any red/green signal at
the same pixel. As the colour fades from no blue to maximum intensity, the signal goes from the standard
sine wave to a noise band. The result is that white (magenta/cyan) areas in the image will yield a dense
spectrum.
The noise band in Coagula is a mix (actually, a real mess) of randomly time-varying frequency and
amplitude modulation (ie both FM and AM).
This image was generated to sound. Pitch range 40-11025 Hz.
The
blueness gradually increases, expanding the noise bands.
The overall maximum amount of noisiness can be controlled in the More options section of the Render
Options dialog:
Below we show that Coagula generates fairly smooth sound, which falls off very quickly. The noise is
biased to the lower end of the spectrum. This is not bad, one will often want to filter blue from the upper
range anyway.
Spectrum of an all-white image (200 lines high) at pitch range from 20 Hz to 11025 Hz.
Due to the workings of the noisery, it is better to render no higher than 1/4 of sample rate (11025 Hz in a
44.1 kHz soundfile). When the same image was rendered with frequency range 20 Hz - 16 kHz, the noise
continues up to maximum frequency, and was uneven in the topmost range (probably due to aliasing).
There (used to be) some more material on these measurements at the Coagula web pages.
Echord toolbox
Here you add faded copies of the current selection to the image. The effect is echoes and "chords".
You can fine-adjust the most recent used (highlighted) slider in the Echord dialog with the arrow keys.
The default value of any slider can be restored by holding down the SHIFT key and clicking it.
Hop Direction
The "Angle" slider sets the direction of the hops. 0 degrees is straight up; degree increases clockwise (90
degrees is straight right). The hop angle may be skewed by a "Warp" factor. Positive warp turns the hops
gradually clockwise, while negative warping bends the line of hops counter-clockwise.
Sliders
"Hop" sets the stepping between copies, in pixels.
"Num" controls how many copies are created.
"Fade" sets a fade factor for each step.
"1st Hop" sets the stepping to the first image copy.
"1st Fade" sets the fade factor for the first image copy.
"Mul" slider sets a factor for stepping, making the hops gradually shorter or longer.
"Rnd" controls length randomness for each hop. The randomness factor is increased with each hop.
"Jitter" controls hop randomness for each individual pixel, resulting in a smeared/noisy image. The
jitteriness is also increased for each hop. (This was called Rnd in the first versions of Coagula);
Checkboxes
"Wrap echo" when checked makes echoes continue over the right edge of the image and come back
from the left, or vice versa. This is useful for creating looped sounds. "Wrap" has no effect on
chords/pitches however (ie it is not effective vertically).
"Swap r/g" and "Alt r/g" checkboxes switch red and green colours, at the first hop, and at every hop,
respectively. This results in left-right bouncing echoes and correspondingly sends chord overtones into
the opposite stereo channel.
Echord Patches
You can store eighteen (2 x 9) different echord settings to recall at any time. Hold down the SHIFT key
and click one of the echord patch buttons to store a parameter set. Click one of the echord patch buttons
to recall the saved echord parameters. The "00" patch sets the all sliders to their default values. The
patches are stored between sessions in the Windows Registry.
This tool window will show all images in opened folders as thumbnails, ie as miniature copies. It is used to
select the reference images for filtering and overlays operations. Some keyboard commands work with
the selected image in the browser, if the I.B. is the active window. They are described below.
Each tab in the Image Browser shows the images from one folder. If you add an image folder using the
"Add Folder" button, a new tab will be added to the dialog. All tabs created will remain open for the rest
of the session.
At start-up, the Image Browser loads all images in the selected Coagula Filter folder, plus all images in
the folders directly under this folder. (In later versions there will be more options, and/or the " Add Folder"
dialog will allow multiple selection of filter folders.) You can change the start-up filter folder from the dialog
under the Options | Select Filter Folder... menu.
Note: The miniaturisation formula (Windows built-in stretching in case you're interested) may distort some
images - many small-scale, regular patterns are distorted, or simply disappear - but most will appear ok.
Amount of Effect
When applying an image from the I.B. as a filter, you can select the amount of effect on each different
colour component. If you eg set the effect to zero for blue, the red/yellow/green filter images will not
remove any blue from the image. This means that you can do most filtering using only black and white
images. The filter image may also be switched in the left-right direction, or flipped upside down.
Note: The colour amount percentage settings are currently not applied when using an image as overlay.
Tip: If you later want to remove blue in the pixels that do not have any red or green colour left, you can
use the Remove Excess Blue command found under the Edit | Color Operations menu (shortcut:
CTRL+B).
Image Browser Commands
Click an image to select it. The image will get a blue frame, and its file name is shown in the title bar.
Double-click an image to use it as a filter on the current selection.
SHIFT+Double-click an image to open it for editing. The previous image is discarded.
There are a few keyboard commands which will work with the currently selected image in the Image
Browser, if and only if it is the currently active window. These are:
The cut and delete operations prompt you to confirm before deleting the image from the disk.
The Refresh command will re-read the images in the folder of the currently selected tab.
Generating Sound from the Image
Hit the function key F5 to generate a soundfile from the whole image, or SHIFT+F5 to synthesize only the
selected part. When rendering only the selection, Coagula will scale generated audio to keep the
amplitude maximised. This may be used for "zooming in" on the sound of murkier areas of the picture.
Rendering can be stopped by holding down the ESC key. The output will still be a playable, but shorter
sound (-file).
After rendering has finished, the sound will be played back automatically. Hit SPACE to stop it, or to
restart looped playback of the sound.
Render Options dialog
Control the duration and pitch range of the generated sound:
The frequency of each line in the image is a function of the height of the image and the selected
frequency range. The lowest pitch to use can be quite freely selected. The highest generated pitch should
normally be less than half of your sample rate (ie below the so-called Nyquist frequency). Otherwise the
highest pitches will be "mirrored" to lower pitches, which defeats the linear mapping of image position to
sound. If you set the pitch higher than the Nyquist frequency, you will be warned in the status bar (and
occasionally by a dialog). The Nyquist frequency of a 44100 Hz sound ("CD quality") is thus 22050 Hz,
which is very high and not usually musically useful by itself -- though it's relevant for the "brilliance" of a
sound.
You can see the pitch interval between each image line in the Step textboxes in the dialog. The value is
given in cents, where one cent is a 100th of a semitone (of which there are twelve per octave, so a cent
is a 1200th of an octave). The smallest pitch intervals that most people can distinguish is about 2 or 3
cents for single tones, but it turns out that we would need much much more narrow intervals to create a
really dense spectrum, ie to make the output sound from Coagula not sound like some dense but clean
cluster chord. That's why there is the blue->noise option in the retail version; then we can use much fewer
lines and make proper hisses and noise sounds (fewer lines means faster rendering).
Pitch example: To control the pitch interval between image lines you must calculate the appropriate
values, and set both the image height and the frequency range accordingly.
Let's say you want to have one semitone step (100 cents) between each line. If we use a pitch range of 7
octaves, that will be = 84 semitones. So set the image height to 85 (adding the topmost octave note to
simplify the calculation of the frequencies). Each octave is a pitch doubling, so if you want to tune middle
A to 440 Hz, set the freq range to eg min = 55, and max = 7040; those will both be A:s.
To use quarter-tones in the same pitch range you just double the height of the image and add one
(7 octaves 24 quartertones + 1 for the topmost octave pitch = 169 lines).
Coagula attempts to guess the maximum output amplitude and make the output soundfile as loud as
safely possible. The routine looks at the pixels and attempts to find max amplitude, but it is a little
simplistic, and so does not work for all sounds. You can change the base amplitude factor manually in the
Amp factor edit box in the dialog.
As stated, each line in the image controls the amplitude envelope of an oscillator. Each pixel on the line
represents several samples (usually in the hundreds). To make a smooth transition between the
amplitude levels of consecutive pixels, the values must of course be faded gradually. The Soft Envelope
Sweeps checkbox controls the shape of the fade between pixels. If the box is checked, a half-cosine
envelope waveform is used. This gives a smooth transition -- and extremely clean sound -- but takes
about 10% longer time to generate. If the option is not checked, a linear fade is used, which will however
create minimal noise bursts in the sound. This may of course also be musically desirable.
Every time that you save an image, the pitch and time options of the last rendering is stored with the
image in two ways: As a secret attachment at the end of the BMP image file, and as a small text file. The
text file has the same name as image file, but with the file extension .info rather than .bmp. Whenever
you load an image, Coagula will look for this information, first at the end of the BMP, and then by looking
for a companion file. (Note that this only happens if you have rendered the (or some) image first, else the
info is not changed.)
The reason for saving the render options twice like this is that the BMP file format actually does not allow
proprietary information to be added (like WAV files and most other sensible file formats do). So if you
manipulate the image in another program and save it, the info will certainly not be retained, and the
program may even complain about the file being corrupt. If this becomes a problem, you can select not to
attach the render info, by unchecking the Attach Render Info to BMP option under the Options menu.
The text file is designed to be both human and machine readable, but they are a nuisance to keep track
of, so Coagula will first look at the end of each BMP file it opens. For instance, the Undo images do not
have any companion files, since these would surely get mixed up.
Technote
You can check a BMP image file to see if it has a Coagula info section. Open it in a binary file editor (or
text editor if you don't have one) and look towards the end of the file. You should see the "magic number"
which is 'rdnr' (= 72 64 6E 72 in hex, ie 'rndr' backwards) 100-200 bytes from the end.
Each time Coagula has rendered an image (or the selection), it will playback the generated sound.
An inverted line tracks the playback. If the length of the current sound does not correspond to the length
of the image (eg because rendering was interrupted by Escape key), the line is shown dotted.
Use the Space bar to stop or restart playback of the most recently generated sound.
Soundfile Folder
The output soundfile is stored in the current soundfile directory.
The default soundfile directory is:
(1) The directory given by the SFDIR environment variable (only for users of the program Csound,
else don't bother).
(2) The Coagula home directory.
You can open a dialog to select a new output folder under the Options | Output Soundfile Options menu.
Output Soundfile Name
The default is not to save the sound to file each time it is rendered. Instead there is a command Save
Soundfile As... on the File menu. You may select the auto-saving functionality described below by
checking the menu Save Sound At Every Render under the Options | Output Soundfile Options menu.
There are three options for naming the output soundfile:
(1) Always called Coagula.wav (default).
(2) Use image name (if any, else Coagula is used)
(3) Add a number to the soundfile name. The number is 00-99, and will be automatically incremented
each time you render a file. It wraps around after a hundred images. The most recently used
number is stored in the Registry entries for Coagula, so numbering continues between
sessions.
About Coagula
Coagula was created by rasmus ekman.
The current version is available from
https://www.abc.se/~re/Coagula/Coagula.html
Large parts of this program is basically just half a clone of (the first version of) MetaSynth for Macintosh,
but of course with some variations. Some other image-to-sound renderers exist, but most of them
provide very meagre image editing facilities or none at all.
