# -----------------
# Copyright © 2025 ACK Cyfronet AGH, Poland.
# -----------------
from scipy.io import loadmat, whosmat
  
def read_catalog(catalog_path):
    """
    Reads the provided catalog in EPISODES Platform format (https://docs.cyfronet.pl/display/ISDOC/Catalogs)

    Parameters:
        catalog_path: Path to the catalog file to be read.

    Returns:
        catalog (np.ndarray): A structured NumPy array representing the catalog.

    Raises:
        ValueError: If the specified field name is not found in the catalog.
    """
    catalog_contents = loadmat(catalog_path, mat_dtype=True)
    catalog_field_name = whosmat(catalog_path)[0][0] # Getting the name of first non-metadata field
    catalog = catalog_contents[catalog_field_name][0]
    return catalog