Handlers

This module provides a class for handling file operations related to segmentation data.

It includes functionalities for saving and loading segmentation data in HDF files, verifying the integrity of HDF and video files, and checking the validity of analysis files.

CLASS	DESCRIPTION
FileHandler	A class for handling file operations related to segmentation data and metadata.

FileHandler

A class for handling file operations related to segmentation data and metadata.

This class provides methods for saving and loading segmentation data in HDF files, verifying the integrity of HDF and video files, and checking analysis files.

METHOD	DESCRIPTION
save_hdf_file	Saves segmentation data and metadata to an HDF file.
load_hdf_file	Loads segmentation data and metadata from an HDF file.
verify_hdf_file	Verifies the integrity of an HDF file.
verify_video_file	Verifies the integrity of a video file.
verify_analysis_files	Verifies the analysis files for counts and percentages.

save_hdf_file

save_hdf_file(file_path, segmentation_data, metadata)

Saves segmentation data and metadata to an HDF file.

PARAMETER	DESCRIPTION
file_path	Path to the HDF file. TYPE: Path
segmentation_data	Segmentation data to be saved. TYPE: ndarray
metadata	Metadata associated with the segmentation data. TYPE: Dict[str, Any]

Source code in cityseg/file_handler.py

@staticmethod
def save_hdf_file(
    file_path: Path, segmentation_data: np.ndarray, metadata: Dict[str, Any]
) -> None:
    """
    Saves segmentation data and metadata to an HDF file.

    Args:
        file_path (Path): Path to the HDF file.
        segmentation_data (np.ndarray): Segmentation data to be saved.
        metadata (Dict[str, Any]): Metadata associated with the segmentation data.
    """
    with h5py.File(file_path, "w") as f:
        f.create_dataset("segmentation", data=segmentation_data, compression="gzip")
        if "palette" in metadata and isinstance(metadata["palette"], np.ndarray):
            metadata["palette"] = metadata["palette"].tolist()
        json_metadata = json.dumps(metadata)
        f.create_dataset("metadata", data=json_metadata)

load_hdf_file

load_hdf_file(file_path)

Loads segmentation data and metadata from an HDF file.

PARAMETER	DESCRIPTION
file_path	Path to the HDF file. TYPE: Path

RETURNS	DESCRIPTION
Tuple[File, Dict[str, Any]]	Tuple[h5py.File, Dict[str, Any]]: Loaded HDF file and metadata.

Source code in cityseg/file_handler.py

@staticmethod
def load_hdf_file(file_path: Path) -> Tuple[h5py.File, Dict[str, Any]]:
    """
    Loads segmentation data and metadata from an HDF file.

    Args:
        file_path (Path): Path to the HDF file.

    Returns:
        Tuple[h5py.File, Dict[str, Any]]: Loaded HDF file and metadata.
    """
    hdf_file = h5py.File(file_path, "r")
    json_metadata = hdf_file["metadata"][()]
    metadata = json.loads(json_metadata)
    if "palette" in metadata and isinstance(metadata["palette"], list):
        metadata["palette"] = np.array(metadata["palette"], np.uint8)
    return hdf_file, metadata

verify_hdf_file

verify_hdf_file(file_path, config)

Verifies the integrity of an HDF file.

PARAMETER	DESCRIPTION
file_path	Path to the HDF file. TYPE: Path
config	Configuration object for comparison. TYPE: Config

RETURNS	DESCRIPTION
bool	True if the HDF file is valid and up-to-date, False otherwise. TYPE: bool

Source code in cityseg/file_handler.py

@staticmethod
def verify_hdf_file(file_path: Path, config: Config) -> bool:
    """
    Verifies the integrity of an HDF file.

    Args:
        file_path (Path): Path to the HDF file.
        config (Config): Configuration object for comparison.

    Returns:
        bool: True if the HDF file is valid and up-to-date, False otherwise.
    """
    try:
        with h5py.File(file_path, "r") as f:
            if "segmentation" not in f or "metadata" not in f:
                logger.warning(
                    f"HDF file at {file_path} is missing required datasets"
                )
                return False

            json_metadata = f["metadata"][()]
            metadata = json.loads(json_metadata)

            if metadata.get("frame_step") != config.frame_step:
                logger.warning(
                    f"HDF file frame step ({metadata.get('frame_step')}) does not match current config ({config.frame_step})"
                )
                return False

            segmentation_data = f["segmentation"]
            if len(segmentation_data) == 0:
                logger.warning(
                    f"HDF file at {file_path} contains no segmentation data"
                )
                return False

            first_frame = segmentation_data[0]
            last_frame = segmentation_data[-1]
            if first_frame.shape != last_frame.shape:
                logger.warning(
                    f"Inconsistent frame shapes in HDF file at {file_path}"
                )
                return False

        logger.debug(f"HDF file at {file_path} is valid and up-to-date")
        return True
    except Exception as e:
        logger.error(f"Error verifying HDF file at {file_path}: {str(e)}")
        return False

verify_video_file

verify_video_file(file_path)

Verifies the integrity of a video file.

PARAMETER	DESCRIPTION
file_path	Path to the video file. TYPE: Path

RETURNS	DESCRIPTION
bool	True if the video file is valid and up-to-date, False otherwise. TYPE: bool

