SYNOPSIS
OPTIONS
DESCRIPTION
# **kern data processing:
mkeyscape file.krn > file.ppm
mkeyscape file.krn | pnmtopng > file.png
cat file.krn | mkeyscape > file.ppm
cat file.krn | mkeyscape | pnmtopng > file.png
# MIDI data processing:
mkeyscape file.mid > file.ppm
mkeyscape file.mid | pnmtopng > file.png
Graphical output from the program is a format called PPM 3 which is a text-based image format. Here is a sample of raw output data from mkeyscape which is 3 pixels high and 6 pixels wide:
The first column contains the string "P3" which indicates the data format for a text-bast PPM image file. The second line contains two numbers: The width of the image in pixels, and the height of the image in pixels. The third line contains the maximum color value in the list of numbers which follow. In this case each color value represents one byte of data and the maximum value is 255. Following the header information is a serial list of the pixels in the image. Each pixel is represented by three numbers. The first number represents the amount of red in the pixel, the second number is for green, and the last number is for blue. White is represented by maximum brightness for all pixels: "255 255 255" and black by minimum brightness for all colors: "0 0 0".
In this case are a total of 18 pixels and therefore
54 numbers are expected after the header. The formatting of the lines
is arbitrary, but in this case the numbers map how the final image is
to be displayed.
The pixel list starts at the top left
of the image, going left to right, then through successive rows to the
bottom of the picture. Thus in this case, you can see that there are 18
pixels on each row, representing the 6 pixels on each row of the image,
and there are three rows of pixels which represent the 3 pixels height
of the image. Here is the PPM image converted to a visual graphic:
Graphic File Conversion and Processing PPM images can be enormous and take a lot of space to store, so you will probably want to store the output images in another format. If you want to store the PPM images (for later processing with text-based programs, for example), you might want to consider compressing them:
bzip2 prelude28-03.ppm
will create a file called prelude28-03.ppm.bz2 which
is even smaller than other graphics types you could convert
the image to. To uncompress the file, type
"bunzip2 prelude28-03.ppm.bz2 or you can pipe a temporary
output to another program with "bzcat prelude28-03.ppm.bz2 | less,
where less is an example program you can send the uncompressed
data to.
Most of the time, however, you will probably prefer to store the resulting images in a more convenient image format, such as PNG. Here are two ways of converting the PPM 3 data into PNG data: (1) From the command-line the output PPM data can be piped to another unix command called pnmtopng which is often pre-installed on linux computers. The following command-line:
mkeyscape -s 150 prelude28-03.krn | pnmtopng > prelude28-03.png
will generate the following PNG image which is 150 pixels high, and 300 pixels wide:
(2) Another program which can convert PPM images on the command-line is called convert. This program is more widely distributed, and has more features since it can convert almost any image format to any other image format. To accomplish the same task with convert, you would type two commands:
mkeyscape -s 150 prelude28-03.krn > prelude28-03.ppm
convert prelude28-03.ppm prelude28-03.png
With convert you can also resize the image at the same time.
For example if you want to make a thumbnail image when you convert,
you can try this command:
convert prelude28-03.ppm -resize 50 prelude28-03-tn.png
which generates the 50x25 pixel thumbnail image shown to the right.
Another useful feature of convert is the ability to add text on top of the image:
convert prelude28-03.ppm -font NewCenturySchlbk-Roman -pointsize 12 \
-draw "text 5,20 'Chopin prelude 28/3' prelude28-03-text.png
which produces text starting at pixel (5,20) from the top left corner
of the image:
 A list of fonts recognized by convert can be found in configuration files which are found on my computer in the directory /usr/lib/ImageMagick-6.2.4/config. Here is a list of fonts which might work for you based on the files in that configuration directory: fontlist.txt. Another use of the convert program is to generate a transparent background. Here is a rather painful way of making the white background of the image transparent:
convert prelude28-03.png -bordercolor white -border 1x1 -matte \
-fill none -fuzz 5% -draw 'matte 0,0 floodfill' -shave 1x1 \
prelude28-03-trans.png
which generates this image:
 A command-line program called transparency may also be use to create transparent backgrounds. You will probably have to install this program, since it does not come with OS installations by default. Also, you could save this bash script to a file: For example, save the above text to a file called maketransparent. Then make sure that it is executable by typing "chmod 0755 maketransparent", and then run by giving the original file name first, followed by the filename of the image with the transparent background:
maketransparent oldfile.png newfile.png
If your program search path does not include the current directory, you
will have to type:
./maketransparent oldfile.png newfile.png
Key to Color Mapping Key color representation is ultimately arbitrary, but the convention in the mkeyscape program is to assign the seven colors of the rainbow to the seven diatonic-pitch classes, arrange by circle of fifths with the C pitch-class centered at green: red=E, orange=B, yellow=F, green=C, blue=G, indigo (dark blue) = D, purple=A. Chromatic alterations of the diatonic pitches are displayed in intermediate colors along the circle-of-fifths. For example F is yellow, and F-sharp is a greenish-yellow, and F-flat is an orangish-yellow. In the future, arbitrary color maps for the keys will be an input option to mkeyscape. Absolute Key vs. Functional Key When comparing the key structure of large numbers of compositions in different keys, it is useful to color the keys functionally rather than with the absolute pitch color. For example, if green (usually representing the pitch class C) is defined as the tonic key, then the dominant key is in light blue, the subdominant color is yellow, and so on. In a Humdrum file, if the start of a composition contains a key specification, then you can transpose the music to C major, and interpret the key colors functionally rather than as absolute pitch-class colors. For example, using the transpose command, you can easily convert prelude28-03.krn to C major before sending it to mkeyscape to be converted into an image:
transpose -k c prelude28-03.krn | mkeyscape -s 150
The file prelude28-03.krn contains a marker for G major, *G:, which
is used to instruct the transpose program how to convert the music
into C major. If there is more than one primary key in the music, all
other subsequent key-regions are ignored during the transposition.
In other words, the dominant key of the dominant key will be displayed
in dark blue, just as the supertonic key will be (there will be
a brightness difference though, since the first is a major key and the
second in a minor chord/key). Here is the resulting image when transposing
to C major.
 Now, the tonic color is green, the dominant is blue and the subdominant key region is yellow. MIDI input can be transposed using the -t option to transpose the music before key analysis is done. For example to transpose the music up by a perfect fifth, you can type either of the two commands:
mkeyscape -t 7 file.mid
mkeyscape -t -5 file.mid
Which will transpose the music up 7 steps, or equivalently, down 5 steps.
Humdrum file data can also be transpose in this manner, but there is
no automatic method to transpose the key to C major/minor with the
Underlying Key Analysis Method Key analysis is accomplished by comparing a histogram of the pitch-classes to what would be expected in each major and minor key. The key which fits best is then assigned a color in the keyscape plot. The algorithm used in mkeyscape is the Krumhansl-Schmuckler algorithm which does a Pearson correlation between the measured histogram of pitch classes and the pre-determined profiles for major and minor keys. Pearson correlation generates a value between -1.0 and +1.0 for the comparsion between the histogram and a particular key profile with better matches being given higher values. The key-profile which generates the highest Pearson correlation to the measured histogram of pitch classes is decided to be the key of the musical region. When modulation occurs inside of the region of music being analyzed, the algorithm may prefer one key over the other, or it may even decide on a third key, generating noise in the keyscape plot. If the analysis results of this algorithm were ideal, the following picture would be generated for Chopin's prelude Op. 28, No. 3.
 The music start in G major (the tonic), then goes into the dominant key area, returns to the tonic, then goes into the subdominant key region for a longer period than when in the dominant, and finally returns to the tonic at the end of the piece. Analysis Data Using the --hist option will output a histogram of the pitch-classes for every segment. Here is the output from the command keyscape --hist prelude28-03.krn -s 10:
The values in the histogram are relative to the duration of the frame. If you want the values in the histogram to represent the number of quarter notes of each pitch-class in each segment, use the scordur program to find the duration of the music in beats. For prelude28-03.krn, the duration is 132 beats, so the command: "mkeyscape -s 132 --hist prelude28-03.krn" will give this result: The --hist output data is similar to Chromograms extracted from audio data (but there is no interference from harmonics). Using the -c option allows you to specify any color for the 24 major / minor twelve-tone keys as well as the color for silence (default is black) and the background image color (default is white). The color file is a text file in the Humdrum file format as shown in this example: There must be a spine called **index and a spine called **pixel. There can be any number of other spines, such as **comment in the example file, and the index and pixel spines can occur in any position. If there are more than one index or pixel spine, the ones furthest to the right will be used. The above example color file is also the default color scheme for mapping keys to color. If you only want to change specific colors and keep the rest as in the default, you only have to specify the colors you want to change. For example, if you only want to change the background color from white to black, you could use this color file: Key Profile Weights
      Keyscape of Schenker's Heimat, Op. 6, No. 1:  More example usages of the mkeyscape program are avaliable on the mkeyscape examples page DOWNLOAD
The source code for the program was last modified on 3 Feb 2008. |
