Skip to content

VOC Stats

Bases: BaseStats

Concrete analyzer for datasets in Pascal VOC (XML) format.

This class implements the processing logic for XML annotation files. It coordinates data reading, geometric feature extraction, and pixel-level image analysis to build a comprehensive feature matrix.

Source code in tools/stats/voc_stats.py 
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class VOCStats(BaseStats):
    """
    Concrete analyzer for datasets in Pascal VOC (XML) format.

    This class implements the processing logic for XML annotation files.
    It coordinates data reading, geometric feature extraction, and
    pixel-level image analysis to build a comprehensive feature matrix.
    """
    _worker_image_map = {}

    @staticmethod
    def get_umap_features(df: pd.DataFrame) -> List[str]:
        """
        Selects relevant numeric columns for dimensionality reduction (UMAP).

        Filters out metadata (paths, timestamps), categorical data,
        and outlier flags to ensure UMAP focuses on geometric and
        content-based manifold analysis.

        Args:
            df (pd.DataFrame): The complete feature matrix.

        Returns:
            List[str]: A list of numeric column names suitable for projection.
        """
        exclude = {
            ImageStatsKeys.class_name,
            ImageStatsKeys.path,
            ImageStatsKeys.mtime,
            ImageStatsKeys.has_neighbors,
            ImageStatsKeys.full_size,
            ImageStatsKeys.objects_count
        }

        numeric_features = [c for c in df.select_dtypes(include=[np.number]).columns
                            if c not in exclude and not c.startswith('outlier')]

        return numeric_features

    @classmethod
    def _init_worker(cls, image_dict: Dict[str, str]):
        """
        Initializes a worker process with a shared image lookup map.

        This method is called once per worker process during the startup
        of the ProcessPoolExecutor to provide fast access to image paths.

        Args:
            image_dict (Dict[str, str]): Map of image stems to their absolute paths.
        """
        cls._worker_image_map = image_dict

    @staticmethod
    def _analyze_worker(
            file_path: Path,
            reader: BaseReader,
            margin_threshold: int = 5,
            class_mapping: Optional[Dict[str, str]] = None

    ) -> List[Dict[str, str]]:
        """
         Parses a single VOC XML file and merges geometric data with pixel metrics.

         The workflow includes:
             1. Parsing XML to get object coordinates.
             2. Calculating geometric features (area, aspect ratio, etc.).
             3. Analyzing image content (brightness, contrast, blur).
             4. Fusing both data sources into a single record.

         Args:
             file_path (Path): Path to the .xml annotation file.
             reader (BaseReader): XML parser instance.
             margin_threshold (int): Margin for truncation detection.
             class_mapping (Optional[Dict[str, str]]): ID-to-name mapping.

         Returns:
             List[Dict[str, str]]: A list of fused feature dictionaries
                 for each object. Returns an empty list on failure.
         """
        try:
            annotation_data = reader.read(file_path).get("annotation")

            if not annotation_data:
                return []
            correspond_img_str = VOCStats._worker_image_map.get(file_path.stem)
            stat_data = FeatureExtractor.extract_features(file_path, annotation_data, margin_threshold)
            pixel_data = ImageContentAnalyzer.analyze_metrics(correspond_img_str)

            for obj in stat_data:
                obj.update(pixel_data)
                obj.update({ImageStatsKeys.im_path: correspond_img_str})

            return stat_data
        except Exception as e:
            return []

get_umap_features(df) staticmethod

Selects relevant numeric columns for dimensionality reduction (UMAP).

Filters out metadata (paths, timestamps), categorical data, and outlier flags to ensure UMAP focuses on geometric and content-based manifold analysis.

Parameters:

Name Type Description Default
df DataFrame

The complete feature matrix.

 required

Returns:

Type Description
List[str]

List[str]: A list of numeric column names suitable for projection.
Source code in tools/stats/voc_stats.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
@staticmethod
def get_umap_features(df: pd.DataFrame) -> List[str]:
    """
    Selects relevant numeric columns for dimensionality reduction (UMAP).

    Filters out metadata (paths, timestamps), categorical data,
    and outlier flags to ensure UMAP focuses on geometric and
    content-based manifold analysis.

    Args:
        df (pd.DataFrame): The complete feature matrix.

    Returns:
        List[str]: A list of numeric column names suitable for projection.
    """
    exclude = {
        ImageStatsKeys.class_name,
        ImageStatsKeys.path,
        ImageStatsKeys.mtime,
        ImageStatsKeys.has_neighbors,
        ImageStatsKeys.full_size,
        ImageStatsKeys.objects_count
    }

    numeric_features = [c for c in df.select_dtypes(include=[np.number]).columns
                        if c not in exclude and not c.startswith('outlier')]

    return numeric_features