{"id":13807781,"url":"https://github.com/mitmul/pynvvl","last_synced_at":"2025-10-07T04:32:01.182Z","repository":{"id":62582161,"uuid":"131919461","full_name":"mitmul/pynvvl","owner":"mitmul","description":"A Python wrapper of NVIDIA Video Loader (NVVL) with CuPy for fast video loading with Python","archived":true,"fork":false,"pushed_at":"2020-05-04T12:40:12.000Z","size":1360,"stargazers_count":101,"open_issues_count":12,"forks_count":12,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-24T20:03:09.995Z","etag":null,"topics":["cuda","cupy","gpu","numpy","nvidia-video-loader","nvvl","python","video","video-processing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitmul.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-03T00:17:55.000Z","updated_at":"2024-02-24T15:06:05.000Z","dependencies_parsed_at":"2022-11-03T22:01:29.713Z","dependency_job_id":null,"html_url":"https://github.com/mitmul/pynvvl","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitmul%2Fpynvvl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitmul%2Fpynvvl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitmul%2Fpynvvl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitmul%2Fpynvvl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitmul","download_url":"https://codeload.github.com/mitmul/pynvvl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235586527,"owners_count":19014035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cuda","cupy","gpu","numpy","nvidia-video-loader","nvvl","python","video","video-processing"],"created_at":"2024-08-04T01:01:30.263Z","updated_at":"2025-10-07T04:31:55.865Z","avatar_url":"https://github.com/mitmul.png","language":"Python","funding_links":[],"categories":["Video Processing"],"sub_categories":[],"readme":"PyNVVL\n======\n[![pypi-pynvvl-cuda80](https://img.shields.io/pypi/v/pynvvl-cuda80.svg)](https://pypi.org/project/pynvvl-cuda80)\n[![pypi-pynvvl-cuda90](https://img.shields.io/pypi/v/pynvvl-cuda90.svg)](https://pypi.org/project/pynvvl-cuda90)\n[![pypi-pynvvl-cuda91](https://img.shields.io/pypi/v/pynvvl-cuda91.svg)](https://pypi.org/project/pynvvl-cuda91)\n[![pypi-pynvvl-cuda92](https://img.shields.io/pypi/v/pynvvl-cuda92.svg)](https://pypi.org/project/pynvvl-cuda92)\n[![GitHub license](https://img.shields.io/github/license/mitmul/pynvvl.svg)](https://github.com/mitmul/pynvvl)\n\nPyNVVL is a thin wrapper of [NVIDIA Video Loader (NVVL)](https://github.com/NVIDIA/nvvl). This package enables you to load videos directly to GPU memory and access them as [CuPy](https://github.com/cupy/cupy) ndarrays with zero copy. The pre-built binaries of PyNVVL include NVVL itself, so you do not need to install NVVL.\n\n## Requirements\n\n- CUDA 8.0, 9.0, 9.1, or 9.2\n- Python 2.7.6+, 3.4.7+, 3.5.1+, or 3.6.0+\n- [CuPy](https://github.com/cupy/cupy) v4.5.0\n\n## Tested Environment\n\n- Ubuntu 16.04\n- Python 2.7.6+, 3.4.7+, 3.5.1+, and 3.6.0+\n- CUDA 8.0, 9.0, 9.1, and 9.2\n\n## Install the pre-built binary\n\nPlease choose a right package depending on your CUDA version.\n\n```bash\n# [For CUDA 8.0]\npip install pynvvl-cuda80\n\n# [For CUDA 9.0]\npip install pynvvl-cuda90\n\n# [For CUDA 9.1]\npip install pynvvl-cuda91\n\n# [For CUDA 9.2]\npip install pynvvl-cuda92\n```\n\n## Usage\n\n```python\nimport pynvvl\nimport matplotlib.pyplot as plt\n\n# Create NVVLVideoLoader object\nloader = pynvvl.NVVLVideoLoader(device_id=0, log_level='error')\n\n# Show the number of frames in the video\nn_frames = loader.frame_count('examples/sample.mp4')\nprint('Number of frames:', n_frames)\n\n# Load a video and return it as a CuPy array\nvideo = loader.read_sequence(\n    'examples/sample.mp4',\n    horiz_flip=True,\n    scale_height=512,\n    scale_width=512,\n    crop_y=60,\n    crop_height=385,\n    crop_width=512,\n    scale_method='Linear',\n    normalized=True\n)\n\nprint(video.shape)  # =\u003e (91, 3, 385, 512): (n_frames, channels, height, width)\nprint(video.dtype)  # =\u003e float32\n\n# Get the first frame as numpy array\nframe = video[0].get()\nframe = frame.transpose(1, 2, 0)\n\nplt.imshow(frame)\nplt.savefig('examples/sample.png')\n```\n\n![](https://github.com/mitmul/pynvvl/raw/master/examples/sample.png)\n\nThis video is `flickr-2-6-3-3-5-2-7-6-5626335276_4.mp4` from the Moments-In-Time dataset.\n\nNote that cropping is performed after scaling. In the above example, NVVL performs scaling up from 256 x 256 to 512 x 512 first, then cropping the region [60:60 + 385, 0:512]. See the following section to know more about the transformation options.\n\n## VideoLoader options\n\nPlease specify the GPU device id when you create a `NVVLVideoLoader` object.\nYou can also specify the logging level with the argument `log_level` for the constructor of `NVVLVideoLoader`.\n\n```\nWrapper of NVVL VideoLoader\n\n    Args:\n        device_id (int): Specify the device id used to load a video.\n        log_level (str): Logging level which should be either 'debug',\n            'info', 'warn', 'error', or 'none'.\n            Logs with levels \u003e= log_level is shown. The default is 'warn'.\n```\n\n## Transformation Options\n\n`pynvvl.NVVLVideoLoader.read_sequence` can take some options to specify the color space, the value range, and what transformations you want to perform to the video.\n\n```\nLoads the video from disk and returns it as a CuPy ndarray.\n\n    Args:\n        filename (str): The path to the video.\n        frame (int): The initial frame number of the returned sequence.\n            Default is 0.\n        count (int): The number of frames of the returned sequence.\n            If it is None, whole frames of the video are loaded.\n        channels (int): The number of color channels of the video.\n            Default is 3.\n        scale_height (int): The height of the scaled video.\n            Note that scaling is performed before cropping.\n            If it is 0 no scaling is performed. Default is 0.\n        scale_width (int): The width of the scaled video.\n            Note that scaling is performed before cropping.\n            If it is 0, no scaling is performed. Default is 0.\n        crop_x (int): Location of the crop within the scaled frame.\n            Must be set such that crop_y + height \u003c= original height.\n            Default is 0.\n        crop_y (int): Location of the crop within the scaled frame.\n            Must be set such that crop_x + width \u003c= original height.\n            Default is 0.\n        crop_height (int): The height of cropped region of the video.\n            If it is None, no cropping is performed. Default is None.\n        crop_width (int): The width of cropped region of the video.\n            If it is None, no cropping is performed. Default is None.\n        scale_method (str): Scaling method. It should be either of\n            'Nearest' or 'Lienar'. Default is 'Linear'.\n        horiz_flip (bool): Whether horizontal flipping is performed or not.\n            Default is False.\n        normalized (bool): If it is True, the values of returned video is\n            normalized into [0, 1], otherwise the value range is [0, 255].\n            Default is False.\n        color_space (str): The color space of the values of returned video.\n            It should be either 'RGB' or 'YCbCr'. Default is 'RGB'.\n        chroma_up_method (str): How the chroma channels are upscaled from\n            yuv 4:2:0 to 4:4:4. It should be 'Linear' currently.\n        out (cupy.ndarray): Alternate output array where place the result.\n            It must have the same shape and the dtype as the expected\n            output, and its order must be C-contiguous.\n```\n\n## How to build\n\n### Build wheels using Docker: \n\nRequirements:\n\n- Docker\n- nvidia-docker (v1/v2)\n\n```\nbash docker/build_wheels.sh\n```\n\n### Setup development environment without Docker:\n\nThe `setup.py` script searches for necessary libraries.\n\nRequirements: the following libraries should be available in `LIBRARY_PATH`.\n\n- libnvvl.so\n- libavformat.so.57\n- libavfilter.so.6\n- libavcodec.so.57\n- libavutil.so.55\n\nYou can build `libnvvl.so` in the `nvvl` repository. Follow the instructions\nof `nvvl` library. The `build` directory must be in `LIBRARY_PATH`.\n\nThe other three libraries are available as packages in Ubuntu 16.04.\nThey are installed under `/usr/lib/x86_64-linux-gnu`, so they must be in `LIBRARY_PATH` as well.\n\n```\npython setup.py develop\npython setup.py bdist_wheel\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitmul%2Fpynvvl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitmul%2Fpynvvl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitmul%2Fpynvvl/lists"}