.:pbp viewer:home

pbp_viewer Graphical Plotting Program

Purpose of Program

This program was developed to view and analyze individual particle images produced by airborne probes. This program can theoretically work for any group of particle images as long as the particle file is in a format readable by the program.

Setup

This program can be accessed via ADPAA, or a copy of the program with premade data lives in this google drive folder https://drive.google.com/drive/folders/1rG3g118HKXCl6g-kCSiHVouZYGq4-ZJS?usp=sharing. The google drive folder may not be consistently updated, so if possible, it's best to access the program through ADPAA so you have access to the most recent version.

To download ADPAA, go to https://sourceforge.net/projects/adpaa/files/. Instructions to set it up are included in the installation (I think, I need to check).

Another important program for the PBP_Viewer is the System for Optical Array Probe Data Analysis (SODA). SODA produces the particle-by-particle files that the PBP_Viewer uses. Expansions to other particle-by-particle file types has not been developed. To download SODA, go to https://github.com/abansemer/soda2. When creating the particle-by-particle file using SODA, make sure to select both the PBP(netCDF) box and the Images(netCDF) box. The "PBP" box creates all the particle attributes, and the "Images" box creates the information needed for individual image files.

Getting Started

The program can be started multiple ways,

• From an IDE such as Spyder, use the command runfile() in the console panel. E.g. runfile('PBP_Viewer.py', '06222000_232921_HVPS1.pbp.nc')
• The program can also be run from the command line using python,
  • If in a directory with the pbp_viewer program file and data file, then you can use ./PBP_Viewer.py 06222000_232921_HVPS1.pbp.nc or python3 PBP_Viewer.py 06222000_232921_HVPS1.pbp.nc
  • If ADPAA is installed, you don't need the ./ or python3. The command would look like pbp_viewer.py 06222000_232921_HVPS1.pbp.nc

Once the program is open, you'll see multiple sections to the gui,

How to Use the GUI

• The big box on the left is where the particle images are displayed.
• To scroll through images, use the ">>" to move to the next particle and the "<<" button to go to the previous particle.
• The three dropdown boxes on the right show the particle attributes. To change which attributes are selected, click on the arrow in a dropdown box and scroll until you see the attribute you want displayed and click on it.

• The box in the top right of the window is the particle sorter.
  • It should be turned off by default and will show "Disabled." This is because the particle sorter still has a bug in it. Sometimes it incorrectly writes new data. This can impact analysis of the data if it incorrectly writes data for important particles. A fix is in progress, but in the meantime it does work if used following strict rules. The particle sorter allows you to manually create attributes to add to the particles. Once opened, there are multiple things you can do,
  • add row: When clicked, it will add a row for a new particle category. There is an entry box to add a category name to. The remove and add buttons count down and up, respectively. The initialized 0 will change when these buttons are clicked. The program only allows a 0, 1, and 2. 0 means that the particle is uncategorized. 1 means that the particle is true for the category. 2 means that the particle is false for the category. Up to five rows can be added.
  • Loading and Saving Categories: When clicked, the options for saving and loading the categories pop up. Note that this program works with a max of five additional categories.
    • To add new categories to the particle-by-particle file, select the "Save Category Names" option. This will initialize the category name in the particle-by-particle file and fill the category with a 0 for every particle.
    • To load categories that have already been generated, select the "Load Category Names" option. This will automatically add the rows and fill them in with the category name and the current particle's data (There is an error where the current particle on the screen will be overwritten with 0's for the categories. This will mess up the categorization for the current particle.)
  • Toggle Bindings: This turns off the entry boxes with the category names so they can't be typed in, and binds the "12345" and "qwert" keys to the particle sorter. "12345" are linked to the "add" button, and "qwert" are linked to the remove button.
    • Note that typing "12345" or "qwert" in any of the other entry while "Toggle Bindings" is on will erroneously count up or down in the particle sorter.

Additional Actions

Additional actions are located in "File/Commands" in the top left of the window.

• Filters
  • This will open a new window. Make sure you leave this window open. Here you can select,
    • What attribute to filter by, and
    • The minimum and maximum threshold for the filter. If no value is put in the minimum or maximum box, they will default to 0 and 99999, respectively.
  • Once a filter is applied, the program will remember it. If you wish to add another filter, just select a new option from the dropdown box and adjust the thresholds as necessary. To remove a filter, make sure the right option is selected, and click the remove filter button.

• Convert Units
  • Here you can convert time and diameter units.
  • This window can be closed when you're done with it.
  • The program defaults to seconds and micrometers.
  • Once you've selected a unit to convert to, click forward or backward, and the GUI will update and show all time and/or diameters in the new unit.

• Toggle Particle View
  • The program shows individual particles and their pixel size by default.
  • When selected, this will change to a view of the buffer.
    • The buffer view will draw an X and an open circle through the particle in focus. The preceding and following six particles have a lightly shaded circle drawn around them.

• Toggle Grid View
  • When selected, it will turn the grid showing the pixel size off/on

• Toggle Arrow Keys
  • When selected, it will enable the left and right arrow keys to scroll through the particles in addition to the "<<" and ">>" buttons.

Frequently Asked Questions (FAQ)

Q: How do you ensure that SODA2 adds images to the netcdf file used by pbp_viewer?

Answer: Click on the option to generate a PBP(netCDF) box and the Images(netCDF)

Q: I downloaded the pbp_viewer file but it won't run?

Answer: Make sure all the spelling is correct. If the issue persists, try both the ./ and python3 method to run the file. If the issue still persists, type "ls -l" in the directory with the files and verify if the file has excute permissions (an x in the -rwxrwxrwx). If an x isn't there, the use chmod +x PBP_Viewer.py (or whatever the name is if you changed it).

Q: The program looks weird. Why?

Answer: I finished setting up the locations and sizes of everything in the gui on my windows laptop. If running from a linux machine, the graphics are altered a bit and everything is less nicely organized. I'm working on a fix for that.