Navigating the GUI - gammaspire/midichlorians GitHub Wiki

Editor's Note

So, you have successfully executed the main script and opened the GUI. I heartily applaud this fruit of your efforts. Let us now proceed to understanding the various widgets and trinkets of the interface.

1. Loading a FITS file

If sonification is to be done, the user must upload a FITS file.

The "File Browser" frame is located at the top right of the GUI. You can either type the path to the galaxy FITS image, or you can click the "Browse Image" button. Doing so will open a browsing window, where you can select your desired FITS image and click "Open." The window should then close and the full path to your image will display in the frame's textbox. Optionally, the user can also insert a corresponding mask image for the galaxy, with the covered pixels being omitted from the sonification process. Click "Browse Mask" and use the browsing window to navigate to your FITS mask, then click "Open." (NOTE: if at any point you would like to visually confirm that any given set of pixels are masked, you can check the "Show/Hide Mask" box, found in the centrally located "Change Display" widget

The "Load/Refresh Canvas" button underneath has two functions, the first being to load your FITS image into the main display canvas. The second function is more of a failsafe -- if any glitches transpire while utilizing the drawing tools, then you may click this button in order to clear the canvas of your scribbles and refresh the FITS image.

If the display's colormap and/or stretch is not to your liking, there is no need to fret! You might use the vmin, vmax sliders and colormap dropdown menu options in the appropriate frame located around the center of the GUI. Upon selecting any colorscale or sliding the scale any which way, the canvas will automatically update.

NOTE: One built-in feature for the stretch to display nicely is through the use of the object mask (which will cause the program to ignore regions with prominent foreground stars and other undesirable artifacts, thereby stretching the colors ONLY according to the pixel values in the central galaxy). If you have an object mask you would like to incorporate, (1) be sure that the mask FITS file is in the same directory as your image and (2) have both the galaxyname, the wavelength band, and the word "mask" in the filename, separated by -. An example would be [UGC11132-wise-mask.fits], without the brackets. Current support is only for 'wise' (which applies to W1, W2, W3, W4) and grz (type 'g', 'r', or 'z' in place of 'wise') bands! Otherwise, you can proceed as normal and simply use the vmin, vmax scrollbars.

2. Selecting a Sonification Region

Your galaxy might not occupy the entirety of the cutout; rather, it may be placed centrally with about 50+ bumper pixels of background space around the perimeter. What if you don't want to sonify these non-galaxy pixels? Or what if there is a particularly nifty foreground star or non-central galaxy in this bumper space that you'd like to try sonifying instead?

Well, do I have the solution for you.

Once you have successfully loaded your galaxy FITS image onto the canvas, you can left-click in two different spots on the image in order to create a rectangle. The idea is that each click will represent the location of one of the two opposing vertices. When you have clicked twice, assuming the x- and y- values are different, lines will automatically form to create a rectangle. If you click a third time, the rectangle will disappear and this location will mark the new first vertex of your next rectangle. I recommend experimenting a bit until you are familiar with the mechanics of such complex 2D geometry.

If you have found a rectangle enclosing the desired object to sonify, you can proceed in a few ways:

  1. Use the "Change Rectangle Angle widget" to rotate the rectangle in a way that might better accommodate the position angle (and perhaps the axis ratio) of your object.

  2. Tweak some of the parameters (in the aptly-labeled "Parameters" frame) to your liking.

Then, if you are all set, navigate to the "Parameters" frame and click "Sonify." If all python libraries are correctly installed with the correct versions, you should automatically begin to hear the MIDI file begin to play.

The default direction of the pixel strips is from left to right, so the notes played will also go from the left of the galaxy to the right. These strips are 1D pixel arrays spanning the height of the rectangle, with as many strips as there are pixels spanning the rectangle's length. The code then calculates the mean pixel value of these strips, and places them in a new array to be mapped onto MIDI notes (and eventually a key signature).

Once the user clicks "Sonify," a real-time sweeping animation of a line passing through the rectangle in synchrony with the notes being played will occur. There is also a checkbox feature which allows the user to listen to a single note corresponding to a single line of pixels within this rectangle. If you check the box located below the galaxy display and then left-click within the rectangle you drew on the canvas, you will plot a single line and hear its corresponding MIDI note. Note that you MUST have clicked the "Sonify" button first in order to both create and listen to the lines.

