Skip to content

Utilities

Utilities for loading class names and creating class mappings.

Provides functions to load class definitions from text files and create dictionaries and lists for mapping class indices to names.

load_class_dict 

load_class_dict(
    name_file: str | None = None,
) -> dict[str, int]

Load class names from file and create name-to-index mapping.

Parameters:

Name Type Description Default
name_file str | None

Path to class names file (one class per line). If None (default), uses 'coco.names' from the shared/data directory.

 None

Returns:

Type Description
dict[str, int]

Mapping from class name (str) to class index (int). Example: {'person': 0, 'car': 2, 'dog': 16}

Raises:

Type Description
FileNotFoundError

If the class names file does not exist.
ValueError

If the file is empty or cannot be parsed.
Notes

The class names file should contain one class name per line. The class index is determined by the line number (0-indexed). Empty lines are skipped.

Examples:

>>> class_dict = load_class_dict()
>>> idx = class_dict['person']
>>> print(idx)  # Output: 0
Source code in src/dnt/shared/util.py 
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
def load_class_dict(name_file: str | None = None) -> dict[str, int]:
    """Load class names from file and create name-to-index mapping.

    Parameters
    ----------
    name_file : str | None, optional
        Path to class names file (one class per line). If None (default),
        uses 'coco.names' from the shared/data directory.

    Returns
    -------
    dict[str, int]
        Mapping from class name (str) to class index (int).
        Example: {'person': 0, 'car': 2, 'dog': 16}

    Raises
    ------
    FileNotFoundError
        If the class names file does not exist.
    ValueError
        If the file is empty or cannot be parsed.

    Notes
    -----
    The class names file should contain one class name per line.
    The class index is determined by the line number (0-indexed).
    Empty lines are skipped.

    Examples
    --------
    >>> class_dict = load_class_dict()
    >>> idx = class_dict['person']
    >>> print(idx)  # Output: 0

    """
    if not name_file:
        lib_root = Path(__file__).resolve().parents[1]
        name_file = lib_root / "shared/data/coco.names"
    else:
        name_file = Path(name_file)

    if not name_file.exists():
        raise FileNotFoundError(f"Class names file not found: {name_file}")

    with name_file.open("r", encoding="utf-8") as f:
        lines = [line.strip() for line in f.readlines()]

    if not lines:
        raise ValueError(f"Class names file is empty: {name_file}")

    class_dict = {name: idx for idx, name in enumerate(lines) if name}
    return class_dict

load_classes 

load_classes(name_file: str | None = None) -> list[str]

Load class names from file and return as list.

Parameters:

Name Type Description Default
name_file str | None

Path to class names file (one class per line). If None (default), uses 'coco.names' from the shared/data directory.

 None

Returns:

Type Description
list[str]

List of class names in order. Empty strings are filtered out. Example: ['person', 'bicycle', 'car', ..., 'toothbrush']

Raises:

Type Description
FileNotFoundError

If the class names file does not exist.
ValueError

If the file is empty.
Notes

The class index in the returned list corresponds to the order of class names in the input file (0-indexed). Lines with only whitespace are treated as empty and excluded from the result.

Examples:

>>> classes = load_classes()
>>> print(classes[0])  # Output: 'person'
>>> print(len(classes))  # Output: 80 (for COCO)
Source code in src/dnt/shared/util.py 
 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
109
110
111
112
113
114
115
116
117
118
119
120
121
def load_classes(name_file: str | None = None) -> list[str]:
    """Load class names from file and return as list.

    Parameters
    ----------
    name_file : str | None, optional
        Path to class names file (one class per line). If None (default),
        uses 'coco.names' from the shared/data directory.

    Returns
    -------
    list[str]
        List of class names in order. Empty strings are filtered out.
        Example: ['person', 'bicycle', 'car', ..., 'toothbrush']

    Raises
    ------
    FileNotFoundError
        If the class names file does not exist.
    ValueError
        If the file is empty.

    Notes
    -----
    The class index in the returned list corresponds to the order of class
    names in the input file (0-indexed). Lines with only whitespace are
    treated as empty and excluded from the result.

    Examples
    --------
    >>> classes = load_classes()
    >>> print(classes[0])  # Output: 'person'
    >>> print(len(classes))  # Output: 80 (for COCO)

    """
    if not name_file:
        lib_root = Path(__file__).resolve().parents[1]
        name_file = lib_root / "shared/data/coco.names"
    else:
        name_file = Path(name_file)

    if not name_file.exists():
        raise FileNotFoundError(f"Class names file not found: {name_file}")

    with name_file.open("r", encoding="utf-8") as f:
        results = [line.strip() for line in f.readlines() if line.strip()]

    if not results:
        raise ValueError(f"Class names file is empty: {name_file}")

    return results