Subframe Selector PCL Module

[cameronleger]

Foreword
First, I must thank Mike Schuster for the original version of this fantastic PixInsight Script. Second, of course, the PixInsight team and their continuing open-source initiative, without which this Module would be near impossible to complete. The recent release of 1.8.5 is also worth mentioning because two very important inclusions made this Module significantly easier to make.

I'm sure that most users love the SubframeSelector. It seemed such a worthy item in the pre-processing toolkit that I believed it deserved a more 'standard' method of use that fits inside PixInsight. My primary motivator for this was that Scripts 'block' PixInsight from other tasks. With nearly every use, I singled out a few frames to check out; why are the statistics so different for this frame, and how 'bad' is my worst 'statistically significant' frame? This involved remembering the file name, finding it in a file explorer, and checking it out in another image editor. My secondary motivator was speed. By far this is the slowest part of my pre-processing workflow. Less importantly, I prefer prefixes and this Script only supported postfixes.

Initial Release Notes
This Module has become stable and includes nearly every feature as the SubframeSelector Script. I work in Linux, and while I've provided a Windows build, I've only opened it in Windows to ensure that it loads fine. I do not currently plan on including more features, but I am absolutely welcome to feedback and will continue to develop this as needs arise.

Notable Differences
Of course, this is a native PCL Module instead of a PJSR Script. That alone offers many conveniences, including a huge performance boost. With the addition of threading for the measurement stage, this Module ran 12 frames in the time it takes the original Script to run 2.

The Output Files section is based off the common section between many other PixInsight Modules.

I've ported the recent PJSR StarDetector library to PCL and am using that exclusively instead of the StarAlignment tool. Some of the Star Detector parameters are slightly different because of this.

I've ripped the PSF Fitting portion of DynamicPSF. This plus my port of the StarDetector means this Module is more self-contained and does not call on any other PixInsight Modules or Scripts.

For most measurements, I'm using the Median and Mean Deviation from the Median for dispersion calculations. Star-related paramters, such as FWHM, are now a weighted average of the best-fit stars instead of a simple image-wide average.

The Approval and Weighting expressions are mostly the same, but behind-the-scenes are completely different. I've renamed a few parameters, so be sure to check them if you're copying your existing expressions. These expressions are now run as JavaScript code in the PJSR, thanks to recent updates. This vastly simplified the work involved for parsing expressions. Although I've limited the allowed characters, there are more possibilities with expressions. For example, you can use standard JavaScript functions like 'Math.abs()'.

The Graphs are now a WebView which utilizes the Dygraphs JS library also recently introduced. They are a little more interactive now, and display more information. In lieu of the extra line items in the Measurement Table, the Median and Mean Deviation are displayed on the graph and in tooltips that appear as you hover over points. Subframe Weights are a secondary axis, and the dispersion is displayed with a gradation. Clicking frames still toggles the Approved status, and shift-clicking unlocks the frame.

An additional Graph is also included which shows a histogram of the selected property with a line representing the Empirical Distribution Function. While this graph is not as interactive as the previous, it helps to identify ranges within your distribution of data that are best to include or exclude.

A few items are now placed in a 'Routines' dropdown: Measurement, Output, and Star Detector Preview. First, you must add your frames and measure them. Then, you can use the Output Routine. The Star Detector Routine runs only the Star Detector on the first frame that's supplied, and outputs relevant images for this process and the final structure map used to fit stars against. This helps you when tweaking Star Detector parameters.



To-Do

• Live Monitoring
• Support for DATE-OBS keywords
• Map Outputs (currently, only the Star Detector preview is available)

Release Information
My code is available in my forked branch of the PCL repository: https://github.com/cameronleger/PCL/tree/SubframeSelector
You can download a Linux and Windows build at this releases page of the repository: https://github.com/cameronleger/PCL/releases/tag/01.04.01.0001
OS X 10.12 build provided by Rob: https://drive.google.com/file/d/1xWKzGr4YKXbNaaeui5nH8RZR7olD1bIj/view?usp=sharing

I welcome any and all feedback. Thank you and enjoy!

[Geoff]

Looks good but in my trial case I got completely different results using the script  vs the module.  I am using Win10.
Geoff

[cameronleger]

Hi Geoff,
Thanks for trying this out and providing those screenshots.

For the FWHM and Eccentricity differences, I do expect them but I'd like feedback as to if it's 'better' or not. The original SubframeSelector averages those values for all stars it finds. This does an average too, but it weights them by the MAD of the PSF Fit compared to the best PSF Fit in the image, so that it gives less preference to stars that weren't fit as well. This seemed to be recommended in the PixInsight documentation.

It may also be that the PSF Fitting settings in Star Detector Parameters is different than your setting for the Script. Can you also provide how many stars each version matched?

The SNR Weight appears the same, and I expect the Median and other image-related statistics to be extremely similar since it looks like you're looking at monochrome images. I've seen differences in those numbers myself, but I'm using debayered DSLR images and I suspect that's because the ConvertToGrayscale process that the Script uses comes up with a slightly different result than the getImageIntensity method that I'm using.

[pfile]

i have built this for OSX, but against OSX 10.11 (El Capitan). i am not sure if it would work against 10.12 (Sierra) or 10.13 (High Sierra) but for what it's worth, here it is:

https://drive.google.com/file/d/0B6cW4ae2KyMJcXI5aThGUDZId2s/view?usp=sharing

rob

[avastro]

Looks good too, I've done a comparison, using the same expression, FWHM seem better with PCL.
PC with Win10. I utilize Subframe selector all the time and appreciate the PCL evolution. Thank you for all the contributors.
Antoine

[Juan Conejero]

Hi Cameron,

As it happens every time a developer publishes a new module or script on this forum, you have realized the main reason why I started and have continued my work on the PixInsight project during all of these years. When this happens, the only thing I can say is thank you, so thank you very much for this excellent work, ad welcome to PixInsight development. This module is especially valuable for me because you have shown that all the effort I am putting in version 1.8.5 to strengthen PixInsight as a development platform is worthwhile. So thanks again.

Also as you have noted in your initial post, here we owe our gratitude to Mike Schuster for the SubframeSelector script, which is one of the most useful and beautiful resources available in PixInsight. Thank you so much Mike for making this piece of art possible and available to all PixInsight users.

Needless to say, I want this released as an official module as soon as possible. I have invited you to join our team of contributors to our official GitHub repository. Please submit a pull request to include your code in the PCL master branch. I want to discuss a few things with you (mainly regarding GUI topics and a few items related to high-level parallel processing) but I think the module is basically ready for release.

[dld]

Great news!

Users who take lots of frames with low-end mounts (like myself), or experimenters on lucky imaging using cooled CMOS cameras, should benefit a lot after this development!

I have only one wish; histogram plots or other data exploration plots. So far I plot the results outside of PI in order to judge from the distribution of the measured values where to set an approval/rejection threshold. I am a novice Python/Numpy/Pandas programmer and I had in mind to write a Jupyter Notebook for the task, i.e., importing the SubframeSelector .csv output and do my plots there and get rid of the closed-source tools I use nowadays

Thanks again!

[cameronleger]

Hi Juan,
I'm happy to do this. I'll also look into forking Reference-Documentation and providing proper documentation to the standard of the Script.

dld,
Please, let's discuss more on this. From what you've said, I would think it's already in this Module, because every column of data in the CSV Output is also available as a Graph. Could you give an example of some plots you'd like to see? If there's more meaningful data that can measured and weighted/approved against, I want it! I was unsure if by 'histogram plot' you meant a plot of each histogram of the image channels or histogram as a graph of any numerical data

[dld]

dld,
Please, let's discuss more on this. From what you've said, I would think it's already in this Module, because every column of data in the CSV Output is also available as a Graph. Could you give an example of some plots you'd like to see? If there's more meaningful data that can measured and weighted/approved against, I want it! I was unsure if by 'histogram plot' you meant a plot of each histogram of the image channels or histogram as a graph of any numerical data

A histogram as a graph of any numerical data. Suppose our column data is FWHM. I would be happy to be able to plot a histogram of the FWHM values (example: the first attached plot). In my example I'll approve images with FWHM < 3.0 since images with FWHM > 3.0 lies at the bad "tail" of the distribution.

A rather more complicated plot is the second attachment (scatter_matrix) which (may) combine smoothed histograms (diagonal of the matrix) with scatter plots. This is called a "scatterplot matrix". Such plots allows us to visualize correlations between our variables. For each cell (except the diagonal) we plot the column variable as x and the row variable as y. For example, at the top row the second plot from the left plots Eccentricity (y-value) against FWHM (x-value) . Probably such plots are not that important but may help us 1) find and reject outlier frames (example: sometimes a frame has a low eccentricity value due to passing clouds = low StarSupport and maybe high Median)  2) choose what is the most meaningful combination of variables for an approval formula.

Cumulative probability plots may also be useful (no example attached  :-( ).

[kor]

Wow Cameron!

One of my most important tools just got better!  Thank you.  It used to take about an half and hour to measure my frames.  Now it takes a couple of minutes. 

A couple of suggestions:
1. Add the "Approved # of #" label somewhere--it's convenient to know how many frames pass the Approval expression.

2. Is there any way to add the ability to minimum and maximum on a Weighting symbol.  So something like

Code: [Select]

(FWHM - 3.642) / (8.449 - 3.642) would become something like

Code: [Select]

(FHWM - Math.min(FWHM)) / (Math.max(FWHM) / (Math.min(FWHM))Use case:  I add frames over time and remeasure to see if I have enough "good" ones yet.  When I do, I have to redo a bunch of minimum and maximum values in my Weighting expression.  Not a huge deal, but it would be nice to just let the tool take care of that.

Thanks again - Shane

[dld]

Cameron, I have just installed and run your Module. It runs FAST! Thanks again for your efforts!

[cameronleger]

Shane,
Thank you for the feedback. I was already thinking of doing the first item, and the second item is a good suggestion. I figure I can add a Median, Min, and Max just like the Sigma is currently handled, and that would do what you want I think. At first, I didn't want to implement a 'file cache' feature because of the complexity versus perceived usage of the feature. However, with what you've said and my recent experience with multi-night shoots, I think this would be another great addition.

dld,
That's great news. I also put histograms on the roadmap. I'm still toying with it in my head, but I also think that allowing the choice for the X axis and generating a scatter plot would also handle some of the other plots you have described. I hadn't thought to get that technical with the graphs, but I can see its usefullness now.

[kor]

Cool.  Great idea about the Median, Min, and Max.  I looked through the code today and kind of figured that would be the best way to do it.  My "multi-night" shoots last months and the file cache, if it survives PI shutdown and startup would save a lot of time too.

Once again, thanks for your work on this module.

- Shane

[dld]

Hello Cameron,

Something like this https://en.wikipedia.org/wiki/Empirical_distribution_function  should be useful too. It helps to visualize what is the percentage of images accepted for a given acceptance threshold. I think people doing planetary imaging are using something similar.

Anyway, let's keep it simple My "matrix" example was way too complicated. I am already a happy user And I don't feel comfortable suggesting features while someone else does the hard work

Thanks and clear skies!

[vicent_peris]

Hi,

Congratulations for your new module. I want to add a couple ideas:

- I also think the cumulative probability graph can be very useful to establish a threshold.

- Since this is a PCL module, I think it would be really useful if your tool is able to monitor a directory to analyze newly saved images. To would be open the possibility to monitor in real time the image quality while acquiring data (inside or outside PixInsight).


Best regards,
Vicent.