.: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.
    • For example, if you wish to look at a 5 second period, say 89450 to 89455, then input those into their respective min and max boxes with time selected for the filter.
  • 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.
  • The filter only works for numerical attributes such as time and size.

• 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.
    • NOTE. The buffer view seems to have problems showing the final particles in the pbp file.

• 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.

Editors Notes/Future Update Ideas

• When particle view is toggled to look at buffer view, and you're at the first particles of the file something confusing can happen. You might see what appear to be more particles below the one that's circled and X'd through. Don't worry, those aren't particles that are being skipped. The way that buffer view is set up, is it centers on the current particle, and then it shows the surrounding particles before and after, thus creating the buffer view. When at the start of the file the particle location in the image strip is at or close to 0, which means the index's for the slices below the particle will be negative. In python, negative indices will go to the end of a list or array. To be honest, I'm not really sure if this is a perfectly accurate description, but it's the best reasoning I can come up with for this occurrence.

• It would be great to add support for stereograph data. My current idea is if you have stereographic data, then maybe the program can read in two files as two arguments, and ensure that those two positions are always set as either one is full or both are full. If both are full then it could trigger something in the code to increase the width of the viewer window to accommodate an extra box to show particles or the continuous buffer. This would require an additional function that ensures the two views being shown are actually of the same particle. Maybe this can be done via time comparison and alignment or something, I'm not sure, but I'm guessing this would be a complex problem to solve for a probe like the 2DS based off the few minutes of data that I quickly scrolled through.

• The bufferview needs to be updated to work with the newest version of PIL. It also needs to be updated to show the final particles in a pbp file. I'm also concerned that it might not show all the particles in any current buffer. I haven't noticed any issues with the bulk of the buffers I've looked at so far, so it might be a non issue at the moment unless you need to look at the final few particles, or have a very small sample of data.

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 execute 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.

Q: I got this error: RuntimeError: NetCDF: HDF error

Answer: Solution, wait till SODA is done processing the data and make sure you have permissions to the file. Explanation, I'm not 100% sure, but I believe that this is due to a permissions error, or a result of the file being open/still being written to. If you tried to run the pbp viewer while SODA was still processing the data and generating the netcdf file, then this error is likely to occur. Likewise, if you made a copy of the netcdf file while it was being generated, I've found that that gives me the same error too.

Q: I got this error: An error occurred in Bufferview function: y1 must be greater than or equal to y0

Answer: The most likely issue is discrepancies in the package versions used to develop the program vs the package versions installed in your environment. I will share a list of the package versions below. PIL is the most important one to make sure it matches. I don't think the others will make a program breaking difference, but I listed them just in case. Another potential issue is that the probe doesn't work with the program. I have tested it for HVPS1, HVPS 1995, Hail Spectrometer, HVPS3, and 2DS H and V. The program is set up to work for other probe types, but there's always the possibility that there's a tiny difference I wouldn't have known about that impacts how the code runs.

• netCDF4 - 1.6.2
• numpy - 1.25.0
• tkinter - Python version 3.9.18
• PIL (pillow) - 9.4.0
• sys - Python version 3.9.18
• math - Python version 3.9.18
• time - Python version 3.9.18