ShoreScan Package

class c_Datastore.ImageDatastore(root_folder=None)[source]

Bases: object

A class to manage and process image data stored in a hierarchical folder structure.

This class handles storing metadata for images in a nested dictionary structure, allows for image selection, loading, and organizing images based on metadata, and provides methods for filtering and plotting images.

images

A nested dictionary structure storing image metadata.

Type:

dict

camera_sites

A dictionary mapping sites to their associated cameras.

Type:

dict

copy_images_to_folder(destination_folder=None, hierarchical=False)[source]

Copies all images from the datastore to the specified destination folder.

Parameters:

• destination_folder – (str, optional) The path to the destination folder where images will be copied. If None, uses the original directory.

• hierarchical – (bool) If True, organizes images into subfolders by site, camera, year, month, and image type. If False, all images are copied to a single folder.

Raises:

ValueError – If the destination folder is not specified or invalid (when not saving to the original folder).

filter_black_images(threshold=50, image_type=None)[source]

Remove images from the datastore that are too dark.

Parameters:

• threshold – (int) The brightness threshold below which images are considered “too dark”.

• image_type – (str, optional) If specified, only filter images of this type (e.g., ‘bright’, ‘snap’).

Returns:

(list) A list of metadata for the removed images.

filter_blurry_images(blur_thresholds=None, image_type=None)[source]

Remove blurry images from the datastore.

Parameters:

• blur_thresholds – (dict, optional) A dictionary where keys are image types (e.g., ‘bright’, ‘snap’) and values are the Laplacian variance thresholds below which images are considered blurry. If not provided, the default threshold will be used.

• image_type – (str, optional) If specified, only filter images of this type (e.g., ‘bright’, ‘snap’).

Returns:

(list) A list of metadata for the removed images.

filter_sun_glare(threshold=30, image_type=None, csv_file='camera_sites.csv')[source]

Check for potential sun glare in images.

Parameters:

• threshold – (int) The angle in degrees above which the image will be considered to have sun glare.

• image_type – (str, optional) If specified, only check images of this type (e.g., ‘bright’, ‘snap’).

• csv_file – (str) The path to the CSV file containing camera site data.

Returns:

(list) A list of metadata for the removed images.

filter_white_images(threshold=200, image_type=None)[source]

Remove images from the datastore that are too bright.

Parameters:

• threshold – (int) The brightness threshold above which images are considered “too bright”.

• image_type – (str, optional) If specified, only filter images of this type (e.g., ‘bright’, ‘snap’).

Returns:

(list) A list of metadata for the removed images.

get_image_metadata_by_type(image_types, site=None, camera=None)[source]

Extract metadata for all specified image types, optionally filtering by site and camera.

Parameters:

• image_types – (list) A list of image types (e.g., [‘bright’, ‘snap’]).

• site – (str, optional) The site to filter by. If not provided, all sites are considered.

• camera – (str, optional) The camera to filter by. If not provided, all cameras are considered.

Returns:

(list) A list of metadata dictionaries for the specified image types, site, and camera.

image_stats()[source]

Displays statistics about the images stored in the datastore.

Returns:

None

list_images(site=None, camera=None, year=None, month=None)[source]

Lists images optionally filtered by site, camera, year, and month.

Parameters:

• site – (str, optional) The site identifier to filter by.

• camera – (str, optional) The camera identifier to filter by.

• year – (str, optional) The year to filter by.

• month – (str, optional) The month to filter by.

Returns:

(dict) A filtered list of images.

load_camera_sites(csv_file='camera_sites.csv')[source]

Load camera sites data (lat, lon, and camera angle) from a CSV file.

Parameters:

csv_file – (str, optional) The path to the CSV file containing camera site data.

Returns:

dict: (dict) A dictionary with site names as keys and tuples (lat, lon, camera_angle) as values.

Raises:

ValueError – If the data in the CSV file is invalid or incomplete.

load_images()[source]

Loads images from the root folder and stores metadata in the images attribute.

This method parses the filenames and stores metadata such as timestamp, site, camera, and image type.

Raises:

ValueError – If a file does not conform to the expected format.

plot_image(image_metadata)[source]

Plot a single image using its metadata dictionary.

Parameters:

image_metadata – (dict) A dictionary containing the image’s metadata.

static select_folder()[source]

