Skip to content

VLM Utils

VLM

supervision.detection.vlm.VLM

Bases: Enum

Enum specifying supported Vision-Language Models (VLMs).

Attributes:

Name Type Description
PALIGEMMA

Google's PaliGemma vision-language model.
FLORENCE_2

Microsoft's Florence-2 vision-language model.
QWEN_2_5_VL

Qwen2.5-VL open vision-language model from Alibaba.
QWEN_3_VL

Qwen3-VL open vision-language model from Alibaba.
GOOGLE_GEMINI_2_0

Google Gemini 2.0 vision-language model.
GOOGLE_GEMINI_2_5

Google Gemini 2.5 vision-language model.
MOONDREAM

The Moondream vision-language model.
Source code in src/supervision/detection/vlm.py 
 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
class VLM(Enum):
    """
    Enum specifying supported Vision-Language Models (VLMs).

    Attributes:
        PALIGEMMA: Google's PaliGemma vision-language model.
        FLORENCE_2: Microsoft's Florence-2 vision-language model.
        QWEN_2_5_VL: Qwen2.5-VL open vision-language model from Alibaba.
        QWEN_3_VL: Qwen3-VL open vision-language model from Alibaba.
        GOOGLE_GEMINI_2_0: Google Gemini 2.0 vision-language model.
        GOOGLE_GEMINI_2_5: Google Gemini 2.5 vision-language model.
        MOONDREAM: The Moondream vision-language model.
    """

    PALIGEMMA = "paligemma"
    FLORENCE_2 = "florence_2"
    QWEN_2_5_VL = "qwen_2_5_vl"
    QWEN_3_VL = "qwen_3_vl"
    DEEPSEEK_VL_2 = "deepseek_vl_2"
    GOOGLE_GEMINI_2_0 = "gemini_2_0"
    GOOGLE_GEMINI_2_5 = "gemini_2_5"
    MOONDREAM = "moondream"

    @classmethod
    def list(cls) -> list[str]:
        return [c.value for c in cls]

    @classmethod
    def from_value(cls, value: VLM | str) -> VLM:
        if isinstance(value, cls):
            return value
        if isinstance(value, str):
            value = value.lower()
            try:
                return cls(value)
            except ValueError:
                raise ValueError(f"Invalid value: {value}. Must be one of {cls.list()}")
        raise ValueError(
            f"Invalid value type: {type(value)}. Must be an instance of "
            f"{cls.__name__} or str."
        )

LMM

supervision.detection.vlm.LMM

Bases: Enum

Enum specifying supported Large Multimodal Models (LMMs).

Deprecated

LMM is deprecated and will be removed in supervision-0.31.0. Use VLM instead.

Attributes:

Name Type Description
PALIGEMMA

Google's PaliGemma vision-language model.
FLORENCE_2

Microsoft's Florence-2 vision-language model.
QWEN_2_5_VL

Qwen2.5-VL open vision-language model from Alibaba. QWEN_3_VL: Qwen3-VL open vision-language model from Alibaba.
GOOGLE_GEMINI_2_0

Google Gemini 2.0 vision-language model.
GOOGLE_GEMINI_2_5

Google Gemini 2.5 vision-language model.
MOONDREAM

The Moondream vision-language model.
Source code in src/supervision/detection/vlm.py 
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
class LMM(Enum):
    """
    Enum specifying supported Large Multimodal Models (LMMs).

    !!! deprecated "Deprecated"

        `LMM` is deprecated and will be removed in `supervision-0.31.0`.
        Use `VLM` instead.

    Attributes:
        PALIGEMMA: Google's PaliGemma vision-language model.
        FLORENCE_2: Microsoft's Florence-2 vision-language model.
        QWEN_2_5_VL: Qwen2.5-VL open vision-language model from Alibaba.\
        QWEN_3_VL: Qwen3-VL open vision-language model from Alibaba.
        GOOGLE_GEMINI_2_0: Google Gemini 2.0 vision-language model.
        GOOGLE_GEMINI_2_5: Google Gemini 2.5 vision-language model.
        MOONDREAM: The Moondream vision-language model.
    """

    PALIGEMMA = "paligemma"
    FLORENCE_2 = "florence_2"
    QWEN_2_5_VL = "qwen_2_5_vl"
    QWEN_3_VL = "qwen_3_vl"
    DEEPSEEK_VL_2 = "deepseek_vl_2"
    GOOGLE_GEMINI_2_0 = "gemini_2_0"
    GOOGLE_GEMINI_2_5 = "gemini_2_5"
    MOONDREAM = "moondream"

    @classmethod
    def list(cls) -> list[str]:
        return [c.value for c in cls]

    @classmethod
    def from_value(cls, value: LMM | str) -> LMM:
        warn_deprecated(
            "`LMM` is deprecated since `supervision-0.27.0` and will be removed in "
            "`supervision-0.31.0`. Use `VLM` instead."
        )
        if isinstance(value, cls):
            return value
        if isinstance(value, str):
            value = value.lower()
            try:
                return cls(value)
            except ValueError:
                raise ValueError(f"Invalid value: {value}. Must be one of {cls.list()}")
        raise ValueError(
            f"Invalid value type: {type(value)}. Must be an instance of "
            f"{cls.__name__} or str."
        )

validate_vlm_parameters

supervision.detection.vlm.validate_vlm_parameters(vlm: VLM | str, result: Any, kwargs: dict[str, Any]) -> VLM

