Skip to content

Assets

Supervision offers an assets download utility that allows you to download image and video files that you can use in your demos.

download_assets

supervision.assets.downloader.download_assets(asset_name: Assets | str, directory: str | Path | None = None) -> str

Download a specified asset if it doesn't already exist or is corrupted.

Parameters:

Name Type Description Default

asset_name

Assets | str

The name or type of the asset to be downloaded.

 required

directory

str | Path | None

Optional output directory. Defaults to the current working directory for backward compatibility.

 None

Returns:

Type Description
str

The downloaded asset path. When directory is omitted, this preserves
str

the historical filename-only return value.
Example 
>>> from supervision.assets import download_assets, ImageAssets, VideoAssets
>>> download_assets(VideoAssets.VEHICLES)  # doctest: +SKIP
'vehicles.mp4'

>>> download_assets(ImageAssets.PEOPLE_WALKING)  # doctest: +SKIP
'people-walking.jpg'
Source code in src/supervision/assets/downloader.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def download_assets(
    asset_name: Assets | str,
    directory: str | Path | None = None,
) -> str:
    """
    Download a specified asset if it doesn't already exist or is corrupted.

    Args:
        asset_name: The name or type of the asset to be downloaded.
        directory: Optional output directory. Defaults to the current working
            directory for backward compatibility.

    Returns:
        The downloaded asset path. When `directory` is omitted, this preserves
        the historical filename-only return value.

    Example:
        ```pycon
        >>> from supervision.assets import download_assets, ImageAssets, VideoAssets
        >>> download_assets(VideoAssets.VEHICLES)  # doctest: +SKIP
        'vehicles.mp4'

        >>> download_assets(ImageAssets.PEOPLE_WALKING)  # doctest: +SKIP
        'people-walking.jpg'

        ```
    """

    filename = asset_name.filename if isinstance(asset_name, Assets) else asset_name
    if directory is None:
        destination = Path.cwd() / filename
        check_target: str | Path = filename
        return_value = filename
    else:
        destination_directory = Path(directory).expanduser().resolve()
        destination = destination_directory / filename
        check_target = str(destination)
        return_value = str(destination)

    if filename in MEDIA_ASSETS:
        original_md5_hash = MEDIA_ASSETS[filename][1]
        if not Path(check_target).exists():
            logger.info("Downloading %s assets", filename)
            _download_verified_asset(
                filename=filename,
                original_md5_hash=original_md5_hash,
                destination=destination,
                check_target=check_target,
            )
        else:
            if not is_md5_hash_matching(check_target, original_md5_hash):
                logger.warning("File corrupted. Re-downloading...")
                os.remove(check_target)
                _download_verified_asset(
                    filename=filename,
                    original_md5_hash=original_md5_hash,
                    destination=destination,
                    check_target=check_target,
                )

            logger.info("%s asset download complete.", filename)
    else:
        valid_assets = ", ".join(filename for filename in MEDIA_ASSETS.keys())
        raise ValueError(
            f"Invalid asset. It should be one of the following: {valid_assets}."
        )

    return return_value

VideoAssets

supervision.assets.list.VideoAssets

Bases: Assets

Each member of this class represents a video asset. The value associated with each member has a filename and hash of the video. File names and links can be seen below.