Opens a dialog to select a folder and returns the selected path.

Returns:

(str) The path to the selected folder.

Raises:

RuntimeError – If folder selection fails.

class c_Datastore.ShorelineDatastore[source]

Bases: object

A class to manage shoreline data using a nested dictionary structure.

This class supports hierarchical storage, retrieval, and export of shoreline results including error metrics.

results

A nested dictionary to store shoreline-related data.

Type:

defaultdict

get_shoreline_coords(site, camera, year, month, day, time, image_type)[source]

Retrieve all filtered bottom boundaries for a given image.

Parameters:

• site – (str) The site identifier.

• camera – (str) The camera identifier.

• year – (str) The year of the image.

• month – (str) The month of the image.

• day – (str) The day of the image.

• time – (str) The time of the image.

• image_type – (str) The type of the image (e.g., ‘bright’).

Returns:

(list) A list of all shoreline coords for the given image.

get_shoreline_results(site, camera, year, month, day, time, image_type)[source]

Retrieve the stored results for a given image.

Parameters:

• site – (str) The site identifier.

• camera – (str) The camera identifier.

• year – (str) The year of the image.

• month – (str) The month of the image.

• day – (str) The day of the image.

• time – (str) The time of the image.

• image_type – (str) The type of the image (e.g., ‘bright’).

Returns:

(dict) A dictionary containing the shoreline coords, bottom boundary, watershed coords, y-distance, and RMSE values.

save_shoreline_coords_to_file(site, camera, year, month, day, time, image_type, output_folder='output')[source]

Save shoreline_coords to a text file with a name based on the dictionary keys.

Parameters:

• site – (str) The site identifier.

• camera – (str) The camera identifier.

• year – (str) The year of the image.

• month – (str) The month of the image.

• day – (str) The day of the image.

• time – (str) The time of the image.

• image_type – (str) The type of the image (e.g., ‘bright’).

• output_folder – (str) Folder to save the output file. Default is “output”.

store_shoreline_results(site, camera, year, month, day, time, image_type, shoreline_coords, bottom_boundary, watershed_coords, y_distance, rmse_value)[source]

Store the computed results for a given image.

Parameters:

• site – (str) The site identifier.

• camera – (str) The camera identifier.

• year – (str) The year of the image.

• month – (str) The month of the image.

• day – (str) The day of the image.

• time – (str) The time of the image.

• image_type – (str) The type of the image (e.g., ‘bright’).

• shoreline_coords – (np.ndarray) The final shoreline coords.

• bottom_boundary – (np.ndarray) The computed bottom boundarys. (1,2,3,median)

• watershed_coords – (np.ndarray) The watershed coordinates.

• y_distance – (np.ndarray) The computed y-distance.

• rmse_value – (float) The computed RMSE value.

class c_Workflow.ShorelineWorkflow(image_path, image_type, shoreline_datastore, make_intermediate_plots=False)[source]

Bases: object

A class that processes ARGUS-style image products by applying filtering criteria (brightness, blur, glare), segmenting the shoreline using the SAM model, and performing analysis on the detected shoreline. The processed results are stored in the provided datastore.

This class supports different image types such as ‘bright’, ‘timex’, ‘dark’, etc., and can generate intermediate plots. Filtering is applied before any further processing.

shoreline_datastore

The datastore to store results.

Type:

ShorelineDatastore

static apply_watershed(image_path, bottom_boundary, kernel_size=200, window_size=25, make_plot=False)[source]

Apply watershed segmentation to clean up the shoreline using the bottom boundary as a marker.

Parameters:

• image_path – (str) Path to the input image.

• bottom_boundary – (np.ndarray) Extracted bottom boundary coordinates used as markers for the watershed algorithm.

• kernel_size – (int, optional) Size of the kernel for Gaussian blur (default is 200).

• window_size – (int, optional) Size of the sliding window to calculate noise (standard deviation) (default is 25).

• make_plot – (bool, optional) Whether to plot intermediate results (default is False).

Returns:

markers (np.ndarray): The segmented image after watershed with marked boundary.

Returns:

watershed_coords (np.ndarray): Extracted coordinates of the watershed boundary.

static compute_rmse(coords_1, coords_2)[source]

Compute the RMSE (Root Mean Squared Error) between two sets of coordinates.

Parameters:

