Merge pull request #37 from amiaopensource/develop

Develop

Author: eddycolloton

.github/workflows/tests.yml

@@ -0,0 +1,37 @@
+on: [push, pull_request]
+name: Supported Python Compatibility Test
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-2019]
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        include:
+          - os: macos-latest
+          - os: ubuntu-latest
+          - os: windows-2019
+      fail-fast: false
+    name: Python ${{ matrix.python-version }} ${{ matrix.os }} build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip' # caching pip dependencies
+      - name: Install requirements
+        run: |
+          pip install tox
+      - uses: actions/github-script@v7
+        id: tox-env
+        with:
+          result-encoding: string
+          script: |
+            const frontend = "${{matrix.frontend}}"
+            const toxEnv = "py${{matrix.python-version}}".replace('.','') 
+            if(frontend === ""){
+              return toxEnv
+            }
+            return "py${{matrix.python-version}}".replace('.','') + "-${{matrix.frontend}}"
+      - name: Run tox
+        run: tox -e ${{ steps.tox-env.outputs.result }}

README.md

@@ -1,102 +1,211 @@
-scripts for automating QCTools actions
 
-qct-parse.py | find frames that are beyond thresholds for saturation, luma, etc
+# QCTools Automation Scripts
+
+This repository contains scripts for automating analysis of QCTools reports.
+
+## Overview
+
+### Install from source:
+
+* Create a new Python Virtual Environment for qct_parse
+  * Unix based (Mac or Linux):    
+    `python3 -m venv name_of_env` 
+  * Windows:    
+    `py -m venv name_of_env`
+    (where 'name_of_env' is replaced with the name of your virtual environment) 
+* Activate virtual env 
+  * Unix based (Mac or Linux):     
+    `source ./name_of_env/bin/activate`
+  * Windows:     
+    `name_of_env\scripts\activate`
+* Install Package
+  * Navigate to the repo root directory `path/to/qct-parse/`
+  * Run the command:    
+  `python -m pip install .`
+
+### Test Code
+
+If you intend to develop the code for your proposes or contribute to the open source project, a test directory is provided in the repo.
+* Activate virtual env (see Install from source) 
+* Install pytest 
+  `pip install pytest`
+* Run tests
+  `python -m pytest`
+
+### Building the documentation
+* Activate virtual env (see Install from source)
+* Install sphinx and myst-parser
+  `pip install sphinx myst-parser`
+* Run sphinx-build command
+  `sphinx-build ./docs ./dist/docs`
+
+
+### Commands:
+
+- **`qct-parse -i/--input [path to QCTools report] [optional arguments]`**  
+  Finds frames that exceed thresholds for QCTool tag(s). Full list of command line arguments below.
+
+---
+
+# `qct-parse`
+
+Run a single tag against a supplied value or multiple tags using a profile.
+
+## Arguments
 
-makeqctoolsreport.py | make a qctools.xml.gz report for input video file
+| Argument                   | Description                                                                                           |
+|-----------------------------|-------------------------------------------------------------------------------------------------------|
+| `-h`, `--help`              | Show this help message and exit                                                                       |
+| `-i`, `--input`             | Path to the input `qctools.xml.gz` or `qctools.mkv` file                                              |
+| `-t`, `--tagname`           | The tag name you want to test (e.g., `SATMAX`); see table of tag names below for list              |
+| `-o`, `--over`              | Threshold overage number                                                                              |
+| `-u`, `--under`             | Threshold under number                                                                                |
+| `-p`, `--profile`           | Compare frame data against tag values from `config.txt`. Use `-p default` for QCTools default values  |
+| `-buff`, `--buffSize`       | Circular buffer size. If even, defaults to the next odd number (default: 11)                          |
+| `-te`, `--thumbExport`      | Enable/disable thumbnail export (default: off)                                                        |
+| `-ted`, `--thumbExportDelay`| Minimum frames between exported thumbnails (default: 9000)                                             |
+| `-tep`, `--thumbExportPath` | Path to thumbnail export. Uses input base-path if omitted                                             |
+| `-ds`, `--durationStart`    | Start analysis from this time (seconds, equivalent to ffmpeg `-ss`)                                   |
+| `-de`, `--durationEnd`      | End analysis after this time (seconds, equivalent to ffmpeg `-t`)                                     |
+| `-bd`, `--barsDetection`    | Enable/disable bar detection (default: off)                                                           |
+| `-be`, `--barsEvaluation`   | Use peak values from color bars as 'profile' if bars are detected                                      |
+| `-pr`, `--print`            | Print over/under frame data to console (default: off)                                                 |
+| `-q`, `--quiet`             | Suppress ffmpeg output in console (default: off)                                                      |
 
-# qct-parse.py
+## Tags
 