Asset Video Filename Video URL
VEHICLES vehicles.mp4 Link
MILK_BOTTLING_PLANT milk-bottling-plant.mp4 Link
VEHICLES_2 vehicles-2.mp4 Link
GROCERY_STORE grocery-store.mp4 Link
SUBWAY subway.mp4 Link
MARKET_SQUARE market-square.mp4 Link
PEOPLE_WALKING people-walking.mp4 Link
BEACH beach-1.mp4 Link
BASKETBALL basketball-1.mp4 Link
SKIING skiing.mp4 Link
Source code in src/supervision/assets/list.py 
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
class VideoAssets(Assets):
    """
    Each member of this class represents a video asset. The value associated with each
    member has a filename and hash of the video. File names and links can be seen below.

    | Asset                  | Video Filename             | Video URL                                                                             |
    |------------------------|----------------------------|---------------------------------------------------------------------------------------|
    | `VEHICLES`             | `vehicles.mp4`             | [Link](https://media.roboflow.com/supervision/video-examples/vehicles.mp4)            |
    | `MILK_BOTTLING_PLANT`  | `milk-bottling-plant.mp4`  | [Link](https://media.roboflow.com/supervision/video-examples/milk-bottling-plant.mp4) |
    | `VEHICLES_2`           | `vehicles-2.mp4`           | [Link](https://media.roboflow.com/supervision/video-examples/vehicles-2.mp4)          |
    | `GROCERY_STORE`        | `grocery-store.mp4`        | [Link](https://media.roboflow.com/supervision/video-examples/grocery-store.mp4)       |
    | `SUBWAY`               | `subway.mp4`               | [Link](https://media.roboflow.com/supervision/video-examples/subway.mp4)              |
    | `MARKET_SQUARE`        | `market-square.mp4`        | [Link](https://media.roboflow.com/supervision/video-examples/market-square.mp4)       |
    | `PEOPLE_WALKING`       | `people-walking.mp4`       | [Link](https://media.roboflow.com/supervision/video-examples/people-walking.mp4)      |
    | `BEACH`                | `beach-1.mp4`              | [Link](https://media.roboflow.com/supervision/video-examples/beach-1.mp4)             |
    | `BASKETBALL`           | `basketball-1.mp4`         | [Link](https://media.roboflow.com/supervision/video-examples/basketball-1.mp4)        |
    | `SKIING`               | `skiing.mp4`               | [Link](https://media.roboflow.com/supervision/video-examples/skiing.mp4)              |
    """  # noqa: E501 // docs

    VEHICLES = ("vehicles.mp4", "8155ff4e4de08cfa25f39de96483f918")
    MILK_BOTTLING_PLANT = (
        "milk-bottling-plant.mp4",
        "9e8fb6e883f842a38b3d34267290bdc7",
    )
    VEHICLES_2 = ("vehicles-2.mp4", "830af6fba21ffbf14867a7fea595937b")
    GROCERY_STORE = ("grocery-store.mp4", "48608fb4a8981f1c2469fa492adeec9c")
    SUBWAY = ("subway.mp4", "453475750691fb23c56a0cffef089194")
    MARKET_SQUARE = ("market-square.mp4", "859179bf4a21f80a8baabfdb2ed716dc")
    PEOPLE_WALKING = ("people-walking.mp4", "0574c053c8686c3f1dc0aa3743e45cb9")
    BEACH = ("beach-1.mp4", "4175d42fec4d450ed081523fd39e0cf8")
    BASKETBALL = ("basketball-1.mp4", "60d94a3c7c47d16f09d342b088012ecc")
    SKIING = ("skiing.mp4", "d30987cbab1bbc5934199cdd1b293119")

ImageAssets

supervision.assets.list.ImageAssets

Bases: Assets

Each member of this enum represents a image asset. The value associated with each member is the filename of the image.

Asset Image Filename Video URL
PEOPLE_WALKING people-walking.jpg Link
SOCCER soccer.jpg Link
Source code in src/supervision/assets/list.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class ImageAssets(Assets):
    """
    Each member of this enum represents a image asset. The value associated with each
    member is the filename of the image.

    | Asset              | Image Filename         | Video URL                                                                             |
    |--------------------|------------------------|---------------------------------------------------------------------------------------|
    | `PEOPLE_WALKING`   | `people-walking.jpg`   | [Link](https://media.roboflow.com/supervision/image-examples/people-walking.jpg)      |
    | `SOCCER`           | `soccer.jpg`           | [Link](https://media.roboflow.com/supervision/image-examples/soccer.jpg)              |

    """  # noqa: E501 // docs

    PEOPLE_WALKING = ("people-walking.jpg", "e6bda00b47f2908eeae7df86ef995dcd")
    SOCCER = ("soccer.jpg", "0f5a4b98abf3e3973faf9e9260a7d876")

Comments