Source code in cityseg/file_handler.py

@staticmethod
def verify_video_file(file_path: Path) -> bool:
    """
    Verifies the integrity of a video file.

    Args:
        file_path (Path): Path to the video file.

    Returns:
        bool: True if the video file is valid and up-to-date, False otherwise.
    """
    try:
        cap = cv2.VideoCapture(str(file_path))
        if not cap.isOpened():
            logger.warning(f"Unable to open video file at {file_path}")
            return False

        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))

        cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
        ret, first_frame = cap.read()
        if not ret:
            logger.warning(
                f"Unable to read first frame from video file at {file_path}"
            )
            return False

        cap.set(cv2.CAP_PROP_POS_FRAMES, frame_count - 1)
        ret, last_frame = cap.read()
        if not ret:
            logger.warning(
                f"Unable to read last frame from video file at {file_path}"
            )
            return False

        cap.release()
        logger.debug(f"Video file at {file_path} is valid and up-to-date")
        return True
    except Exception as e:
        logger.error(f"Error verifying video file at {file_path}: {str(e)}")
        return False

verify_analysis_files

verify_analysis_files(counts_file, percentages_file)

Verifies the analysis files for counts and percentages.

PARAMETER	DESCRIPTION
counts_file	Path to the counts file. TYPE: Path
percentages_file	Path to the percentages file. TYPE: Path

RETURNS	DESCRIPTION
bool	True if the analysis files are valid, False otherwise. TYPE: bool

Source code in cityseg/file_handler.py

@staticmethod
def verify_analysis_files(counts_file: Path, percentages_file: Path) -> bool:
    """
    Verifies the analysis files for counts and percentages.

    Args:
        counts_file (Path): Path to the counts file.
        percentages_file (Path): Path to the percentages file.

    Returns:
        bool: True if the analysis files are valid, False otherwise.
    """
    try:
        if counts_file.stat().st_size == 0 or percentages_file.stat().st_size == 0:
            logger.info("One or both analysis files are empty")
            return False
        return True
    except Exception as e:
        logger.error(f"Error verifying analysis files: {str(e)}")
        return False

cityseg.visualization_handler

This module provides a class for visualizing segmentation results using color palettes.

It includes methods to visualize segmentation maps with color palettes and options for displaying colored or blended results.

CLASS	DESCRIPTION
VisualizationHandler	A class for visualizing segmentation results using color palettes.

VisualizationHandler

A class for visualizing segmentation results using color palettes.

This class provides methods to visualize segmentation maps with color palettes and options for displaying colored or blended results.

METHOD	DESCRIPTION
visualize_segmentation	Visualizes segmentation results with color palettes.
_generate_palette	Generates a color palette for visualization.

visualize_segmentation

visualize_segmentation(
    images, seg_maps, palette=None, colored_only=False
)

Visualizes segmentation results using color palettes.

This method takes input images and their corresponding segmentation maps, applies the specified color palette, and returns the visualized results.

PARAMETER	DESCRIPTION
images	Input images or a list of images. TYPE: Union[ndarray, List[ndarray]]
seg_maps	Segmentation maps or a list of maps. TYPE: Union[ndarray, List[ndarray]]
palette	Color palette for visualization. If None, a default palette is generated. TYPE: Optional[ndarray] DEFAULT: None
colored_only	Flag to indicate if only colored results are desired (True) or blended with the original images (False). TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Union[ndarray, List[ndarray]]	Union[np.ndarray, List[np.ndarray]]: Visualized segmentation results, either as a single array or a list of arrays.

Source code in cityseg/visualization_handler.py

@staticmethod
def visualize_segmentation(
    images: Union[np.ndarray, List[np.ndarray]],
    seg_maps: Union[np.ndarray, List[np.ndarray]],
    palette: Optional[np.ndarray] = None,
    colored_only: bool = False,
) -> Union[np.ndarray, List[np.ndarray]]:
    """
    Visualizes segmentation results using color palettes.

    This method takes input images and their corresponding segmentation maps,
    applies the specified color palette, and returns the visualized results.

    Args:
        images (Union[np.ndarray, List[np.ndarray]]): Input images or a list of images.
        seg_maps (Union[np.ndarray, List[np.ndarray]]): Segmentation maps or a list of maps.
        palette (Optional[np.ndarray]): Color palette for visualization. If None, a default palette is generated.
        colored_only (bool): Flag to indicate if only colored results are desired (True) or blended with the original images (False).

    Returns:
        Union[np.ndarray, List[np.ndarray]]: Visualized segmentation results, either as a single array or a list of arrays.
    """
    logger.debug(
        f"Visualizing segmentation for {len(images) if isinstance(images, list) else 1} images"
    )
    if palette is None:
        palette = VisualizationHandler._generate_palette(256)
    if isinstance(palette, list):
        palette = np.array(palette, dtype=np.uint8)

    if isinstance(images, np.ndarray) and images.ndim == 3:
        images = [images]
        seg_maps = [seg_maps]

    results = []
    for image, seg_map in zip(images, seg_maps):
        color_seg = palette[seg_map]

        if colored_only:
            results.append(color_seg)
        else:
            img = image * 0.5 + color_seg * 0.5
            results.append(img.astype(np.uint8))

    return results[0] if len(results) == 1 else results