Troubleshooting Tips

  • If you would like to change the rectangle but only seem to be able to create lines, that would be because you must uncheck the "Switch to lines" checkbox. The left-click setting within the canvas will then revert to the rectangle fun with which you started.
  • If you would like to change a certain parameter but not the rectangle, you need only to insert the desired parameter value in the companion textbox and click "Sonify" again.
  • If you have encountered a problem where certain red marks or lines on the canvas are not disappearing, you can click the "Enter/Refresh" button located in the "File Browser" widget to re-load the FITS image.

3. Sonification parameters

There is an array of options that will manipulate your sonification file, primarily for aesthetics but also to potentially magnify on subtleties in your galaxy's structure. Note this second rule more applies to those who are using well-resolved images, as such structures are sparse for all but the most luminous galactic behemoths of the cosmos -- there is no use seeking spiral arms or bars in galaxies resembling pudgy little fuzzballs, like a limbless Ewok.

In the "Parameters" frame, you will find the following:

  1. Note Inversion: Do you prefer the lowest notes to correspond to the highest pixel values, and vise versa? If so, then check this box to change the default high-to-high and low-to-low scheme.

  2. yscale: A parameter which scales the midi notes; affects how quickly or slowly note changes occur. For instance, if 10 is C, will 14 be D or E? Or F?! Or just C? The note assignment goes like note = (normalized mean flux)$^{yscale}$.

  3. Min, Max Velocity: The minimum and maximum volume, respectively, of notes. The lowest minimum is 0 (no sound), and the highest maximum is 127 (loud, powerful, punctuating).

  4. BPM: Beats per minute; affects the tempo of sound, or the amount of time between two successive notes.

  5. xmin, xmax: This textbox will just display the range of x-values which the program is sonifying. If you draw a rectangle from x=10 to x=40, then those min and max x-values will show in this here box. Trying to type new inputs will do na-da.

  6. Key Signature: Sort of self-explanatory. For the unaffiliated (e.g., me), signatures effectively dictate what notes are played. Some might include F, others F#, etc.

  7. Instrument: Each integer, 0-127, represents an instrument! The current soundfont I have pre-loaded is from the line of Pokemon Gameboy Advance titles, but you (the user) are welcome to apply any soundfont desired. Just be sure to specify the filename and path in the params.txt file.

  8. Duration: The duration, in seconds, that a note is played. If BPM is relatively high, then this will cause the notes to overlap, resulting in either cacophony or a marginally more amusing sound. I recommend shortening the duration if the notes merge together and become utterly unrecognizable as individual entities. Independence is a rare commodity in these times, and your music will thank you for the gesture of mercy.

4. Generating a WAV File

If you have not yet converted galaxy data to sound by clicking the "Sonify" widget, please refer to the above for instructions. Otherwise, the following ought to be relatively uninvolved...

In fact, you need only press a button!

What that button does, though, requires a brief discussion. Once you click the "Save as WAV" button, located around the upper-center of the GUI, your most recent sonification MIDI file will be converted to a WAV file. This process incorporates your soundfont (e.g., I use pkmngba.sf2), so the output may not sound identical to the MIDI notes played upon clicking "Sonify" in terms of instrument choice.

This .wav file, along with the companion .mid file, will appear in the "saved_wavfiles" directory which is part of the git pull package. The filename is a bit tricky. The current naming convention I use for FITS files is such that the galaxy name appears first, followed by a -, followed by the wavelength band, followed by a -, followed by some additional information. The code will parse the filename with the - as a delimiter, so I assign the first two elements, the galaxy name and band, to be part of the saved .wav name. DEPENDING ON YOUR FILENAMING CONVENTION, your saved filenames might not be informative.

5. Generating an MP4 File

Follow the same general procedure as with saving a .wav file. The output will be a .mp4 with a few components: the upper panel will show the MIDI notes to be played, with a red highlighting circle tracing each note as it is played; while the bottom panel, displaying the original image, will have a sweeping bar tracing the sonified region in sync with the highlighted circle. This tracing should then be approximately calibrated with the audio overlay. A *concat.mp4 file comprising this composition will appear in the relevant folder (which is set up by default to be in the same directory as the collection of heehaw that you git pulled from my repository).

I provide an example screenshot below of galaxy VFID6593 from our Virgo Filament Survey.