Skip to content

VLMs Utils

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:

Name Type Description
int 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 
 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
60
61
62
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 (str): The source string to be transformed.
        string_2 (str): The target string to transform into.
        case_sensitive (bool, optional): Whether comparison should be case-sensitive.
            Defaults to True.

    Returns:
        int: 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

Optional[int]: Index of the first matching string in candidates, 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 
 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
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[str]): List of strings to search.
        query (str): String to compare against the candidates.
        threshold (int): Maximum allowed edit distance for a match.
        case_sensitive (bool, optional): Whether matching should be case-sensitive.

    Returns:
        Optional[int]: 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