# siti-tools
[](https://github.com/VQEG/siti-tools/actions/workflows/python-package.yml)
SI/TI calculation tools.
Calculate spatial information (SI) and temporal information (TI).
**⚠️ Note: This is the main branch of the project. For the legacy version of SI/TI, see [the `legacy` branch](https://github.com/VQEG/siti-tools/tree/legacy)**.
Contents:
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Command Line Usage](#command-line-usage)
- [Detailed Options](#detailed-options)
- [Output](#output)
- [API Usage](#api-usage)
- [Testing](#testing)
- [About](#about)
- [What is SI/TI?](#what-is-siti)
- [What is the purpose of this activity?](#what-is-the-purpose-of-this-activity)
- [Contributors](#contributors)
- [Acknowledgements](#acknowledgements)
- [Related Projects](#related-projects)
- [License](#license)
## Requirements
- Python 3.8 or higher
- FFmpeg libraries (v5 or higher)
Under Ubuntu, to get ffmpeg libraries:
sudo apt update -qq && \
sudo apt install \
libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev \
libavfilter-dev libswscale-dev libavresample-dev
Under macOS, it is recommended to install ffmpeg via [Homebrew](https://brew.sh):
brew install ffmpeg
## Installation
Directly install from Git:
```bash
pip3 install --user git+https://github.com/VQEG/siti-tools
```
Or clone this repository and then:
```bash
pip3 install --user .
```
## Usage
This tool can be used via command line or through a Python API.
### Command Line Usage
After installation, simply run:
```
siti-tools /path/to/input/file.mp4
```
to run the tool. It will print JSON output containing info about SI/TI values and other statistics to `stdout`.
You can pass any video file with a container that can be read by FFmpeg. For YUV files, see below.
:warning: We are currently observing a bug with some videos that manifests in an error ("ValueError: cannot reshape array of size …"). See [this issue](https://github.com/VQEG/siti-tools/issues/17) for details. If you encounter this error, please use Y4M files as input instead.
This works for 8-bit standard dynamic range (SDR) content, which will apply to most input files. However, this tool does not automatically handle input that is not 8-bit SDR content. For more info on that, see below.
#### Usage with YUV or Y4M files
We don't recommend working with raw YUV files, as they do not carry the metadata required to decode them. Use Y4M files or any other container format that can be read by FFmpeg.
To convert YUV into Y4M, use the basic command:
```bash
ffmpeg -f rawvideo -pix_fmt yuv420p -framerate 24 -video_size 1920x1080 -i input.yuv -f yuv4mpegpipe output.y4m
```
Adapt the parameters to your input file (i.e., the pixel format, framerate, and resolution).
NOTE: If you are working with 10-bit content (e.g., if your input pixel format is `yuv420p10le`), you must add the `-strict -1` flag to the command above:
```bash
ffmpeg -f rawvideo -pix_fmt yuv420p10le -framerate 24 -video_size 1920x1080 -i input.yuv -f yuv4mpegpipe -strict -1 output.y4m
```
If you just want to convert an existing (e.g. MP4) file into Y4M, use:
```bash
ffmpeg -i input.mp4 -pix_fmt yuv420p output.y4m
```
#### Usage for > 8-bit Content
To deal with input with more than 8-bit, you can choose the bit depth:
```
siti-tools /path/to/input/file.mov --bit-depth 10
```
To check if your input really has 10 bit, you can use `ffprobe`:
```
ffprobe -v error -select_streams v:0 -show_streams test/videos/ParkJoy_480x270_50.y4m -of compact=p=0:nk=1 -show_entries stream=pix_fmt
```
If the pixel format ends with `p10`, you have a 10-bit sequence.
#### Full vs. Limited Range
If your input has full range values (0–255) instead of limited range (16–235), you must specify the following flag:
```
siti-tools /path/to/input/file.mp4 --color-range full
```
This ensures that the values are properly scaled. If you pass a full range content to the tool without specifying the flag, it will print an error.
#### HDR Usage
This tool handles HDR content encoded in HLG or HDR10. For example, if you have a HLG-encoded file with 10 bit per channel, you should call:
```
siti-tools /path/to/input/file-HLG.mov --hdr-mode hlg --bit-depth 10
```
Likewise, if you have an HDR10-encoded file:
```
siti-tools /path/to/input/file-HDR10.mp4 --hdr-mode hdr10 --bit-depth 10
```
You can further tune the HDR parameters. The most important ones are the assumed display luminance values, which can be set via `--l-max` and `--l-min`. We have chosen sane defaults here, but depending on your application you may want to override them.
### Detailed Options
Run `siti-tools -h` for a full list of command line options:
```
usage: siti-tools [-h] [-s SETTINGS] [-n NUM_FRAMES] [--max-frames MAX_FRAMES] [-f {json,csv}] [-v]
[--show-histogram] [-q] [-c {pq,pu21}] [-m {sdr,hdr10,hlg}] [-b {8,10,12}]
[-r {limited,full}] [--legacy] [-e {bt1886,inv_srgb}] [-g GAMMA] [--l-max L_MAX]
[--l-min L_MIN] [--pu21-mode {banding,banding_glare,peaks,peaks_glare}]
input
optional arguments:
-h, --help show this help message and exit
input/output:
input Input file, can be Y4M or file in FFmpeg-readable container
-s SETTINGS, --settings SETTINGS
Load settings from previous JSON results file instead of using CLI args
-n NUM_FRAMES, --num-frames NUM_FRAMES
Number of frames to calculate, must be >= 2 (default: unlimited)
--max-frames MAX_FRAMES
Overall number of frames, useful for providing better time estimates from
the command-line
-f {json,csv}, --format {json,csv}
Choose the output format (default: json)
-v, --verbose Show debug info on stderr (default: False)
--show-histogram Show a histogram for the first frame (computation-intensive, implies
--verbose) (default: False)
-q, --quiet Do not show progress bar (default: False)
Video/SI options:
-c {pq,pu21}, --calculation-domain {pq,pu21}
Select calculation domain (default: pq)
-m {sdr,hdr10,hlg}, --hdr-mode {sdr,hdr10,hlg}
Select HDR mode (default: sdr)
-b {8,10,12}, --bit-depth {8,10,12}
Select bit depth (default: 8)
-r {limited,full}, --color-range {limited,full}
Specify limited or full range (default: limited)
--legacy Use legacy mode, disables all other features except for range adjustment
(default: False)
SDR options:
-e {bt1886,inv_srgb}, --eotf-function {bt1886,inv_srgb}
Specify the EOTF function for converting SDR to HDR (default: bt1886)
-g GAMMA, --gamma GAMMA
Specify gamma for BT.1886 function (default: 2.4)
Display options:
--l-max L_MAX Nominal peak luminance of the display in cd/m2 for achromatic pixels
(default: 300 for SDR, 1000.0 for HDR)
--l-min L_MIN Display luminance for black in cd/m2 (default: 0.1 for SDR, 0.01 for HDR)
PU21 options:
--pu21-mode {banding,banding_glare,peaks,peaks_glare}
Specify mode for PU21 (default: banding)
```
### Output
The tool will output a valid JSON object on `stdout`, with SI and TI scores contained in an array.
To redirect the output to a file, use shell redirection:
```bash
siti-tools input1.mp4 > input1.json
```
Note that the first frame has no TI value by definition, so a file with two frames would produce the following output:
```json
{
"si": [
4.678114135021466,
4.690539260164495
],
"ti": [
0.33096454208633247
],
"settings": {
"calculation_domain": "pq",
"hdr_mode": "sdr",
"bit_depth": 8,
"color_range": "full",
"eotf_function": "bt1886",
"l_max": 300,
"l_min": 0.1,
"gamma": 2.4,
"pu21_mode": "banding",
"legacy": false,
"version": "0.1.2"
},
"input_file": "FourPeople_480x270_60.y4m"
}
```
In the `settings` key, you will find information on how the calculation was done. This is useful for allowing values to be reproduced. You can use these settings for further calculation runs. For instance, if you want to use the settings used for `input1` for `input2`, run the following:
```
siti-tools input1.mp4 > input1.json
siti-tools input2.mp4 --settings input1.json > input2.json
```
You can also generate CSV output, which will contain fewer columns but is easier to parse.
```bash
siti-tools input1.mp4 --format csv > input1.csv
siti-tools input2.mp4 --settings input1.json --format csv > input2.csv
```
The output might look like this:
```
input_file,n,si,ti
foreman_cif.y4m,1,39.342,
foreman_cif.y4m,2,39.229,5.007
foreman_cif.y4m,3,39.224,5.291
foreman_cif.y4m,4,39.458,5.08
foreman_cif.y4m,5,39.212,4.854
foreman_cif.y4m,6,39.214,4.22
foreman_cif.y4m,7,39.26,3.95
foreman_cif.y4m,8,39.351,4.267
foreman_cif.y4m,9,39.349,4.915
foreman_cif.y4m,10,39.504,4.77
```
Note that the first TI value is empty by definition.
There is also a handy conversion utility to help you convert JSON to CSV files after you have calculated the scores.
```bash
utils/json-to-csv.py input.json input.csv
```
### API Usage
The tools expose the calculation functions via an API.
For instance, you can directly use the SI/TI functions:
```python
import numpy as np
from siti_tools.siti import SiTiCalculator # noqa: E402
frame_data = ... # some numpy array
previous_frame_data = ... # some other numpy array
si_value = SiTiCalculator.si(frame_data)
ti_value = SiTiCalculator.ti(frame_data, previous_frame_data)
```
See the `test/generate_raw_siti_values.py` file for an example of how to use those.
Or, you can use the calculator class to do the conversions required for higher bit depths and HDR:
```python
import json
from siti_tools.siti import ColorRange, SiTiCalculator
si_ti_calculator = SiTiCalculator(
color_range=ColorRange.LIMITED,
# ... other settings go here
)
si_ti_calculator.calculate(
path_to_input_file,
num_frames=3, # only calculate 3 frames
)
results = si_ti_calculator.get_results()
print(json.dumps(results, indent=4))
```
See the `siti_tools/__main__.py` file on how to specify all options.
## Testing
This repo provides a set of test sequences with expected output values that you can verify against.
First, install the dev dependencies:
```
pip3 install -r requirements.dev.txt
```
Generate the sequences:
```bash
cd test && ./generate_ffmpeg_sources.sh && cd -
```
Then run:
```bash
python3 -m pytest test/test.py -n auto
```
The `-n auto` flag distributes the test to all cores. Remove it if you want to capture stdout with `-s`.
## About
### What is SI/TI?
The following info is given about SI / TI in [ITU-T Recommendation P.910](https://www.itu.int/rec/T-REC-P.910) (10/2023) – "Subjective video quality assessment methods for multimedia applications". This is the most recent version of the document at the time of writing. Version 07/2022 has introduced significant changes to the SI/TI calculation, which are reflected in this repository.
> **Spatial Information**: A measure that indicates the amount of spatial detail in a picture. It is usually higher for more spatially complex scenes. It is not meant to be a measure of entropy nor is it associated with the information defined in communication theory
> **Temporal information**: A measure that indicates the number of temporal changes of a video sequence. It is usually higher for high motion sequences. It is not meant to be a measure of entropy nor associated with the information defined in communication theory.
SI and TI are based on the Sobel filter, which is a simple edge detector. The Sobel filter is applied to the luminance channel of the input video, and the resulting values are aggregated to a single value. For a detailed calculation, see Annex B of ITU-T Rec. P.910 (10/2023)
Further, Clause 7.8 states:
> The selection of test scenes is an important issue. In particular, the spatial information (SI) and temporal information (TI) of the scenes are critical parameters. These parameters play a crucial role in determining the amount of video compression that is possible (compressibility), and consequently, the level of impairment that is suffered when the scene is transmitted over a fixed-rate digital transmission service channel. Fair and relevant video test scenes must be chosen such that their SI and TI is consistent with the video services that the digital transmission service channel was intended to provide. The set of test scenes should span the full range of SI and TI of interest to users of the devices under test.
Regarding the aggregation of SI/TI values, Clause 7.8.4 states:
> Multiple SI and TI values per sequence may be aggregated into single numbers for SI and TI, respectively, by applying appropriate statistical measures such as the minimum, maximum, median, average, or percentiles.
It is recommended to use the average as an aggregation measure.
If you have used a previous version of SI/TI, please consider:
> Note that in the previous versions of Recommendation ITU-T P.910, the respective maximum value was recommended as aggregated score for SI and TI. (…) If the resulting SI and TI values are being compared to those provided in publications or with publicly available databases, deviations may stem from the previously recommended usage of the maximum.
For further information, please refer to the ITU-T Rec. P.910 document.
### What is the purpose of this activity?
The [No-Reference Metrics (NORM)](https://www.its.bldrdoc.gov/vqeg/projects/no-reference-metrics-norm.aspx) working group of the [Video Quality Expert Group (VQEG)](https://www.its.bldrdoc.gov/vqeg/vqeg-home.aspx) has investigated the Spatial Information (SI) and Temporal Information (TI) indicators defined in ITU-T Rec. P.910.
SI and TI have been frequently used by the community to classify sets of video sequences or video databases, primarily for checking that the used material spans an appropriate range of spatiotemporal complexity before further processing the sequences (e.g., encoding them, presenting them to subjects). Since they are easy and quick to calculate, SI/TI are still very relevant today.
VQEG identified several limitations with the current definition of SI/TI, including the following:
- It was not specified how to handle video with limited (16-235) vs. full range (0-255).
- The applicable range of input bit depths (bits per channel) was not specified. This means that it was unclear how to handle content with different bit depths, in particular when comparing sequences of varying bit depth.
- It was undefined how to handle high dynamic range (HDR) content, where the luminance information might be encoded differently compared to standard dynamic range (SDR).
The overall aims of this activity were the following:
- Providing an updated set of calculation functions for SI and TI that cover limited/full range content, higher bit depths, and HDR sequences
- Providing a set of test sequences and expected values (i.e., test vectors) in order to allow others to reproduce the results and verify their own implementation
- Updating the ITU-T Rec. P.910 text to incorporate the new calculation functions
Since ITU-T Rec. P.910 is a normative document, the updated text was be submitted to ITU-T Study Group 12 for approval and subsequently published in the ITU-T Rec. P.910 document version 07/2022.
### Contributors
Code contributors:
- Werner Robitza
- Lukas Krasula
Many others have contributed to the discussion and updating of the ITU-T document. Thank you to all of them!
### Acknowledgements
If you use this software in your research, please include link to this repository.
### Related Projects
- [TelecommunicationTelemediaAssessment/SITI](https://github.com/Telecommunication-Telemedia-Assessment/SITI): Legacy calculations of OpenCV and Python version of SI/TI, values may not necessarily correspond.
- [NabajeetBarman/SI-TI](https://github.com/NabajeetBarman/SI-TI): MATLAB version of SI/TI calculation, values verified against this repository.
### License
MIT License
siti_tools, Copyright (c) 2021-2023 Werner Robitza, Lukas Krasula
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# Changelog
## v0.3.0 (2024-08-01)
* Chore: update dependencies.
* Fix the implementation of the HLG EOTF function (#23)
* Fix the implementation of the HLG EOTF function
* Fix the tests for HLG
---------
## v0.2.3 (2023-12-18)
* Update dependencies to include release deps.
* Bump dependencies.
* Update readme.
* Fix issue #20 (#21)
* Remove `-c:v copy` from the FFmpeg command putting YUV content in a Y4M container.
Mention that `-strict -1` is necessary fot 10-bit pixel formats.
* Make sure the example for 10-bit pixel format actually uses a 10-bit pixel format
* Fix README installation instructions.
* Update readme, addresses #17.
* Fix ffmpeg libs.
## v0.2.2 (2023-06-27)
* Update dependencies.
* Update test decode function.
* Explain usage with YUV files.
* Add version support to CLI.
* Add utility for converting JSON output to CSV.
* Error on unsupported frame formats.
## v0.2.1 (2022-05-13)
* Fix console script installation.
* Fix link in setup.py.
* Update README.
## v0.2.0 (2022-05-03)
* Check for pypandoc on release.
* Fix CI setup (#14)
* CI: support only Python 3.8 and higher.
* Fix broken link.
* Merge branch 'siti2020'
* Update README links.
* Minor code style.
* Code formatting and note.
* ITU-T --> ITU-R.
* Improve docs and tests.
* Add profiling test.
* Update README.md.
* Update release script.
* Add poetry environment.
* Type error.
* Improve logs.
* Fix logs.
* Add legacy mode.
* Format code.
* Update README.
* Add option for total frame count in tqdm bar.
* Update for newer ffmpeg, update pip.
* Fix call of OETF, fix tests.
* Remove superfluous scaling for PU21.
* Fix issue with CSV output.
* Add type casts for type checks.
* Make logger global.
* Update README.
* Add histogram plots.
* Fix formula for EOTF output.
* Add progress bar/iterator.
* Add CSV output functionality.
* Add logging and fix error with l_min/l_max conversion.
* Add further test content.
* Fix unit tests.
* Update README and docs.
* Fixes for 10bpp reading, fixes #12.
* Update requirements.
* Update test set, fix reading function for Y4M.
* Update test functions.
* Print more info during tests.
* Remove unused import.
* Update dev requirements.
* Fix test functions.
- use JSON for testing the complex class functions
- fall back to one video for testing the simple functions
- prepare using other videos for testing
* Limit download size of test videos.
* Add options to select PU21.
* Remove comment.
* Add typing support for PU21.
* Add oetf_pu21.
* Simplify test functions.
* Add note on input values.
* Update requirements.
* Remove import.
* Update test suite.
* Add CLI documentation and entry point.
* Allow reusing settings from previous run, fixes #10.
* Convert to 0-1 range.
This converts values into 0-1 for EOTF/OETF handling, and then scales everything
up to 0-255 again for output, regardless of original bit depth.
* Add new class-based calculation and results.
add more CLI flags
rework classes
* Update LICENSE and README.
* Implementation of eotf_1886, eotf_inv_srgb, eotf_hlg, and oetf_pq.
* Implement first conversion functions.
* Update README links.
## v0.1.3 (2022-03-14)
* Add method to specify full range in read_container.
* Link to development branch.
* Update docs.
## v0.1.2 (2021-05-14)
* Add documentation for method.
* Fix link.
* Update README.md.
* Update README.md.
* Output frame data as integers.
## v0.1.1 (2021-05-13)
* Add warning for full range passed to limited range function, fixes #2.
* Add new test video, improve test harness.
## v0.1.0 (2021-03-08)
* Add status badge.
* Bump Python support.
* Add GitHub Actions CI (#1)
* Fix flake8 errors.
## v0.0.2 (2021-03-08)
* Fix setup.py.
* Add CHANGELOG.
## v0.0.1 (2021-03-08)
* Improve README.
* Initial commit.
* Initial commit.
Raw data
{
"_id": null,
"home_page": "https://github.com/VQEG/siti-tools",
"name": "siti-tools",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "video, spatial information, temporal information",
"author": "Werner Robitza",
"author_email": "werner.robitza@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0b/37/af3abdd07e9630dc2faabf94bba8a35d29bf0a59838ab5da2ecb2b4a7a64/siti-tools-0.3.0.tar.gz",
"platform": null,
"description": "# siti-tools\n\n[](https://github.com/VQEG/siti-tools/actions/workflows/python-package.yml)\n\nSI/TI calculation tools.\n\nCalculate spatial information (SI) and temporal information (TI).\n\n**\u26a0\ufe0f Note: This is the main branch of the project. For the legacy version of SI/TI, see [the `legacy` branch](https://github.com/VQEG/siti-tools/tree/legacy)**.\n\nContents:\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Command Line Usage](#command-line-usage)\n - [Detailed Options](#detailed-options)\n - [Output](#output)\n - [API Usage](#api-usage)\n- [Testing](#testing)\n- [About](#about)\n - [What is SI/TI?](#what-is-siti)\n - [What is the purpose of this activity?](#what-is-the-purpose-of-this-activity)\n - [Contributors](#contributors)\n - [Acknowledgements](#acknowledgements)\n - [Related Projects](#related-projects)\n - [License](#license)\n\n## Requirements\n\n- Python 3.8 or higher\n- FFmpeg libraries (v5 or higher)\n\nUnder Ubuntu, to get ffmpeg libraries:\n\n sudo apt update -qq && \\\n sudo apt install \\\n libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev \\\n libavfilter-dev libswscale-dev libavresample-dev\n\nUnder macOS, it is recommended to install ffmpeg via [Homebrew](https://brew.sh):\n\n brew install ffmpeg\n\n## Installation\n\nDirectly install from Git:\n\n```bash\npip3 install --user git+https://github.com/VQEG/siti-tools\n```\n\nOr clone this repository and then:\n\n```bash\npip3 install --user .\n```\n\n## Usage\n\nThis tool can be used via command line or through a Python API.\n\n### Command Line Usage\n\nAfter installation, simply run:\n\n```\nsiti-tools /path/to/input/file.mp4\n```\n\nto run the tool. It will print JSON output containing info about SI/TI values and other statistics to `stdout`.\n\nYou can pass any video file with a container that can be read by FFmpeg. For YUV files, see below.\n\n:warning: We are currently observing a bug with some videos that manifests in an error (\"ValueError: cannot reshape array of size \u2026\"). See [this issue](https://github.com/VQEG/siti-tools/issues/17) for details. If you encounter this error, please use Y4M files as input instead.\n\nThis works for 8-bit standard dynamic range (SDR) content, which will apply to most input files. However, this tool does not automatically handle input that is not 8-bit SDR content. For more info on that, see below.\n\n#### Usage with YUV or Y4M files\n\nWe don't recommend working with raw YUV files, as they do not carry the metadata required to decode them. Use Y4M files or any other container format that can be read by FFmpeg.\n\nTo convert YUV into Y4M, use the basic command:\n\n```bash\nffmpeg -f rawvideo -pix_fmt yuv420p -framerate 24 -video_size 1920x1080 -i input.yuv -f yuv4mpegpipe output.y4m\n```\n\nAdapt the parameters to your input file (i.e., the pixel format, framerate, and resolution).\n\nNOTE: If you are working with 10-bit content (e.g., if your input pixel format is `yuv420p10le`), you must add the `-strict -1` flag to the command above:\n\n```bash\nffmpeg -f rawvideo -pix_fmt yuv420p10le -framerate 24 -video_size 1920x1080 -i input.yuv -f yuv4mpegpipe -strict -1 output.y4m\n```\n\nIf you just want to convert an existing (e.g. MP4) file into Y4M, use:\n\n```bash\nffmpeg -i input.mp4 -pix_fmt yuv420p output.y4m\n```\n\n#### Usage for > 8-bit Content\n\nTo deal with input with more than 8-bit, you can choose the bit depth:\n\n```\nsiti-tools /path/to/input/file.mov --bit-depth 10\n```\n\nTo check if your input really has 10 bit, you can use `ffprobe`:\n\n```\nffprobe -v error -select_streams v:0 -show_streams test/videos/ParkJoy_480x270_50.y4m -of compact=p=0:nk=1 -show_entries stream=pix_fmt\n```\n\nIf the pixel format ends with `p10`, you have a 10-bit sequence.\n\n#### Full vs. Limited Range\n\nIf your input has full range values (0\u2013255) instead of limited range (16\u2013235), you must specify the following flag:\n\n```\nsiti-tools /path/to/input/file.mp4 --color-range full\n```\n\nThis ensures that the values are properly scaled. If you pass a full range content to the tool without specifying the flag, it will print an error.\n\n#### HDR Usage\n\nThis tool handles HDR content encoded in HLG or HDR10. For example, if you have a HLG-encoded file with 10 bit per channel, you should call:\n\n```\nsiti-tools /path/to/input/file-HLG.mov --hdr-mode hlg --bit-depth 10\n```\n\nLikewise, if you have an HDR10-encoded file:\n\n```\nsiti-tools /path/to/input/file-HDR10.mp4 --hdr-mode hdr10 --bit-depth 10\n```\n\nYou can further tune the HDR parameters. The most important ones are the assumed display luminance values, which can be set via `--l-max` and `--l-min`. We have chosen sane defaults here, but depending on your application you may want to override them.\n\n### Detailed Options\n\nRun `siti-tools -h` for a full list of command line options:\n\n```\nusage: siti-tools [-h] [-s SETTINGS] [-n NUM_FRAMES] [--max-frames MAX_FRAMES] [-f {json,csv}] [-v]\n [--show-histogram] [-q] [-c {pq,pu21}] [-m {sdr,hdr10,hlg}] [-b {8,10,12}]\n [-r {limited,full}] [--legacy] [-e {bt1886,inv_srgb}] [-g GAMMA] [--l-max L_MAX]\n [--l-min L_MIN] [--pu21-mode {banding,banding_glare,peaks,peaks_glare}]\n input\n\noptional arguments:\n -h, --help show this help message and exit\n\ninput/output:\n input Input file, can be Y4M or file in FFmpeg-readable container\n -s SETTINGS, --settings SETTINGS\n Load settings from previous JSON results file instead of using CLI args\n -n NUM_FRAMES, --num-frames NUM_FRAMES\n Number of frames to calculate, must be >= 2 (default: unlimited)\n --max-frames MAX_FRAMES\n Overall number of frames, useful for providing better time estimates from\n the command-line\n -f {json,csv}, --format {json,csv}\n Choose the output format (default: json)\n -v, --verbose Show debug info on stderr (default: False)\n --show-histogram Show a histogram for the first frame (computation-intensive, implies\n --verbose) (default: False)\n -q, --quiet Do not show progress bar (default: False)\n\nVideo/SI options:\n -c {pq,pu21}, --calculation-domain {pq,pu21}\n Select calculation domain (default: pq)\n -m {sdr,hdr10,hlg}, --hdr-mode {sdr,hdr10,hlg}\n Select HDR mode (default: sdr)\n -b {8,10,12}, --bit-depth {8,10,12}\n Select bit depth (default: 8)\n -r {limited,full}, --color-range {limited,full}\n Specify limited or full range (default: limited)\n --legacy Use legacy mode, disables all other features except for range adjustment\n (default: False)\n\nSDR options:\n -e {bt1886,inv_srgb}, --eotf-function {bt1886,inv_srgb}\n Specify the EOTF function for converting SDR to HDR (default: bt1886)\n -g GAMMA, --gamma GAMMA\n Specify gamma for BT.1886 function (default: 2.4)\n\nDisplay options:\n --l-max L_MAX Nominal peak luminance of the display in cd/m2 for achromatic pixels\n (default: 300 for SDR, 1000.0 for HDR)\n --l-min L_MIN Display luminance for black in cd/m2 (default: 0.1 for SDR, 0.01 for HDR)\n\nPU21 options:\n --pu21-mode {banding,banding_glare,peaks,peaks_glare}\n Specify mode for PU21 (default: banding)\n```\n\n### Output\n\nThe tool will output a valid JSON object on `stdout`, with SI and TI scores contained in an array.\n\nTo redirect the output to a file, use shell redirection:\n\n```bash\nsiti-tools input1.mp4 > input1.json\n```\n\nNote that the first frame has no TI value by definition, so a file with two frames would produce the following output:\n\n```json\n{\n \"si\": [\n 4.678114135021466,\n 4.690539260164495\n ],\n \"ti\": [\n 0.33096454208633247\n ],\n \"settings\": {\n \"calculation_domain\": \"pq\",\n \"hdr_mode\": \"sdr\",\n \"bit_depth\": 8,\n \"color_range\": \"full\",\n \"eotf_function\": \"bt1886\",\n \"l_max\": 300,\n \"l_min\": 0.1,\n \"gamma\": 2.4,\n \"pu21_mode\": \"banding\",\n \"legacy\": false,\n \"version\": \"0.1.2\"\n },\n \"input_file\": \"FourPeople_480x270_60.y4m\"\n}\n```\n\nIn the `settings` key, you will find information on how the calculation was done. This is useful for allowing values to be reproduced. You can use these settings for further calculation runs. For instance, if you want to use the settings used for `input1` for `input2`, run the following:\n\n```\nsiti-tools input1.mp4 > input1.json\nsiti-tools input2.mp4 --settings input1.json > input2.json\n```\n\nYou can also generate CSV output, which will contain fewer columns but is easier to parse.\n\n```bash\nsiti-tools input1.mp4 --format csv > input1.csv\nsiti-tools input2.mp4 --settings input1.json --format csv > input2.csv\n```\n\nThe output might look like this:\n\n```\ninput_file,n,si,ti\nforeman_cif.y4m,1,39.342,\nforeman_cif.y4m,2,39.229,5.007\nforeman_cif.y4m,3,39.224,5.291\nforeman_cif.y4m,4,39.458,5.08\nforeman_cif.y4m,5,39.212,4.854\nforeman_cif.y4m,6,39.214,4.22\nforeman_cif.y4m,7,39.26,3.95\nforeman_cif.y4m,8,39.351,4.267\nforeman_cif.y4m,9,39.349,4.915\nforeman_cif.y4m,10,39.504,4.77\n```\n\nNote that the first TI value is empty by definition.\n\nThere is also a handy conversion utility to help you convert JSON to CSV files after you have calculated the scores.\n\n```bash\nutils/json-to-csv.py input.json input.csv\n```\n\n### API Usage\n\nThe tools expose the calculation functions via an API.\n\nFor instance, you can directly use the SI/TI functions:\n\n```python\nimport numpy as np\nfrom siti_tools.siti import SiTiCalculator # noqa: E402\n\nframe_data = ... # some numpy array\nprevious_frame_data = ... # some other numpy array\n\nsi_value = SiTiCalculator.si(frame_data)\nti_value = SiTiCalculator.ti(frame_data, previous_frame_data)\n```\n\nSee the `test/generate_raw_siti_values.py` file for an example of how to use those.\n\nOr, you can use the calculator class to do the conversions required for higher bit depths and HDR:\n\n```python\nimport json\nfrom siti_tools.siti import ColorRange, SiTiCalculator\n\nsi_ti_calculator = SiTiCalculator(\n color_range=ColorRange.LIMITED,\n # ... other settings go here\n )\n\nsi_ti_calculator.calculate(\n path_to_input_file,\n num_frames=3, # only calculate 3 frames\n)\n\nresults = si_ti_calculator.get_results()\n\nprint(json.dumps(results, indent=4))\n```\n\nSee the `siti_tools/__main__.py` file on how to specify all options.\n\n## Testing\n\nThis repo provides a set of test sequences with expected output values that you can verify against.\n\nFirst, install the dev dependencies:\n\n```\npip3 install -r requirements.dev.txt\n```\n\nGenerate the sequences:\n\n```bash\ncd test && ./generate_ffmpeg_sources.sh && cd -\n```\n\nThen run:\n\n```bash\npython3 -m pytest test/test.py -n auto\n```\n\nThe `-n auto` flag distributes the test to all cores. Remove it if you want to capture stdout with `-s`.\n\n## About\n\n### What is SI/TI?\n\nThe following info is given about SI / TI in [ITU-T Recommendation P.910](https://www.itu.int/rec/T-REC-P.910) (10/2023) \u2013 \"Subjective video quality assessment methods for multimedia applications\". This is the most recent version of the document at the time of writing. Version 07/2022 has introduced significant changes to the SI/TI calculation, which are reflected in this repository.\n\n> **Spatial Information**: A measure that indicates the amount of spatial detail in a picture. It is usually higher for more spatially complex scenes. It is not meant to be a measure of entropy nor is it associated with the information defined in communication theory\n\n> **Temporal information**: A measure that indicates the number of temporal changes of a video sequence. It is usually higher for high motion sequences. It is not meant to be a measure of entropy nor associated with the information defined in communication theory.\n\nSI and TI are based on the Sobel filter, which is a simple edge detector. The Sobel filter is applied to the luminance channel of the input video, and the resulting values are aggregated to a single value. For a detailed calculation, see Annex B of ITU-T Rec. P.910 (10/2023)\n\nFurther, Clause 7.8 states:\n\n> The selection of test scenes is an important issue. In particular, the spatial information (SI) and temporal information (TI) of the scenes are critical parameters. These parameters play a crucial role in determining the amount of video compression that is possible (compressibility), and consequently, the level of impairment that is suffered when the scene is transmitted over a fixed-rate digital transmission service channel. Fair and relevant video test scenes must be chosen such that their SI and TI is consistent with the video services that the digital transmission service channel was intended to provide. The set of test scenes should span the full range of SI and TI of interest to users of the devices under test.\n\nRegarding the aggregation of SI/TI values, Clause 7.8.4 states:\n\n> Multiple SI and TI values per sequence may be aggregated into single numbers for SI and TI, respectively, by applying appropriate statistical measures such as the minimum, maximum, median, average, or percentiles.\nIt is recommended to use the average as an aggregation measure.\n\nIf you have used a previous version of SI/TI, please consider:\n\n> Note that in the previous versions of Recommendation ITU-T P.910, the respective maximum value was recommended as aggregated score for SI and TI. (\u2026) If the resulting SI and TI values are being compared to those provided in publications or with publicly available databases, deviations may stem from the previously recommended usage of the maximum.\n\nFor further information, please refer to the ITU-T Rec. P.910 document.\n\n### What is the purpose of this activity?\n\nThe [No-Reference Metrics (NORM)](https://www.its.bldrdoc.gov/vqeg/projects/no-reference-metrics-norm.aspx) working group of the [Video Quality Expert Group (VQEG)](https://www.its.bldrdoc.gov/vqeg/vqeg-home.aspx) has investigated the Spatial Information (SI) and Temporal Information (TI) indicators defined in ITU-T Rec. P.910.\n\nSI and TI have been frequently used by the community to classify sets of video sequences or video databases, primarily for checking that the used material spans an appropriate range of spatiotemporal complexity before further processing the sequences (e.g., encoding them, presenting them to subjects). Since they are easy and quick to calculate, SI/TI are still very relevant today.\n\nVQEG identified several limitations with the current definition of SI/TI, including the following:\n\n- It was not specified how to handle video with limited (16-235) vs. full range (0-255).\n- The applicable range of input bit depths (bits per channel) was not specified. This means that it was unclear how to handle content with different bit depths, in particular when comparing sequences of varying bit depth.\n- It was undefined how to handle high dynamic range (HDR) content, where the luminance information might be encoded differently compared to standard dynamic range (SDR).\n\nThe overall aims of this activity were the following:\n\n- Providing an updated set of calculation functions for SI and TI that cover limited/full range content, higher bit depths, and HDR sequences\n- Providing a set of test sequences and expected values (i.e., test vectors) in order to allow others to reproduce the results and verify their own implementation\n- Updating the ITU-T Rec. P.910 text to incorporate the new calculation functions\n\nSince ITU-T Rec. P.910 is a normative document, the updated text was be submitted to ITU-T Study Group 12 for approval and subsequently published in the ITU-T Rec. P.910 document version 07/2022.\n\n### Contributors\n\nCode contributors:\n\n- Werner Robitza\n- Lukas Krasula\n\nMany others have contributed to the discussion and updating of the ITU-T document. Thank you to all of them!\n\n### Acknowledgements\n\nIf you use this software in your research, please include link to this repository.\n\n### Related Projects\n\n- [TelecommunicationTelemediaAssessment/SITI](https://github.com/Telecommunication-Telemedia-Assessment/SITI): Legacy calculations of OpenCV and Python version of SI/TI, values may not necessarily correspond.\n- [NabajeetBarman/SI-TI](https://github.com/NabajeetBarman/SI-TI): MATLAB version of SI/TI calculation, values verified against this repository.\n\n### License\n\nMIT License\n\nsiti_tools, Copyright (c) 2021-2023 Werner Robitza, Lukas Krasula\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n\n# Changelog\n\n\n## v0.3.0 (2024-08-01)\n\n* Chore: update dependencies.\n\n* Fix the implementation of the HLG EOTF function (#23)\n\n * Fix the implementation of the HLG EOTF function\n\n * Fix the tests for HLG\n\n ---------\n\n\n## v0.2.3 (2023-12-18)\n\n* Update dependencies to include release deps.\n\n* Bump dependencies.\n\n* Update readme.\n\n* Fix issue #20 (#21)\n\n * Remove `-c:v copy` from the FFmpeg command putting YUV content in a Y4M container.\n\n Mention that `-strict -1` is necessary fot 10-bit pixel formats.\n\n * Make sure the example for 10-bit pixel format actually uses a 10-bit pixel format\n\n* Fix README installation instructions.\n\n* Update readme, addresses #17.\n\n* Fix ffmpeg libs.\n\n\n## v0.2.2 (2023-06-27)\n\n* Update dependencies.\n\n* Update test decode function.\n\n* Explain usage with YUV files.\n\n* Add version support to CLI.\n\n* Add utility for converting JSON output to CSV.\n\n* Error on unsupported frame formats.\n\n\n## v0.2.1 (2022-05-13)\n\n* Fix console script installation.\n\n* Fix link in setup.py.\n\n* Update README.\n\n\n## v0.2.0 (2022-05-03)\n\n* Check for pypandoc on release.\n\n* Fix CI setup (#14)\n\n* CI: support only Python 3.8 and higher.\n\n* Fix broken link.\n\n* Merge branch 'siti2020'\n\n* Update README links.\n\n* Minor code style.\n\n* Code formatting and note.\n\n* ITU-T --> ITU-R.\n\n* Improve docs and tests.\n\n* Add profiling test.\n\n* Update README.md.\n\n* Update release script.\n\n* Add poetry environment.\n\n* Type error.\n\n* Improve logs.\n\n* Fix logs.\n\n* Add legacy mode.\n\n* Format code.\n\n* Update README.\n\n* Add option for total frame count in tqdm bar.\n\n* Update for newer ffmpeg, update pip.\n\n* Fix call of OETF, fix tests.\n\n* Remove superfluous scaling for PU21.\n\n* Fix issue with CSV output.\n\n* Add type casts for type checks.\n\n* Make logger global.\n\n* Update README.\n\n* Add histogram plots.\n\n* Fix formula for EOTF output.\n\n* Add progress bar/iterator.\n\n* Add CSV output functionality.\n\n* Add logging and fix error with l_min/l_max conversion.\n\n* Add further test content.\n\n* Fix unit tests.\n\n* Update README and docs.\n\n* Fixes for 10bpp reading, fixes #12.\n\n* Update requirements.\n\n* Update test set, fix reading function for Y4M.\n\n* Update test functions.\n\n* Print more info during tests.\n\n* Remove unused import.\n\n* Update dev requirements.\n\n* Fix test functions.\n\n - use JSON for testing the complex class functions\n - fall back to one video for testing the simple functions\n - prepare using other videos for testing\n\n* Limit download size of test videos.\n\n* Add options to select PU21.\n\n* Remove comment.\n\n* Add typing support for PU21.\n\n* Add oetf_pu21.\n\n* Simplify test functions.\n\n* Add note on input values.\n\n* Update requirements.\n\n* Remove import.\n\n* Update test suite.\n\n* Add CLI documentation and entry point.\n\n* Allow reusing settings from previous run, fixes #10.\n\n* Convert to 0-1 range.\n\n This converts values into 0-1 for EOTF/OETF handling, and then scales everything\n up to 0-255 again for output, regardless of original bit depth.\n\n* Add new class-based calculation and results.\n\n add more CLI flags\n\n rework classes\n\n* Update LICENSE and README.\n\n* Implementation of eotf_1886, eotf_inv_srgb, eotf_hlg, and oetf_pq.\n\n* Implement first conversion functions.\n\n* Update README links.\n\n\n## v0.1.3 (2022-03-14)\n\n* Add method to specify full range in read_container.\n\n* Link to development branch.\n\n* Update docs.\n\n\n## v0.1.2 (2021-05-14)\n\n* Add documentation for method.\n\n* Fix link.\n\n* Update README.md.\n\n* Update README.md.\n\n* Output frame data as integers.\n\n\n## v0.1.1 (2021-05-13)\n\n* Add warning for full range passed to limited range function, fixes #2.\n\n* Add new test video, improve test harness.\n\n\n## v0.1.0 (2021-03-08)\n\n* Add status badge.\n\n* Bump Python support.\n\n* Add GitHub Actions CI (#1)\n\n* Fix flake8 errors.\n\n\n## v0.0.2 (2021-03-08)\n\n* Fix setup.py.\n\n* Add CHANGELOG.\n\n\n## v0.0.1 (2021-03-08)\n\n* Improve README.\n\n* Initial commit.\n\n* Initial commit.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Functions to calculate Spatial Information / Temporal Information according to ITU-T P.910",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/VQEG/siti-tools"
},
"split_keywords": [
"video",
" spatial information",
" temporal information"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bba0622eb7af88ec6f84ce0853ee020b8e7b10f8851b97d7cf82dbe28146c3a5",
"md5": "5935b8e3f3c096d193947b300b4bc9ff",
"sha256": "d0db707fb22b523c5cb3217c1c06c5398ac5094afb8aa52e58e0689357b23d45"
},
"downloads": -1,
"filename": "siti_tools-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5935b8e3f3c096d193947b300b4bc9ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23926,
"upload_time": "2024-08-01T07:11:29",
"upload_time_iso_8601": "2024-08-01T07:11:29.545099Z",
"url": "https://files.pythonhosted.org/packages/bb/a0/622eb7af88ec6f84ce0853ee020b8e7b10f8851b97d7cf82dbe28146c3a5/siti_tools-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0b37af3abdd07e9630dc2faabf94bba8a35d29bf0a59838ab5da2ecb2b4a7a64",
"md5": "a4c5be91558b8a10da0982fc33d3d2e7",
"sha256": "0804bc59ddfce26d8babc39c44ea816ca44ee988bb668f9ce04ce52a12fdfaae"
},
"downloads": -1,
"filename": "siti-tools-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a4c5be91558b8a10da0982fc33d3d2e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 32728,
"upload_time": "2024-08-01T07:11:30",
"upload_time_iso_8601": "2024-08-01T07:11:30.781250Z",
"url": "https://files.pythonhosted.org/packages/0b/37/af3abdd07e9630dc2faabf94bba8a35d29bf0a59838ab5da2ecb2b4a7a64/siti-tools-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-01 07:11:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "VQEG",
"github_project": "siti-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "siti-tools"
}
JSON
