IWaVE - Image Wave Velocimetry Estimation

IWaVE Image Wave Velocimetry Estimation This library performs simultaneous analysis of 2D velocimetry and depth in lakes, coastlines, estuaries and rivers with highly complex bathymetric and wave dynamics through 2D Fourier transform methods using a physics-based approach. Unlike existing velocimetry approaches such as Particle Image Velocimetry or Space-Time Image Velocimetry, the uniqueness of this approach lies in the following: velocities that are advective of nature, can be distinguished from other wave forms such as wind waves. This makes the approach particularly useful in estuaries or river stretches affected strongly by wind, or in shallow streams in the presence of standing waves. The velocity is estimated based on the physical behavior of the water surface, taking into account the speed of propagation of waves and ripples relative to the main flow. This makes the approach more robust than traditional methods when there are no visible tracers. If the depth is not known, it can be estimated along with the optimization of x and y-directional velocity. Depth estimations are reliable only in fast and shallow flows, where wave dynamics are significantly affected by the finite depth. Purpose The code is meant to offer an Application Programming Interface (API) for use within more high level applications that utilize the method in conjunction with more high level functionalities such as Graphical User Interfaces, dashboards, or automization routines. The source code is available at https://github.com/DataForWater/IWaVE The background and validation of methods are outlined and demonstrated in: Dolcetti, G., Hortobágyi, B., Perks, M., Tait, S. J. & Dervilis, N. (2022). Using non-contact measurement of water surface dynamics to estimate water discharge. Water Resources Research, 58(9), e2022WR032829. https://doi.org/10.1029/2022WR032829 Examples and prospects of this approach are described in a recent HydroLink article, see https://www.iahr.org/library/infor?pid=40120 The code has been based on the original kOmega Matlab code developed by Giulio Dolcetti (University of Trento, Italy) and released on https://doi.org/10.5281/zenodo.7998891 The API of the code can: ingest a set of frames or frames taken from a video Slice these into "interrogation window" for which x- and y-directional velocities must be estimated Analyze advective velocities per interrogation window using the spectral analysis. Additionally estimate the water depth if unknown. Note The sensitivity of water surface dynamics to variations in water depth is minimal. Depth estimations have specific requirements (see below) and can be prone to significant errors. Do not rely on depth estimates for any activity that could pose a risk. Installation To install IWaVE, set up a python (virtual) environment and follow the instructions below: For a direct installation of the latest release, please activate your environment if needed, and type pip install iwave If you want to run the examples, you will need some extra dependencies. You can install these with pip install iwave[extra] This sets you up with ability to retrieve a sample video, read video frames, and make plots. Examples The main functionality is disclosed via an API class IWaVE. Creating an IWaVE instance To create an IWaVE instance, you typically start with some settings for deriving analysis windows and from iwave import Iwave # Initialize IWaVE object iw = Iwave( resolution=0.01, window_size=(64, 64), # size of interrogation windows over which velocities are estimated overlap=(32, 32), # overlap in space (y, x) used to select windows from images or frames time_size=250, # amount of frames in time used for one spectral analysis time_overlap=125, # amount of overlap in frames, used to establish time slices. Selecting half of # time_size implies that you use a 50% overlap in time between frame sets. ) # print some information about the IWaVE instance print(iw) Initializing a IWaVE instance is done by only setting some parameters for the analysis. At this stage we have not loaded any video in memory yet. The inputs have the following meaning: window_size: the size of so-called "interrogation windows" as a tuple (y, x), i.e. slices of pixels from the original frames that the images are subdivided in. Advective velocities are estimated per interrogation window by fitting a spectral model over space and time within an interrogation window. overlap: overlaps between the interrogation window. (64, 64) here means that an overlap of 50% in both directions is applied. time_size: a spectral model is fitted over several subsets of frames and then averaged. This reduces noise. You can define how large slices are. If you for instance read 300 frames, and use a time_size of 100, 3 subsets of 100 frames are derived, and the spectral model is fitted for all three and then averaged. time_overlap: also for the time, overlap can be used, in the same manner as for spatial overlap using overlap. Note Some important remarks on uncertainties: IWaVE employs a spectral approach to compare the observed water surface dynamics with the theoretical expectations for given flow conditions. The key parameters determining the uncertainty of measurements are the spectral resolution, the number of averages, and the sensitivity of surface dynamics to velocity and water depth (see Dolcetti et al., 2022). The spectral resolution improves by increasing the window size and/or the time size. Optimal values of window_size should be similar to the water depth or larger. time_size should be larger than 5 seconds in most applications, ideally around 10 seconds. The spatial and temporal resolution of the videos (e.g., the pixel size and frame rate) are less critical than the spectral resolution for the accuracy of the estimates. Reasonable results can usually be obtained also with a pixel size of ~5 cm and a frame rate of ~10 fps. Consider downsampling the data if memory or computational time are an issue. More averages can significantly improve the convergence of the method. Ideally, one should aim for at least 3 independent slices, regardless of the overlap (e.g., a 30-seconds-long video with a time_size of 10 seconds). Short waves are more sensitive to flow velocity, while long waves are more sensitive to water depth. Therefore, a better spatial resolution (smaller pixel size) can improve velocity estimates, while a better spatial resolution (larger window size) can improve the depth estimates. However, only the waves with a wavelength similar or larger than the water depth feel the presence of the bed and can be used to estimate the water depth. Typically, these long waves form naturally in flows with Froude number in the range 0.4 to 1.0. These long waves (wavelength ~ 2πF2d with d being the depth, must be visible and their wavelength must be smaller than the window size for the depth estimation to be accurate. Otherwise, depth estimates may fail completely due to lack of sensitivity. Reading in a video import matplotlib.pyplot as plt import numpy as np from matplotlib import patches from iwave import Iwave, sample_data iw = Iwave( resolution=0.01, # resolution of videos you will analyze in meters. window_size=(64, 64), # size of interrogation windows over which velocities are estimated overlap=(32, 32), # overlap in space (y, x) used to select windows from images or frames time_size=250, # amount of frames used for one spectral analysis time_overlap=125, # amount of overlap in frames, used to establish time slices. Selecting half of # time_size implies that you use a 50% overlap in time between frame sets. ) # retrieve a sample video from zenodo. This is built-in sample functionality... fn_video = sample_data.get_sheaf_dataset() iw.read_video(fn_video, start_frame=0, end_frame=500) # NOTE: you can also read a list of ordered images with the frames per second set, using iw.read_imgs([...], fps=...) print(iw) # show the shape of the read images print(f"Shape of the available images is {iw.imgs.shape}") # show the shape of the manipulated windows print(f"Shape of the available images is {iw.windows.shape}") # create a new figure with two subplots in one row f, axs = plt.subplots(nrows=1, ncols=2, figsize=(16, 7)) # plot the first image with a patch at the first window and centers of rest in the first axes instance first_window = patches.Rectangle((0, 0), 128, 128, linewidth=1, edgecolor='r', facecolor='none', label="first window") xi, yi = np.meshgrid(iw.x, iw.y) axs[0].imshow(iw.imgs[0], cmap="Greys_r") axs[0].add_patch(first_window) axs[0].plot(xi.flatten(), yi.flatten(), "o", label="centers") axs[0].legend() axs[0].set_title("First frame overview") # plot the first window of the first image in the second axes instance axs[1].imshow(iw.windows[0][0], cmap="Greys_r") axs[1].set_title("First frame zoom first window") plt.show() You can now see that the IWaVE object shows: how many frames are available (if the video is shorter than start_frame and end_frame dictate, you'll get lessframes) how many time slices are expected from the amount of frames (overlap is included in this) The dimensions of the windows The y- and x-axis expected from the velocimetry analysis. You can also see that the frames have actually been read into memory and windowed into a shape that has the following dimensions (in order): amount of windows amount of frames amount of y-pixels per window amount of x-pixels per window Important to note is that the plotted first window on the right is normalized in time by subtracting for each pixel and time step the temporal mean of that pixel. This is meant to reduce background noise. You may also normalize in space by passing norm="xy" during the initialization of the IWaVE instance. In this case, the mean of all pixels in a window is