Source code in src/supervision/detection/vlm.py 
207
208
209
210
211
212
213
@deprecated(  # type: ignore[untyped-decorator]
    target=_validate_vlm_parameters,
    deprecated_in="0.29.0",
    remove_in="0.32.0",
)
def validate_vlm_parameters(vlm: VLM | str, result: Any, kwargs: dict[str, Any]) -> VLM:
    return void(vlm, result, kwargs)  # type: ignore[no-any-return]

edit_distance

supervision.detection.utils.vlms.edit_distance(string_1: str, string_2: str, case_sensitive: bool = True) -> int

Calculates the minimum number of single-character edits required to transform one string into another. Allowed operations are insertion, deletion, and substitution.

Parameters:

Name Type Description Default

string_1

str

The source string to be transformed.

 required

string_2

str

The target string to transform into.

 required

case_sensitive

bool

Whether comparison should be case-sensitive. Defaults to True.

 True

Returns:

Type Description
int

The minimum number of edits required to convert string_1
int

into string_2.

Examples:

>>> import supervision as sv
>>> sv.edit_distance("hello", "hello")
0
>>> sv.edit_distance("Test", "test", case_sensitive=True)
1
>>> sv.edit_distance("abc", "xyz")
3
>>> sv.edit_distance("hello", "")
5
>>> sv.edit_distance("", "")
0
>>> sv.edit_distance("hello world", "helloworld")
1
Source code in src/supervision/detection/utils/vlms.py 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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
def edit_distance(string_1: str, string_2: str, case_sensitive: bool = True) -> int:
    """
    Calculates the minimum number of single-character edits required
    to transform one string into another. Allowed operations are insertion,
    deletion, and substitution.

    Args:
        string_1: The source string to be transformed.
        string_2: The target string to transform into.
        case_sensitive: Whether comparison should be case-sensitive.
            Defaults to True.

    Returns:
        The minimum number of edits required to convert `string_1`
        into `string_2`.

    Examples:
        ```pycon
        >>> import supervision as sv
        >>> sv.edit_distance("hello", "hello")
        0
        >>> sv.edit_distance("Test", "test", case_sensitive=True)
        1
        >>> sv.edit_distance("abc", "xyz")
        3
        >>> sv.edit_distance("hello", "")
        5
        >>> sv.edit_distance("", "")
        0
        >>> sv.edit_distance("hello world", "helloworld")
        1

        ```
    """
    if not case_sensitive:
        string_1 = string_1.lower()
        string_2 = string_2.lower()

    if len(string_1) < len(string_2):
        string_1, string_2 = string_2, string_1

    prev_row = list(range(len(string_2) + 1))
    curr_row = [0] * (len(string_2) + 1)

    for i in range(1, len(string_1) + 1):
        curr_row[0] = i
        for j in range(1, len(string_2) + 1):
            if string_1[i - 1] == string_2[j - 1]:
                substitution_cost = 0
            else:
                substitution_cost = 1
            curr_row[j] = min(
                prev_row[j] + 1,
                curr_row[j - 1] + 1,
                prev_row[j - 1] + substitution_cost,
            )
        prev_row, curr_row = curr_row, prev_row

    return prev_row[len(string_2)]

fuzzy_match_index

supervision.detection.utils.vlms.fuzzy_match_index(candidates: list[str], query: str, threshold: int, case_sensitive: bool = True) -> int | None

Searches for the first string in candidates whose edit distance to query is less than or equal to threshold.

Parameters:

Name Type Description Default

candidates

list[str]

List of strings to search.

 required

query

str

String to compare against the candidates.

 required

threshold

int

Maximum allowed edit distance for a match.

 required

case_sensitive

bool

Whether matching should be case-sensitive.

 True

Returns:

Type Description
int | None

Index of the first matching string in candidates,
int | None

or None if no match is found.

Examples:

>>> from supervision.detection.utils.vlms import fuzzy_match_index
>>> fuzzy_match_index(["cat", "dog", "rat"], "dat", threshold=1)
0
>>> fuzzy_match_index(["alpha", "beta", "gamma"], "bata", threshold=1)
1
>>> fuzzy_match_index(["one", "two", "three"], "xyz", threshold=2) is None
True
Source code in src/supervision/detection/utils/vlms.py 
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
def fuzzy_match_index(
    candidates: list[str],
    query: str,
    threshold: int,
    case_sensitive: bool = True,
) -> int | None:
    """
    Searches for the first string in `candidates` whose edit distance
    to `query` is less than or equal to `threshold`.

    Args:
        candidates: List of strings to search.
        query: String to compare against the candidates.
        threshold: Maximum allowed edit distance for a match.
        case_sensitive: Whether matching should be case-sensitive.

    Returns:
        Index of the first matching string in candidates,
        or None if no match is found.

    Examples:
        ```pycon
        >>> from supervision.detection.utils.vlms import fuzzy_match_index
        >>> fuzzy_match_index(["cat", "dog", "rat"], "dat", threshold=1)
        0
        >>> fuzzy_match_index(["alpha", "beta", "gamma"], "bata", threshold=1)
        1
        >>> fuzzy_match_index(["one", "two", "three"], "xyz", threshold=2) is None
        True

        ```
    """
    for idx, candidate in enumerate(candidates):
        if edit_distance(candidate, query, case_sensitive=case_sensitive) <= threshold:
            return idx
    return None

Comments