Skip to content

frederic-auchere/wow

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

WOW!

Wavelets Optimized Whitening


Installation

Prior to installing WOW, the following packages must be installed from their respective GitHub repositories:

Then, after cloning the present repository:

pip install .

will take care of the other dependencies. Or if you want to be able to edit & develop (requires reloading the package)

pip install -e .

The installation process will create a wow executable that can be run from the command line of the virtual environment (more below):

Usage

The package provides two ways of processing images with the WOW! algorithm:

  • The wow function that can be used in Python programs
  • The wow executable that can be run from the command line

In a Python program

An example is given in the example.py file. In essence:

from astropy.io import fits
from wow import wow

sample_file = r'sample_data\solo_L2_eui-hrieuv174-image_20220317T032000234_V01.fits'
image = fits.getdata(sample_file)

# Basic WOW, non-bilateral, non de-noised. Fast.
wow_image = wow(image)
# Edge-aware, slower
bilateral_wow_image = wow(image, bilateral=1) 
# Same with de-noising
denoised_bilateral_wow_image = wow(image, denoise_coefficients=[5, 1], bilateral=1)  

The wow executable

The wow executable can be called from the command line to produce movies from a sequence of files, directories or glob patterns. Help on the available parameters can be obtained with

wow --help

usage: WOW! [-h] (--source SOURCE | --selektor Selektor query [Selektor query ...] | --ascii Input ASCII file) [-o OUTPUT] [-d DENOISE [DENOISE ...]] [-w WEIGHTS [WEIGHTS ...]] [-nb] [-ns N_SCALES] [-gw GAMMA_WEIGHT] [-g GAMMA]
            [-nw] [-t] [-roi ROI ROI ROI ROI] [-r REGISTER] [-nu] [-cs] [-ne] [-c] [-fps FRAME_RATE] [-crf CRF] [-np N_PROCS] [-nc] [-nl] [-fn FIRST_N] [-i INTERVAL INTERVAL] [-rb REBIN] [-rt ROTATE] [-tf]

Processes a sequence of files with Wavelets Optimized Whitening and encodes the frames to video.

optusage: WOW! [-h] (--source SOURCE | --selektor Selektor query [Selektor query ...] | --ascii Input ASCII file) [-o OUTPUT] [-d DENOISE [DENOISE ...]]
            [-w WEIGHTS [WEIGHTS ...]] [-nb] [-ns N_SCALES] [-gw GAMMA_WEIGHT] [-g GAMMA] [-nw] [-t] [-roi ROI ROI ROI ROI] [-r REGISTER] [-nu] [-cs] [-ne] [-c]
            [-fps FRAME_RATE] [-crf CRF] [-np N_PROCS] [-nc] [-nl] [-fn FIRST_N] [-i INTERVAL INTERVAL] [-im INTERVAL_MARGIN] [-rb REBIN] [-rt ROTATE] [-tf]

Processes a sequence of files with Wavelets Optimized Whitening and encodes the frames to video.

optional arguments:
  -h, --help            show this help message and exit
  --source SOURCE       List of files, directories or glob patterns
  --selektor Selektor query [Selektor query ...]
                        Queries Selektor for EUI observations
  --ascii Input ASCII file
                        ASCII file containing list of input files
  -o OUTPUT, --output OUTPUT
                        Output filename. Frames are saved in its base directory.
  -d DENOISE [DENOISE ...], --denoise DENOISE [DENOISE ...]
                        De-noising coefficients
  -w WEIGHTS [WEIGHTS ...], --weights WEIGHTS [WEIGHTS ...]
                        Synthesis weights
  -nb, --no_bilateral   Do not use edge-aware (bilateral) transform
  -ns N_SCALES, --n_scales N_SCALES
                        Number of wavelet scales
  -gw GAMMA_WEIGHT, --gamma_weight GAMMA_WEIGHT
                        Weight of gamma-stretched image
  -g GAMMA, --gamma GAMMA
                        Gamma exponent
  -nw, --no_whitening   Do not apply whitening (WOW!)
  -t, --temporal        Applies temporal de-noising and/or whitening
  -roi ROI ROI ROI ROI  Region of interest [bottom left, top right corners]
  -r REGISTER, --register REGISTER
                        Order of polynomial used to fit the header data to register the frames.
  -nu, --north_up       Rotate images north up
  -cs, --center_sun     Center solar disk
  -ne, --no_encode      Do not encode the frames to video
  -c, --cleanup         Cleanup frames after encoding
  -fps FRAME_RATE, --frame-rate FRAME_RATE
                        Number of frames per second
  -crf CRF              FFmpeg crf quality parameter
  -np N_PROCS, --n_procs N_PROCS
                        Number of processors to use. By default, uses 1 or the maximum available -1
  -nc, --no-clock       Do not inset clock
  -nl, --no-label       Do not inset time stamp & label
  -fn FIRST_N, --first_n FIRST_N
                        Process only the first N frames
  -i INTERVAL INTERVAL, --interval INTERVAL INTERVAL
                        Percentile to use for scaling
  -im INTERVAL_MARGIN, --interval_margin INTERVAL_MARGIN
                        Factor applied to interval top boundary
  -rb REBIN, --rebin REBIN
                        binning factor
  -rt ROTATE, --rotate ROTATE
                        Counter-clockwise 90 / 180 / 270° rotation
  -tf, --to_fits        Save to fits

