Data

sand_atlas.data.get_all(sand, quality)

Retrieve all sand data with the specified quality.

Parameters: sand (str): The name or identifier of the sand data to retrieve. quality (str): The quality level of the sand data. Must be one of ‘ORIGINAL’, ‘100’, ‘30’, ‘10’, or ‘3’.

Returns: dict or None: A dictionary containing the sand data if the request is successful, or None if an error occurs.

Raises: ValueError: If the quality parameter is not one of the allowed values. requests.exceptions.RequestException: If there is an issue with the HTTP request.

sand_atlas.data.get_by_id(sand, quality, id)

Retrieve a specific sand particle by its ID.

Parameters: sand (str): The name or the sand type to retrieve. quality (str): The quality level of the sand data. Must be one of ‘ORIGINAL’, ‘100’, ‘30’, ‘10’, or ‘3’. id (int): The id of the sand data item to retrieve.

Returns: dict or None: A dictionary containing the sand data if the request is successful, or None if an error occurs.

Raises: ValueError: If the quality parameter is not one of the allowed values. requests.exceptions.RequestException: If there is an issue with the HTTP request.

sand_atlas.data.list()

Requests a list of all sand types from the sand atlas server.

Parameters:

  • server_url (str) – The URL of the Flask server.

  • folder_name (str) – The name of the folder to query for files.

Returns:

A list of filenames if the request is successful. None: If the request fails.

Return type:

list

IO

sand_atlas.io.convert(input_filename, output_filename)

Converts data from an input file and saves it to an output file.

Parameters:

  • input_filename (str) – The path to the input file containing the data to be converted.

  • output_filename (str) – The path to the output file where the converted data will be saved.

Returns:

None

sand_atlas.io.load_data(filename)

Load data from a file based on its extension. Parameters: filename (str): The path to the file to be loaded. Returns: data: The data loaded from the file. The type of data returned depends on the file extension: - For ‘.tif’ or ‘.tiff’ files, returns a memmap or an array from tifffile. - For ‘.raw’ files, returns a memmap from numpy. - For ‘.npz’ files, returns an array from numpy. - For ‘.nrrd’ files, returns the data and header from nrrd.

sand_atlas.io.save_data(data, filename, microns_per_voxel=None)

Save data to a file with the specified filename and extension.

Parameters: data (array-like): The data to be saved. filename (str): The name of the file to save the data to. The extension of the filename determines the format in which the data will be saved.

Supported file extensions: - ‘tif’ or ‘tiff’: Save data as a TIFF file using tifffile.imsave. - ‘raw’: Save data as a raw binary file using data.tofile. - ‘npz’: Save data as a NumPy compressed file using numpy.savez. - ‘nrrd’: Save data as an NRRD file using nrrd.write.

Raises: ValueError: If the file extension is not supported.

Pipeline

Video

sand_atlas.video.make_individual_videos(stl_foldername, output_foldername, max_videos=9, bg_colour=None, fg_colour=None, debug=False)

Renders individual videos for each STL file in the specified folder.

This function processes each STL file in the given folder, renders a rotating animation using Blender, converts the animation into a video using ffmpeg, and saves the video to the specified output folder.

Parameters:

  • stl_foldername (str) – The path to the folder containing STL files.

  • output_foldername (str) – The path to the folder where the output videos will be saved.

  • max_videos (int, optional) – The maximum number of videos to process. Defaults to 9.

  • bg_colour (str, optional) – The background colour for the rendered images. Defaults to None.

  • fg_colour (str, optional) – The foreground colour for the rendered images. Defaults to None.

Returns:

None

Notes

  • The function assumes Blender and ffmpeg are installed and available in the system’s PATH.

  • The function uses 120 frames to create a 4-second video at 30 frames per second.

  • If the debug variable is set to False, the rendered images are cleaned up after the video is created.

  • The videos are named sequentially as particle_XXXXX.mp4 in the output folder.

sand_atlas.video.make_website_video(stl_foldername, output_foldername, debug=False)

Generates a video from STL files by rendering them, converting to webm format, and stitching them together into a grid.

Parameters: stl_foldername (str): The folder containing the STL files. output_foldername (str): The folder where the final video will be saved.

Steps: 1. Create a blank webm video if it doesn’t exist. 2. Render each STL file into a webm video using Blender and ffmpeg. 3. Stitch the individual videos into a grid format. 4. Concatenate the grids into a single video. 5. Reduce the file size of the final video. 6. Clean up intermediate files if not in debug mode.

Note: - Assumes the presence of Blender and ffmpeg in the system path. - Uses a maximum of 72 STL files for the video. - Pads the grid with blank videos if the number of STL files is less than 72.

sand_atlas.video.resolve_path_for_blender(script_relative_path)

Resolves the absolute path for a Blender script relative to the current script’s directory.

If the script is running in a Windows Subsystem for Linux (WSL) environment, the path is converted to a Windows path using the wslpath command.

Parameters:

script_relative_path (str) – The relative path to the Blender script from the current script’s directory.

Returns:

The absolute path to the Blender script. If running in WSL, returns the Windows path.

Return type:

str

Raises:

RuntimeError – If there is an error converting the path with wslpath in a WSL environment.