• coords_1 – (np.ndarray) First set of coordinates (e.g., watershed coordinates).

• coords_2 – (np.ndarray) Second set of coordinates (e.g., bottom boundary).

Returns:

(float) The RMSE value between the two sets of coordinates, or None if there are issues with the input.

static compute_y_distance(coords_1, coords_2)[source]

Compute the distance between the y-values of two sets of coordinates for each x-coordinate.

Parameters:

• coords_1 – (np.ndarray) First set of coordinates (e.g., watershed boundary).

• coords_2 – (np.ndarray) Second set of coordinates (e.g., bottom boundary).

Returns:

(np.ndarray) An array of distances between the y-values of the two coordinate sets.

static extract_bottom_boundary_from_mask(mask, make_plot=False, image_path='')[source]

Extracts the bottom boundary (maximum y-value for each x) from a binary mask.

Parameters:

• mask – (np.ndarray) The binary mask where 255 represents the object of interest.

• make_plot – (bool, optional) Whether to plot intermediate results (default is False).

• image_path – (str, optional) Path to the image to segment (default is ‘’).

Returns:

(np.ndarray) The bottom boundary as (x, y) coordinates.

static find_surfzone_coords(image_path, num_points=5, step=200, max_attempts=100, make_plot=False)[source]

Extract up to num_points random points from the largest connected component in the image representing the surfzone region (typically the shoreline).

Parameters:

• image_path – (str) Path to the input image.

• num_points – (int, optional) Number of points to find (default is 5).

• step – (int, optional) Horizontal step between searches for valid points (default is 200).

• max_attempts – (int, optional) Maximum number of attempts to find valid points (default is 100).

• make_plot – (bool, optional) Whether to plot intermediate results (default is False).

Returns:

marker_coords (list of tuples): List of (x, y) coordinates of the marker points.

Returns:

main_region_mask (np.ndarray): Binary mask of the cleaned region.

static generate_random_coords_above_line(coords, max_range=200, min_points=5, min_y_offset=100, max_y_offset=200)[source]

Generate random coords above a line, with random x-values within dynamically determined intervals.

Parameters:

• coords – (np.ndarray or list) (x, y) coords defining the line.

• max_range – (int, optional) Maximum range between x-values for each interval. Default is 200.

• min_points – (int, optional) Minimum number of intervals (or points) to generate. Default is 5.

• min_y_offset – (int, optional) Minimum y-offset to sample above the line. Default is 100.

• max_y_offset – (int, optional) Maximum y-offset to sample above the line. Default is 200.

Returns:

(list) List of (x, y) tuples representing the random coords above the line.

static load_and_predict_sam_model(image_path, checkpoint_path='segment-anything-main/sam_vit_h_4b8939.pth', model_type='vit_h', shoreline_coords=[(1000, 300)], beach_coords=None)[source]

Loads the SAM model and makes a prediction for a given image.

Parameters:

• image_path – (str) Path to the image to segment.

• checkpoint_path – (str, optional) Path to the SAM model checkpoint (default is “segment-anything-main/sam_vit_h_4b8939.pth”).

• model_type – (str, optional) Type of SAM model to use (“vit_b”, “vit_l”, “vit_h”) (default is “vit_h”).

• shoreline_coords – (list of tuples, optional) List of shoreline coordinates (x, y), used as input points (default is [(1000, 300)]).

• beach_coords – (list of tuples, optional) Optional list of additional coordinates to help with segmentation (default is None).

Returns:

(np.ndarray) The best mask prediction from the SAM model.

static plot_image_and_shoreline(image_path, shoreline_coords=None, watershed_coords=None, other_coords=None, y_distance=None, save_dir=None)[source]

Plot the image with the bottom boundary and the watershed fitted shoreline.

Parameters:

• image_path – (str) The path to the image.

• shoreline_coords – (np.ndarray, optional) The extracted bottom boundary coords to plot (default is None).

• watershed_coords – (np.ndarray, optional) The extracted watershed boundary coords to plot (default is None).

• other_coords – (np.ndarray, optional) Any other set of coordinates to plot (default is None).

• y_distance – (np.ndarray, optional) The y-distance to plot on a secondary y-axis (default is None).

• save_dir – (str, optional) Directory to save the plot (default is None, meaning the plot will be displayed but not saved).

process()[source]

Main function to process a single image based on the selected image_type. Calls the appropriate workflow method based on the image type.

Returns:

(ShorelineDatastore) The datastore after processing the image or a string indicating failure.

process_bright()[source]

Process a single ‘bright’ image.

This method follows the workflow specific to ‘bright’ image types. It performs the following steps: 1. Extract bottom boundaries from the image in three attempts (using SAM). 2. Apply a watershed segmentation to the image based on SAM shoreline. 3. Compute RMSE between watershed coordinates and SAM shoreline. 4. Plot and store the results.

Returns:

(ShorelineDatastore) The updated shoreline datastore after processing the image.

process_dark()[source]

Process a single ‘dark’ image. Placeholder for future implementation.

Returns:

(str) A message indicating that no workflow is available for ‘dark’ image type yet.

process_snap()[source]

Process a single ‘snap’ image. Placeholder for future implementation.

Returns:

(str) A message indicating that no workflow is available for ‘snap’ image type yet.

process_timex()[source]

Process a single ‘timex’ image.

This method follows the workflow specific to ‘timex’ image types. It uses the results from the ‘bright’ image processing and follows similar steps to the ‘bright’ workflow.

Returns:

(ShorelineDatastore) The updated shoreline datastore after processing the image.

process_var()[source]

Process a single ‘var’ image. Placeholder for future implementation.

Returns:

(str) A message indicating that no workflow is available for ‘var’ image type yet.

static resample_to_boundary(coords_1, coords_2)[source]

Resample coordinates from one set to match the length and shape of another using linear interpolation.

Parameters:

• coords_1 – (np.ndarray) First set of coordinates (e.g., watershed boundary).

• coords_2 – (np.ndarray) Second set of coordinates (e.g., bottom boundary).

Returns:

(np.ndarray) Resampled coordinates with the same length as the second set.

utils.check_processed_images(image_metadata, pt_dir, output_dir)[source]

Check if an image has been processed by verifying the existence of its corresponding shoreline point and plot files.

Parameters:

• image_metadata – (dict) A dictionary containing metadata of the image to check. Expected keys include ‘site’, ‘camera’, ‘year’, ‘month’, ‘day’, ‘time’, and ‘image_type’.

• pt_dir – (str) Directory path where shoreline point files (e.g., ‘.txt’ files) are stored.

• output_dir – (str) Directory path where shoreline output files (e.g., ‘.png’ plots) are stored.

Returns:

(bool) True if the image has been processed (i.e., both the point and plot files exist), False otherwise.

utils.create_video_from_images(datastore, video_name='output_video.mp4', frame_rate=30, image_type='timex', camera=None, site=None)[source]

Create a video from images in the datastore with optional filtering by image type, camera, and site.

Parameters:

• datastore – (ImageDatastore) The ImageDatastore object containing the images to be processed.

• video_name – (str, optional) The name of the output video file. Default is “output_video.mp4”.

• frame_rate – (int, optional) The frame rate for the video (frames per second). Default is 30.

• image_type – (str, optional) The type of images to include in the video (e.g., ‘bright’, ‘snap’). Default is ‘timex’.

• camera – (str, optional) The camera identifier to filter by (e.g., ‘CACO03’). If None, process all cameras. Default is None.

• site – (str, optional) The site identifier to filter by. If None, process all sites. Default is None.

Returns:

None

Raises:

ValueError – If no images match the filter criteria.

utils.process_images(datastore, img_type, shoreline_datastore, make_intermediate_plots)[source]

Process images of a specified type and perform shoreline analysis using the ShorelineWorkflow class.

Parameters:

• datastore – (ImageDatastore) An instance of the ImageDatastore class containing image metadata.

• img_type – (str) The type of image to process (e.g., ‘bright’, ‘timex’).

• shoreline_datastore – (ShorelineDatastore) An instance of the ShorelineDatastore class to store shoreline analysis results.

• make_intermediate_plots – (bool) Flag indicating whether intermediate plots should be generated during processing.

utils.remove_processed_images(datastore, pt_dir, output_dir)[source]

Remove images from the datastore that have already been processed (i.e., their corresponding shoreline point and plot files exist).

Parameters:

• datastore – (ImageDatastore) An instance of the ImageDatastore class containing image metadata.

• pt_dir – (str) Directory path for shoreline point files.

• output_dir – (str) Directory path for shoreline output files.