Movie from images in a directory

All images in the my/directory folder

wow --source my/directory -o movie.mp4

Only some files

wow --source my/directory/*20221002*.fits -o movie.mp4

Using Selektor queries

eui_selektor_client is a lightweight client to the EUI Selektor tool (password protected). The query passed as value to the --selektor argument must be of the form --selektor parameter1:value1 parameter2:value2. The most useful query parameters and possible values are summarized below. Note that some parameters do require the [ ] brackets, e.g. detector[]:FSI

Parameter Possible values FITS keyword
level[] 'L0', 'L1' LEVEL
image_size_min 320-3072 NAXIS1=NAXIS2
image_size_max 320-3072 NAXIS1=NAXIS2
binning[] 1, 2, 4 BINNING
detector[] 'FSI', 'HRI_EUV', 'HRI_LYA' DETECTOR
wavelnth[] '174', '304', '1216' WAVELNTH
recstate[] 'on', 'off' RECSTATE
compress[] 'Lossless', 'Lossy-high quality', 'Lossy-strong', 'Lossy-extreme', 'None' COMPRES
gaincomb[] 'low-only', 'high-only', 'combined', 'both', 'other' GAINCOMB
imgtype[] 'solar image', 'LED image', 'dark image', 'occulted image' IMGTYPE
xposure_min 0-7200 XPOSURE
xposure_max 0-7200 XPOSURE
date_begin_start YYYY-MM-DD DATE-BEG
date_begin_start_hour 0-23 DATE-BEG
date_begin_start_minute 0-59 DATE-BEG
date_begin_end YYYY-MM-DD DATE-BEG
date_begin_end_hour 0-23 DATE-BEG
date_begin_end_minute 0-59 DATE-BEG

Note that the DATE-BEG FITS keyword indicates the beginning of an exposure. The start and end suffixes are added to date_begin to form the date_begin_start and date_begin_end parameters, which can be confusing.

When passed the -- selektor [query] option, the wow executable uses Selektor's filtering capability to obtain, e.g. a list of FSI 174 image between two given dates, while excluding too short exposure times. Note that eui_selektor_client queries the EUI archive but does not download the data itself. It is up to the user to make sure that the data is available in a directory tree organized by YYYY/MM/DD. An environment variable named EUI_ARCHIVE_DATA_PATH must point at the root of the data tree. For example, the file solo_L1_eui-hrieuv174-image_20220317T032000234_V01.fits must be located in the EUI_ARCHIVE_DATA_PATH/L1/2022/03/17 directory:

EUI_ARCHIVE_DATA_PATH
├─ L1
│  ├─ 2022/
│  │  ├─ 03
│  │  │  ├─ 17
│  │  │  │  ├─ solo_L1_eui-hrieuv174-image_20220317T032000234_V01.fits

From an ASCII file

A movie can be assembled from a list of file stored as individual lines in an ascii file. Full paths must be provided.

wow --ascii file.txt -o movie.mp4

Examples

Queries selektor to create a video file in the movie directory from all the FSI 304 images from 2022-10-01 to 2022-10-30, excluding exposures shorter than 1 second (note that 2022-10-30 means 2022-10-30T00:00:00):

wow --selektor detector[]:FSI wavelnth[]:304 date_begin_start:2022-10-01 date_begin_end:2022-10-30 image_size_min:3072 xposure_min:1 -o movie.mp4

Use the HRI_EUV data from 2022-10-19T00:00:00 to 2022-10-19T19:00:00, excluding exposures shorter than 1 second:

wow --selektor detector[]:HRI_EUV date_begin_start:2022-10-19 date_begin_end:2022-10-19 date_begin_end_hour:19 xposure_min:1 -o output/movie.mp4

References

Auchère, F., Soubrié, E., Pelouze, G. and Buchlin, É. 2022, Image Enhancement With Wavelets Optimized Whitening, A&A, 670, id.A66

About

Wavelets Enhanced Whitening (WOW!) utilies

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages