metadata_handler

def load_metadata(self):
    """Load metadata from CSV file and validate it against the available images."""
    if self.metadata_file is None:
        logger.debug("No metadata file provided, skipping metadata loading")
        return

    logger.debug(f"Loading metadata from {self.metadata_file}")
    if not os.path.exists(self.metadata_file):
        logger.warning(f"Metadata file {self.metadata_file} does not exist")
        return

    try:
        self.metadata_df = pd.read_csv(self.metadata_file)

        # Check for required filename column
        if "filename" not in self.metadata_df.columns:
            logger.error("Metadata file does not contain required 'filename' column")
            self.metadata_df = None
            return

        # Check if the number of entries in metadata_file matches the number of images
        # Only if image_filenames is provided
        if self.image_filenames:
            metadata_files = set(self.metadata_df["filename"])
            all_files = set([os.path.basename(f) for f in self.image_filenames])

            if len(metadata_files) != len(all_files):
                logger.warning(
                    f"Number of entries in metadata file ({len(metadata_files)}) "
                    f"does not match number of images ({len(all_files)})"
                )

        # Check for essential columns (optional but recommended)
        for col in ["sourceID", "ra", "dec"]:
            if col not in self.metadata_df.columns:
                logger.debug(f"Optional column '{col}' not found in metadata file")

        # Validate RA/Dec coordinates if both are present
        if "ra" in self.metadata_df.columns and "dec" in self.metadata_df.columns:
            logger.info("Validating RA/Dec coordinates for ICRS compatibility")
            try:
                self._validate_icrs_coordinates(self.metadata_df["ra"], self.metadata_df["dec"])
            except ValueError as e:
                logger.error(f"ICRS coordinate validation failed: {str(e)}")
                self.metadata_df = None
                return

        # Set index to filename for easier access
        self.metadata_df.set_index("filename", inplace=True)
        logger.info(f"Successfully loaded metadata for {len(self.metadata_df)} files")

    except Exception as e:
        logger.error(f"Error loading metadata: {str(e)}")
        self.metadata_df = None

def get_metadata_for_file(self, filename: str) -> dict | None:
    """Get metadata for a specific file.

    Args:
        filename: The filename to get metadata for.

    Returns:
        dict: Metadata for the file, or None if not found.
    """
    if self.metadata_df is None or filename not in self.metadata_df.index:
        return None

    # Return as dictionary
    return self.metadata_df.loc[filename].to_dict()

def get_all_metadata(self) -> pd.DataFrame | None:
    """Get all metadata.

    Returns:
        pd.DataFrame: The full metadata DataFrame, or None if no metadata loaded.
    """
    return self.metadata_df