*SculptView Help*
by Stanko Juzbasic

This document is published under GNU FDL


What is SculptView

It's a little visualization, interactive editing and signal-modeling resynthesis utility for partial tracking analisys files saved in text format. This is its second, not yot complete release, and so is its help file. As it is a free program, you have freedom of using it at your own risk and responsability, including freedom of understanding what you're doing. It comes with absolutely no warranty of any kind.

Which is the current version?

Version 0.7.x of December 2003.
This help files covers part of the functionality of v. 081+, in absence of a more up to date manual.

Which system does it work on?

Any UNIX/LINUX/MacOSX based workstation. The prototype is developed on an SGI O2 running IRIX-6.5, but it should easily port to other platforms, because it does not depend on any specialized or commercial libraries. You need to have a THREE-BUTTON MOUSE in order to make the program work properly. You also need a hardware accelerated graphics/video card with double-buffering, overlay visuals and OpenGL graphics software library. Having audio hardware is preferd (you would probably want to listen to your work) but it is not required, since all the processing and audio synthesis is file-based and there are no sound library calls from within the program.

How to install and build it

 If you run the binary, put it anywhere in your path, if you want the desktop look and feel, you should put icons and desktop_files into places where they belong to (see README file). If you compile it from source, you should probably edit the Makefile and put the proper name of the compiler that you use (such as gcc), platform definition (-D_LINUX_INTEL, for example) and adjust CFLAGS= and LDFLAGS= to point at proper locations for header and library files (also see README file).

How to start it

This version cannot yet be "double-clicked" to make start from the desktop icon. It has to be started from a UNIX shell like this:

> sculptview [infilename] -[options]

-Infile has to be in the format of IRCAM's "Partials Tracking Text Files", which are generated by AudioSculpt or by ceres3 programs.
-Version 0.81 also supports SDIF files in text format.

To whom can this program be useful

If you are kind of intermediate-level computer music practitioner, the concepts of additive synthesis, phase-vocoding and algorithmic composition should ring a bell. If you are using UNIX or LINUX already, you probably know more than you have to know about computers in order to use SculptView. If you need free a visualization tool in the education process, this can make sense to you.
If you are already familiar with IRCAM's Audiosculpt and Diphone, and Columbia CMC's RTcmix, SculptView can be an extra tool for you. If you are member in Forum IRCAM's Sound Design Group, than you are at home. Apart from that, there's just a few more theoretical basics worth taking into account:

What is "partials"

 A few mathematical theories of musical tone, dating back to the 19th century teach that musical tones can be decomposed into sets of primitive contours, simultanously independent but co-related (however, there are also other theories, which teach it does not really work). Their qualities (time, frequency, loudness) partially contribute to the overall qualities of tones (pitch, timbre, integrity), so they are called partials. A partial in itself technically, is an enveloped sinewave. A sinewave is the simplest model of tone, which cannot be decomposed to something simpler and smoother. It sounds dull and resembles to the sound of a tuning fork. An envelope is a contour, tracking the development of frequency and loudness over time. A partials' tracking file is a text file which stores descriptions of these envelopes. It can be generated by, and exported from other computer audio programs, such as AudioSculpt, FHTCore and Ceres3. Unfortunately, neither of those programs can edit them, and here's where SculptView can help. If you take a look at the left image you will see a sonogram showing dark spots in the areas of intense spectral activity of a sound, while the right one shows the lines connecting peaks of spectral activity of the same sound. Those lines can be then exported as partials.


FFT sonogram and partials' tracking of a tabla tone in IRCAM's AudioSculpt