-You can run a single tag against a supplied value from the CLI or run multiple tags against values set in the qct-parse_config.txt file.
+| Tag category                   | Tag names                                                                                           |
+|-----------------------------|-------------------------------------------------------------------------------------------------------|
+| [YUV values](https://bavc.github.io/qctools/filter_descriptions.html#yuv) | `YMIN,YLOW,YAVG,YHIGH,YMAX`<br>`UMIN,ULOW,UAVG,UHIGH,UMAX`<br>`VMIN,VLOW,VAVG,VHIGH,VMAX`   |
+| [YUV values (difference)](https://bavc.github.io/qctools/filter_descriptions.html#diff)   | `YDIF,UDIF,VDIF`  |
+| [Saturation values](https://bavc.github.io/qctools/filter_descriptions.html#saturation)   | `SATMIN,SATLOW,SATAVG,SATHIGH,SATMAX` |
+| [Hue values](https://bavc.github.io/qctools/filter_descriptions.html#hue) | `HUEMED,HUEAVG` |
+| [Temporal outliers](https://bavc.github.io/qctools/filter_descriptions.html#tout) | `TOUT`    |
+| [Vertical line repetitions](https://bavc.github.io/qctools/filter_descriptions.html#vrep) | `VREP`   |
+| [Broadcast range](https://bavc.github.io/qctools/filter_descriptions.html#brng) | `BRNG`    |
+| [Mean square error fields](https://bavc.github.io/qctools/filter_descriptions.html#msef) | `mse_y,mse_u,mse_v,mse_avg`  |
+| [Peak signal to noise ratio fields](https://bavc.github.io/qctools/filter_descriptions.html#psnrf) | `psnr_y,psnr_u,psnr_v,psnr_avg`   |
 
-## arguments
-  -h, --help                | show this help message and exit
+## Examples
 
-  -i, --input            | the path to the input qctools.xml.gz file
-  
-  -t, --tagname         | the tag name you want to test, e.g. SATMAX
-  
-  -o, --over             | the threshold overage number
-  
-  -u, --under             | the threshold under number
-  
-  -p, --profile         | compare frame data aginst tag values from config.txt file, us "-p default" for values from QCTools docs
-  
-  -buff, --buffSize         | Size of the circular buffer. if user enters an even number it'll default to the next largest number to make it odd, default size 11
-                        
-  -te, --thumbExport        | export thumbnails on/ off, default off
-  
-  -ted, --thumbExportDelay  | minimum frames between exported thumbs, default 9000
-                        
-  -tep, --thumbExportPath   | Path to thumb export. if ommitted, uses the input base-path
-                        
-  -ds, --durationStart      | the duration in seconds to start analysis (ffmpeg equivalent -ss)
-                        
-  -de, --durationEnd        | the duration in seconds to stop analysis (ffmpeg equivalent -t)
-                        
-  -bd, --barsDetection      | bar detection on/ off, default off
-  
-  -pr, --print               | print over/under frame data to console window, default off
-  
-  -q, --quiet               | print ffmpeg output to console window, default off
+### Run single tag tests
+```bash
+qct-parse -t SATMAX -o 235 -t YMIN -u 16 -i /path/to/report.mkv.qctools.xml.gz
+```
 
+### Run bars detection using default QCTools profile
+```bash
+qct-parse -bd -p default -i /path/to/report.mkv.qctools.mkv
+```
 
-## examples
+### Export thumbnails of frames beyond threshold
+```bash
+qct-parse -p default -te -tep /path/to/export/folder -i /path/to/report.mkv.qctools.xml.gz
+```
 
-### single tags
+### Use peak values from detected color bars as thresholds
+```bash
+qct-parse -bd -be -i /path/to/report.mkv.qctools.xml.gz
+```
 
-python qct-parse.py -t SATMAX -o 235 -t YMIN -u 16 -i /path/to/report.mkv.qctools.xml.gz
+## Input files
 
-### run bars against default profile from QCTools docs
+qct-parse.py will work with the following QCTools report formats: 
+```
+qctools.xml.gz 
+qctools.mkv
+```
 
-python qct-parse.py -bd -p default -i /path/to/reportsmkv.qctools.xml.gz
+If the qctools.xml.gz report is in an MKV attachment, the qctools.xml.gz report file will be extracted and saved as a separate file. 
 
-### print out thumbnails of frames beyond threshold
+Both 8-bit and 10-bit values are supported. The bit depth will be detected automatically, and does not need to be specified. 
 
-python qct-parse.py -p default -te -tep C:\path\to\export\folder -i C:\path\to\the\report.mkv.qctools.xml.gz
+## Config Files
 
-## some handy applescript to grep individual tags
+The provided profiles are:   
+* default
+* highTolerance
+* midTolerance
+* lowTolerance
 
-### just percentages
+Each of these profiles contain the following tags with a corresponding threshold:    
+`YLOW, YMAX, UMIN, UMAX, VMIN, VMAX, SATMAX, TOUT, VREP`
 
-python ./qct-parse.py -i input.mxf.qctools.xml.gz -bd -p lowTolerance | grep 'YMAX' | awk 'NR==1 {print $3}'
+The profiles are stored in the config.txt files. Please note that there is a separate config.txt for 8-bit and 10-bit values.
 
-### total number of frame failures
+The process for providing user supplied profiles is in development.     
+Currently, if you wish to create your own profile, you will need to create your own config directory and `config.txt` file.    
+There is a environmental variable at the top of qct-parse.py which can be used to reset the config directory:     
+```bash
+CONFIG_ENVIRONMENT_VARIABLE_NAME = 'QCT_PARSE_CONFIG_DIRECTORY'
+```
+Simply place the full path to the user created config *directory* in place of 'QCT_PARSE_CONFIG_DIRECTORY'
 
-python ./qct-parse.py -i input.mxf.qctools.xml.gz -bd -p lowTolerance | grep 'YMAX' | awk 'NR==1 {print $2}'
+## Thumbnails
 
-## dependencies
+Thumbnails of failed frames will be exported if the `-te` flag is invoked. 
 
-Python 2.7.x.
+In order to export thumbnails, the QCTools report must be in the same directory as the video file it is describing, and must have the same file name as the report (excluding the `qctools.xml.gz`).
 
-Requires that [lxml](http://lxml.de/) is installed on your system. For more info on how it's used, see [here](http://www.ibm.com/developerworks/library/x-hiperfparse/)
+If you would like to provide a path for exporting thumbnails, you can do so using the `-tep` flag.     
+Otherwise, thumbnails will automatically be created in the same directory as the video file and QCTools report, in a new directory.
 
-### For Windows users:
+When running qct-parse with a profile, the thumbnails will be placed in a directory named `ThumbExports`.
+When run against single tags the directory will be named [TAG NAME].[THRESHOLD]
 
-We **strongly** suggest using the pre-compiled installer found [here](https://pypi.python.org/pypi/lxml/3.3.3#downloads)
+## Logging
 
-### For Mac users:
+A log file is created with the same name as the input file but with a '.log' extension.    
+For example: `some_video_file.mkv.qctools.xml.gz.log`
 
-Try pip first, then try the macport. More info can be found [here](http://lxml.de/installation.html)
+Log files contain every instance of values over the specified threshold. For example:    
+`2024-10-03 17:02:35,737 SATMAX is over 181.02 with a value of 698.0 at duration 00:00:16.4500`
 
-# makeqctoolsreport.py
+---
 
-python port of Morgan's [makeqctoolsreport.as](https://github.com/iamdamosuzuki/QCToolsReport)
+### Legacy Commands:
 
+Not in active development. Please file an issue if you are interested in using these.
 
-## example
+#### `makeqctoolsreport`
 
-python makeqctoolsreport.py /path/to/input.mxf
+A Python port of Morgan’s [makeqctoolsreport.as](https://github.com/iamdamosuzuki/QCToolsReport), this script generates QCTools `.xml.gz` reports from input video files.
 
-## contributors
+Example Usage:
+```bash
+makeqctoolsreport /path/to/input.mxf
+```
 
-@eddycolloton
+#### `overcatch`
 
-@CoatesBrendan
+A script from the original qct-parse development for running a report against multiple profiles.
 
-@av_morgan
+Example Usage:
+```bash
+overcatch /path/to/input.mxf
+```
 
-## maintainers
+---
 
-@av_morgan
+## Dependencies
 
-@eddycolloton
+Ensure Python 3.x.x is installed.
+
+Requires FFmpeg.
+
+This tool uses the `lxml` python module which is automatically installed with the qct-parse package. 
+
+For more information on `lxml` usage, check out the [lxml documentation](http://lxml.de/).
+
+---
+
+## Contributors
+
+- [@eddycolloton](https://github.com/eddycolloton)
+- [@CoatesBrendan](https://github.com/CoatesBrendan)
+- [@av_morgan](https://github.com/av_morgan)
+
+## Maintainer
+
+- [@av_morgan](https://github.com/av_morgan)
+- [@eddycolloton](https://github.com/eddycolloton)

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,31 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'qct-parse'
+copyright = '2024, AMIA Open-Source'
+author = 'AMIA Open-Source'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['myst_parser']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

docs/development.md

@@ -0,0 +1,29 @@
+# Development Information
+
+## Configure Development Environment
+
+* Create a new Python Virtual Environment for qct_parse
+    * Unix based (Mac or Linux):    
+      `python3 -m venv name_of_env`
+    * Windows:    
+      `py -m venv name_of_env`
+      (where 'name_of_env' is replaced with the name of your virtual environment)
+* Activate virtual env
+    * Unix based (Mac or Linux):     
+      `source ./name_of_env/bin/activate`
+    * Windows:     
+      `name_of_env\scripts\activate`
+* Install Package as editable package
+    * Navigate to the repo root directory `path/to/qct-parse/`
+    * Run the command:    
+      `python -m pip install -e .`
+
+## Run Tests
+
+If you intend to develop the code for your proposes or contribute to the open source project, a test directory is provided in the repo.
+* Activate virtual env (see Configure Development Environment)
+* Install pytest
+  `pip install pytest`
+* Run tests
+  `python -m pytest`
+