Where's the difference between FFTs and partials?

 F(ast) F(ourier) T(ransform) is a method of analyzing, filtering and resynthesizing spectral contents of a digitally recorded signal. As useful as it is in the field of "artifact-free" sound design (cross-synthesis, de-noising, reverberation, data compression, phase-vocoding etc...), fft files represent raw data of spectral activity (another program which I maintain, Ceres3 also deals with this issue). Being pretty huge and "monotonous",FFT files don't represent a very appealing format for generating computer music scores. One possible remedy to the problem is in trying to abstract the part of information, which does not seem important for a composer, and re-arrange the meaningful data in a more appealing order, as partials. They represent this further level of abstraction: as hierarchically structured text files they posess a rare duality of maintaining an aspect of sound representation, but also contours that could be shaped by means of music composition. This is how a tipical "partials" file looks like:

            ( PARTIALS      4
            ( POINTS     66
               0.023      107.483        4.905
               0.029      106.906        6.393
               0.035      106.892        7.218
                        ...    ...
                        ...    ...
               0.401      161.814      -10.837
            ( POINTS     43
               0.023      317.816       -0.924
               0.029      320.954        0.352
               0.035      322.549        1.272
                        ...    ...
                        ...    ...
               0.267      387.598      -15.703
            ( POINTS     34
               0.023      409.369       -3.463
               0.029      422.257       -2.888
               0.035      427.591       -2.146
                        ...    ...
                        ...    ...
               0.215      484.361      -13.998
            ( POINTS     22
               0.058      226.494       -8.304
               0.064      226.317       -7.738
               0.070      220.751       -5.203
                        ...    ...
                        ...    ...
               0.180      250.804      -4.006
(Dotted lines spare some space for this example - not to write the entire file - which can also be pretty long)
It's actually a LISP list, originally created for export option to IRCAM's PatchWork and OpenMusic. It is an algorithmic composition environment for orchestral and electro-acoustic music. As the file itself looks pretty much like a parameter oscillator bank score file or a visualisation file, it can also be used as such. However, some times editing such text files can also get frustrating and uninspiring, and here is where visualization can help in both understanding what a particular file means, as well as in editing. The same file looks in SculptView pretty much like in the picture, as you run the following command in the shell:

Opening files in SculptView

sculptview TABLA.pt

The file opens in a GUI window as you start the program, you have to give the file name to the program as argument, so it can start. Other arguments are optional. They have to be preceded by a - (minus) sign and they tell the program how the file should be displayed:

  sculptview [infile] -[options]

Navigating the interactive GUI window

Left mouse button moves (repositions) the image in the window.
Right mouse button zooms in and out.
Middle mouse button rotates the image

The window can be also resized (reconfigured) by the window manager (that is dragging, repositioning and resizing the frame around the window. All values and interface parameters will be recomputed automatically.

If you press and hold the control (Ctrl) key and while holding it click the right mouse button, a hierarchical pop-up menu will open showing a number of commands organized into sub-menus:

If you choose Log Freq from the View menu, the display will change into something like this:

The partials will be displayed logarithmically, i.e. vertical intervals among partials will be alike the way they are heared. One can clearly recognize the visual intervals corresponding to an octave, fifth and fourth - fundamental plus first three overtones. Please also note that vertical axe display will radically change, showing nothing between zero-frequency and the lowest frequency in the lowest partial.

Tip: Once you dismiss the menu by raising the mouse button, you have to press the Control key anew before clicking the mouse button again, in order to make the popup menu show. This way you actually activate the invisible window in which the menu shows, so the program does not have to redraw the partials in the main window, each time a menu pops up and down.

Selecting and editing partials

If you choose Breakpoints and Flat from the View menu, the program enters the editing mode. It would be the same as starting the program with the -bfl (l stands for logarithmic view, which is not necessary for entering the edit mode) options from the command line, i.e:

> sculptview TABLA.pt -bfl

The display changes from the perspective view into a two-dimensional orthographic projection, showing the actual breakpoints in small red dots:

If you zoom-in (right mouse button), those dots will grow bigger.

In the edit mode the function of the middle mouse button changes. It no longer rotates the image, but serves as tool for selection and editing.

There are two types of selection for all operations in SculptView:

They serve for different purposes and here is how they work:

By clicking the middle mouse button near the breakpoint it gets yellow-selected. Up to two different points can be selected this way.

By sweeping (dragging) the middle mouse button across a diagonal area, any enclosed breakpoints will get green-selected. As many breakpoints as available can be selected this way: They can be grouped into different areas. As long as you don't deselect (by pressing Delete), previous selections are remembered.

Please observe the diferent color of the breakpoints , with respect to how the selection was made.

You can choose any item from the edit menu to edit partials. However, the program always makes a pre-check to find out if your selection makes sense for the operation you choose to perform, and will warn you through the shell message if not so. In this case, deselect, and consult the Quick Reference paragraph of this help page to find out what went wrong.

Deselecting and extending selections

Pressing the delete key on the keyboard deselects all breakpoints, they change their color back to red.
Only group (green) selections can be extended by using the Select sub-menu items from the Edit menu. Please feel free to explore what each of them does.

Menus and menu items

All menus which include a sub-menu have an arrow pointing to the right next to its name. All menus whose name includes an ellipsis (...) will require you to enter additional information (such as a file name, or a parameter value into the shell from which the program was started. The shell always prompts you about what the program asks for and tells how to do it.



All process commands work only on group (green) selections.

Commands of this menu will let you save your work in either of the following formats:

The program will use floating-point precision oscillator bank synthesizer to synthesize the partials into an AIFF file. As you might know oscillator bank synthesis is very "processor expensive". To make it work "real-time" would imply substantial internal rearranging of analysis data, which would make the program inpractically slow. So it some times works faster, some times slower than real time, depending on the extent of computation it has to perform.

does what it says

Keyboard Reference

Pressing Control makes the right mouse button open and navigate the pop-up menu

Pressing Shift makes the middle mouse button drag individual breakpoints vertically. While holding Shift, sweep with the middle mouse button asross the breakpoint that you would like to drag. As soon as you release the Shift key, the new position is redrawn and frequency information updated. Watch out if you have a mess of breakpoints on the screen before attempting to drag. First zoom in and position the image properly (using right and left mouse buttons), else you might happen to drag a wrong point.

Pressing Delete (not backspace!!) deselects all active selections (individual and groupwise).

Pressing Escape will quit the program, but the shell will ask you to confirm quit before the program exits.


Nothing advanced so far, only basics...

Known Issues and Feedback

1. As OpenGL itself is platform independent, there should be no rendering problems. However, the way how OpenGL interacts with X and the window manager is implementation dependent and may cause both pleasant and unpleasant surprises. Popup menues, which in IRIX use an overlay plane, can behave somewhat odd on Linux boxes using particular graphic cards.

2. In MacOSX, the history of using Apple's native X11, gave poor results. Next implementation will be built on GLUT library which bypasses the X11 and will work natively with Aqua window manager, and started directly from Terminal.app by typing Sculptview file_name.

Our long-term efforts in persuading Apple to write X11 overlay support failed, so the future MacOSX versions won't be source-compatible with the earlier X11 versions.

If you feel like sending your feedback and suggestions, please feel free to do so here


Ministry of Science and Technology of the Republic of Croatia, for project support.
Columbia University Computer Music Center, for facilitaing the LINUX port.

And of course...

Few more screenshots...