From 40c7198f7df594038de7ce4dd603599b50ee6eb5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arttu=20Yl=C3=A4-Outinen?= Date: Fri, 5 Feb 2016 16:16:18 +0200 Subject: [PATCH] Add a script for updating README Adds script tools/update_readme.sh for regenerating the "Using Kvazaar" section of README.md from the output of "kvazaar --help". --- README.md | 235 +++++++++++++++++++++-------------------- doc/genmanpage.sh | 4 +- doc/kvazaar.1 | 25 ++--- src/cli.c | 23 ++-- tools/update_readme.sh | 35 ++++++ 5 files changed, 182 insertions(+), 140 deletions(-) create mode 100755 tools/update_readme.sh diff --git a/README.md b/README.md index cfc39529..d4ce19ff 100644 --- a/README.md +++ b/README.md @@ -13,129 +13,132 @@ http://ultravideo.cs.tut.fi/#encoder for more information. ##Using Kvazaar - Usage: - kvazaar -i --input-res x -o +[comment]: # (BEGIN KVAZAAR HELP MESSAGE) +``` +Usage: +kvazaar -i --input-res x -o - Optional parameters: - --help : Print this help message and exit - --version : Print version information and exit - -n, --frames : Number of frames to code [all] - --seek : First frame to code [0] - --input-res x : Input resolution (width x height) or - auto : try to detect from file name [auto] - --input-fps / : Framerate of the input video [25.0] - -q, --qp : Quantization Parameter [32] - -p, --period : Period of intra pictures [0] - 0: only first picture is intra - 1: all pictures are intra - 2-N: every Nth picture is intra - --vps-period : Specify how often the video parameter set is - re-sent. [0] - 0: only send VPS with the first frame - 1: send VPS with every intra frame - N: send VPS with every Nth intra frame - -r, --ref : Reference frames, range 1..15 [3] - --no-deblock : Disable deblocking filter - --deblock : Deblocking filter parameters - beta and tc range is -6..6 [0:0] - --no-sao : Disable sample adaptive offset - --no-rdoq : Disable RDO quantization - --no-signhide : Disable sign hiding in quantization - --smp : Enable Symmetric Motion Partition - --amp : Enable Asymmetric Motion Partition - --rd : Rate-Distortion Optimization level [1] - 0: no RDO - 1: estimated RDO - 2: full RDO - --mv-rdo : Enable Rate-Distortion Optimized motion vector costs - --full-intra-search : Try all intra modes. - --no-transform-skip : Disable transform skip - --aud : Use access unit delimiters - --cqmfile : Custom Quantization Matrices from a file - --debug : Output encoders reconstruction. - --cpuid : Disable runtime cpu optimizations with value 0. - --me : Set integer motion estimation algorithm ["hexbs"] - "hexbs": Hexagon Based Search (faster) - "tz": Test Zone Search (better quality) - "full": Full Search (super slow) - --subme : Set fractional pixel motion estimation level [1]. - 0: only integer motion estimation - 1: fractional pixel motion estimation enabled - --source-scan-type : Set source scan type ["progressive"]. - "progressive": progressive scan - "tff": top field first - "bff": bottom field first - --pu-depth-inter - : Range for sizes of inter prediction units to try. - 0: 64x64, 1: 32x32, 2: 16x16, 3: 8x8 - --pu-depth-intra - : Range for sizes of intra prediction units to try. - 0: 64x64, 1: 32x32, 2: 16x16, 3: 8x8, 4: 4x4 - --no-info : Don't add information about the encoder to settings. - --gop : Definition for GOP [0] - - 0 disabled - - 8 B-frame pyramid of length 8 - - lp-gop syntax, defined below (example: g8d4r3t2) - --bipred : Enable bi-prediction search - --bitrate : Target bitrate. [0] - 0: disable rate-control - N: target N bits per second - --preset : Use preset. This will override previous options. - ultrafast, superfast,veryfast, faster, - fast, medium, slow, slower, veryslow, placebo - --no-psnr : Don't calculate PSNR for frames +Optional parameters: + --help : Print this help message and exit + --version : Print version information and exit + -n, --frames : Number of frames to code [all] + --seek : First frame to code [0] + --input-res x : Input resolution (width x height) or + auto : try to detect from file name [auto] + --input-fps / : Framerate of the input video [25.0] + -q, --qp : Quantization Parameter [32] + -p, --period : Period of intra pictures [0] + 0: only first picture is intra + 1: all pictures are intra + 2-N: every Nth picture is intra + --vps-period : Specify how often the video parameter set is + re-sent. [0] + 0: only send VPS with the first frame + 1: send VPS with every intra frame + N: send VPS with every Nth intra frame + -r, --ref : Reference frames, range 1..15 [3] + --no-deblock : Disable deblocking filter + --deblock : Deblocking filter parameters + beta and tc range is -6..6 [0:0] + --no-sao : Disable sample adaptive offset + --no-rdoq : Disable RDO quantization + --no-signhide : Disable sign hiding in quantization + --smp : Enable Symmetric Motion Partition + --amp : Enable Asymmetric Motion Partition + --rd : Rate-Distortion Optimization level [1] + 0: no RDO + 1: estimated RDO + 2: full RDO + --mv-rdo : Enable Rate-Distortion Optimized motion vector costs + --full-intra-search : Try all intra modes. + --no-transform-skip : Disable transform skip + --aud : Use access unit delimiters + --cqmfile : Custom Quantization Matrices from a file + --debug : Output encoders reconstruction. + --cpuid : Disable runtime cpu optimizations with value 0. + --me : Set integer motion estimation algorithm ["hexbs"] + "hexbs": Hexagon Based Search (faster) + "tz": Test Zone Search (better quality) + "full": Full Search (super slow) + --subme : Set fractional pixel motion estimation level [1]. + 0: only integer motion estimation + 1: fractional pixel motion estimation enabled + --source-scan-type : Set source scan type ["progressive"]. + "progressive": progressive scan + "tff": top field first + "bff": bottom field first + --pu-depth-inter - : Range for sizes of inter prediction units to try. + 0: 64x64, 1: 32x32, 2: 16x16, 3: 8x8 + --pu-depth-intra - : Range for sizes of intra prediction units to try. + 0: 64x64, 1: 32x32, 2: 16x16, 3: 8x8, 4: 4x4 + --no-info : Don't add information about the encoder to settings. + --gop : Definition of GOP structure [0] + "0": disabled + "8": B-frame pyramid of length 8 + "lp-": lp-gop definition (e.g. lp-g8d4r3t2) + --bipred : Enable bi-prediction search + --bitrate : Target bitrate. [0] + 0: disable rate-control + N: target N bits per second + --preset : Use preset. This will override previous options. + ultrafast, superfast,veryfast, faster, + fast, medium, slow, slower, veryslow, placebo + --no-psnr : Don't calculate PSNR for frames - Video Usability Information: - --sar : Specify Sample Aspect Ratio - --overscan : Specify crop overscan setting ["undef"] - - undef, show, crop - --videoformat : Specify video format ["undef"] - - component, pal, ntsc, secam, mac, undef - --range : Specify color range ["tv"] - - tv, pc - --colorprim : Specify color primaries ["undef"] - - undef, bt709, bt470m, bt470bg, - smpte170m, smpte240m, film, bt2020 - --transfer : Specify transfer characteristics ["undef"] - - undef, bt709, bt470m, bt470bg, - smpte170m, smpte240m, linear, log100, - log316, iec61966-2-4, bt1361e, - iec61966-2-1, bt2020-10, bt2020-12 - --colormatrix : Specify color matrix setting ["undef"] - - undef, bt709, fcc, bt470bg, smpte170m, - smpte240m, GBR, YCgCo, bt2020nc, bt2020c - --chromaloc : Specify chroma sample location (0 to 5) [0] + Video Usability Information: + --sar : Specify Sample Aspect Ratio + --overscan : Specify crop overscan setting ["undef"] + - undef, show, crop + --videoformat : Specify video format ["undef"] + - component, pal, ntsc, secam, mac, undef + --range : Specify color range ["tv"] + - tv, pc + --colorprim : Specify color primaries ["undef"] + - undef, bt709, bt470m, bt470bg, + smpte170m, smpte240m, film, bt2020 + --transfer : Specify transfer characteristics ["undef"] + - undef, bt709, bt470m, bt470bg, + smpte170m, smpte240m, linear, log100, + log316, iec61966-2-4, bt1361e, + iec61966-2-1, bt2020-10, bt2020-12 + --colormatrix : Specify color matrix setting ["undef"] + - undef, bt709, fcc, bt470bg, smpte170m, + smpte240m, GBR, YCgCo, bt2020nc, bt2020c + --chromaloc : Specify chroma sample location (0 to 5) [0] - Parallel processing: - --threads : Maximum number of threads to use. - Disable threads if set to 0. + Parallel processing: + --threads : Maximum number of threads to use. + Disable threads if set to 0. - Tiles: - --tiles-width-split |u : - Specifies a comma separated list of pixel - positions of tiles columns separation coordinates. - Can also be u followed by and a single int n, - in which case it produces columns of uniform width. - --tiles-height-split |u : - Specifies a comma separated list of pixel - positions of tiles rows separation coordinates. - Can also be u followed by and a single int n, - in which case it produces rows of uniform height. + Tiles: + --tiles-width-split |u : + Specifies a comma separated list of pixel + positions of tiles columns separation coordinates. + Can also be u followed by and a single int n, + in which case it produces columns of uniform width. + --tiles-height-split |u : + Specifies a comma separated list of pixel + positions of tiles rows separation coordinates. + Can also be u followed by and a single int n, + in which case it produces rows of uniform height. - Wpp: - --wpp : Enable wavefront parallel processing - --owf |auto : Number of parallel frames to process. 0 to disable. + Wpp: + --wpp : Enable wavefront parallel processing + --owf |auto : Number of parallel frames to process. 0 to disable. - Slices: - --slice-addresses |u: - Specifies a comma separated list of LCU - positions in tile scan order of tile separations. - Can also be u followed by and a single int n, - in which case it produces uniform slice length. - - Deprecated parameters: (might be removed at some point) - Use --input-res: - -w, --width : Width of input in pixels - -h, --height : Height of input in pixels + Slices: + --slice-addresses |u : + Specifies a comma separated list of LCU + positions in tile scan order of tile separations. + Can also be u followed by and a single int n, + in which case it produces uniform slice length. + Deprecated parameters: (might be removed at some point) + Use --input-res: + -w, --width : Width of input in pixels + -h, --height : Height of input in pixels +``` +[comment]: # (END KVAZAAR HELP MESSAGE) ###For example: diff --git a/doc/genmanpage.sh b/doc/genmanpage.sh index 7b7b4e20..7125e8ef 100755 --- a/doc/genmanpage.sh +++ b/doc/genmanpage.sh @@ -18,8 +18,8 @@ kvazaar \- open source HEVC encoder EOF kvazaar --help 2>&1 | tail -n+5 | head -n-4 | \ - sed 's| : |\n|g; - s|>: $|>|g; + sed 's| : |\n|g; + s| :$||g; s|^ --|.TP\n\\fB--|g; s|^ --|.TP\n\\fB--|g; s|^ -|.TP\n\\fB-|g; diff --git a/doc/kvazaar.1 b/doc/kvazaar.1 index 9e4c809b..181e0538 100644 --- a/doc/kvazaar.1 +++ b/doc/kvazaar.1 @@ -22,7 +22,7 @@ Input resolution (width x height) or auto try to detect from file name [auto] .TP -\fB\-\-input\-fps +\fB\-\-input\-fps / Framerate of the input video [25.0] .TP \fB\-q\fR, \fB\-\-qp @@ -78,12 +78,6 @@ Enable Rate\-Distortion Optimized motion vector costs \fB\-\-full\-intra\-search Try all intra modes. .TP -\fB\-\-me -Set integer motion estimation algorithm ["hexbs"] - "hexbs": Hexagon Based Search (faster) - "tz": Test Zone Search (better quality) - "full": Full Search (super slow) -.TP \fB\-\-no\-transform\-skip Disable transform skip .TP @@ -99,6 +93,12 @@ Output encoders reconstruction. \fB\-\-cpuid Disable runtime cpu optimizations with value 0. .TP +\fB\-\-me +Set integer motion estimation algorithm ["hexbs"] + "hexbs": Hexagon Based Search (faster) + "tz": Test Zone Search (better quality) + "full": Full Search (super slow) +.TP \fB\-\-subme Set fractional pixel motion estimation level [1]. 0: only integer motion estimation @@ -121,8 +121,11 @@ Range for sizes of intra prediction units to try. \fB\-\-no\-info Don't add information about the encoder to settings. .TP -\fB\-\-gop -Length of Group of Pictures, must be 8 or 0 [0] +\fB\-\-gop +Definition of GOP structure [0] + "0": disabled + "8": B\-frame pyramid of length 8 + "lp\-": lp\-gop definition (e.g. lp\-g8d4r3t2) .TP \fB\-\-bipred Enable bi\-prediction search @@ -133,7 +136,7 @@ Target bitrate. [0] N: target N bits per second .TP \fB\-\-preset -Use preset +Use preset. This will override previous options. ultrafast, superfast,veryfast, faster, fast, medium, slow, slower, veryslow, placebo .TP @@ -186,14 +189,12 @@ Disable threads if set to 0. .SS "Tiles:" .TP \fB\-\-tiles\-width\-split |u - Specifies a comma separated list of pixel positions of tiles columns separation coordinates. Can also be u followed by and a single int n, in which case it produces columns of uniform width. .TP \fB\-\-tiles\-height\-split |u - Specifies a comma separated list of pixel positions of tiles rows separation coordinates. Can also be u followed by and a single int n, diff --git a/src/cli.c b/src/cli.c index c4c84e9d..45f83afc 100644 --- a/src/cli.c +++ b/src/cli.c @@ -300,7 +300,7 @@ void print_help(void) " --seek : First frame to code [0]\n" " --input-res x : Input resolution (width x height) or\n" " auto : try to detect from file name [auto]\n" - " --input-fps : Framerate of the input video [25.0]\n" + " --input-fps / : Framerate of the input video [25.0]\n" " -q, --qp : Quantization Parameter [32]\n" " -p, --period : Period of intra pictures [0]\n" " 0: only first picture is intra\n" @@ -326,15 +326,15 @@ void print_help(void) " 2: full RDO\n" " --mv-rdo : Enable Rate-Distortion Optimized motion vector costs\n" " --full-intra-search : Try all intra modes.\n" - " --me : Set integer motion estimation algorithm [\"hexbs\"]\n" - " \"hexbs\": Hexagon Based Search (faster)\n" - " \"tz\": Test Zone Search (better quality)\n" - " \"full\": Full Search (super slow)\n" " --no-transform-skip : Disable transform skip\n" " --aud : Use access unit delimiters\n" " --cqmfile : Custom Quantization Matrices from a file\n" " --debug : Output encoders reconstruction.\n" " --cpuid : Disable runtime cpu optimizations with value 0.\n" + " --me : Set integer motion estimation algorithm [\"hexbs\"]\n" + " \"hexbs\": Hexagon Based Search (faster)\n" + " \"tz\": Test Zone Search (better quality)\n" + " \"full\": Full Search (super slow)\n" " --subme : Set fractional pixel motion estimation level [1].\n" " 0: only integer motion estimation\n" " 1: fractional pixel motion estimation enabled\n" @@ -347,12 +347,15 @@ void print_help(void) " --pu-depth-intra - : Range for sizes of intra prediction units to try.\n" " 0: 64x64, 1: 32x32, 2: 16x16, 3: 8x8, 4: 4x4\n" " --no-info : Don't add information about the encoder to settings.\n" - " --gop : Length of Group of Pictures, must be 8 or 0 [0]\n" + " --gop : Definition of GOP structure [0]\n" + " \"0\": disabled\n" + " \"8\": B-frame pyramid of length 8\n" + " \"lp-\": lp-gop definition (e.g. lp-g8d4r3t2)\n" " --bipred : Enable bi-prediction search\n" " --bitrate : Target bitrate. [0]\n" " 0: disable rate-control\n" " N: target N bits per second\n" - " --preset : Use preset\n" + " --preset : Use preset. This will override previous options.\n" " ultrafast, superfast,veryfast, faster,\n" " fast, medium, slow, slower, veryslow, placebo\n" " --no-psnr : Don't calculate PSNR for frames\n" @@ -383,12 +386,12 @@ void print_help(void) " Disable threads if set to 0.\n" "\n" " Tiles:\n" - " --tiles-width-split |u : \n" + " --tiles-width-split |u :\n" " Specifies a comma separated list of pixel\n" " positions of tiles columns separation coordinates.\n" " Can also be u followed by and a single int n,\n" " in which case it produces columns of uniform width.\n" - " --tiles-height-split |u : \n" + " --tiles-height-split |u :\n" " Specifies a comma separated list of pixel\n" " positions of tiles rows separation coordinates.\n" " Can also be u followed by and a single int n,\n" @@ -399,7 +402,7 @@ void print_help(void) " --owf |auto : Number of parallel frames to process. 0 to disable.\n" "\n" " Slices:\n" - " --slice-addresses |u: \n" + " --slice-addresses |u :\n" " Specifies a comma separated list of LCU\n" " positions in tile scan order of tile separations.\n" " Can also be u followed by and a single int n,\n" diff --git a/tools/update_readme.sh b/tools/update_readme.sh new file mode 100755 index 00000000..1430947d --- /dev/null +++ b/tools/update_readme.sh @@ -0,0 +1,35 @@ +#!/bin/bash + +# This file is part of Kvazaar HEVC encoder. +# +# Copyright (C) 2013-2016 Tampere University of Technology and others (see +# COPYING file). +# +# Kvazaar is free software: you can redistribute it and/or modify +# it under the terms of the GNU Lesser General Public License version 2.1 as +# published by the Free Software Foundation. +# +# Kvazaar is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Kvazaar. If not, see . + +if [[ $# != 1 ]]; then + printf "Usage: $0 README.md\n" + exit 1 +fi + +tmpfile="$(mktemp)" + +{ + sed '/BEGIN KVAZAAR HELP MESSAGE/q' -- "$1"; + printf '```\n'; + kvazaar --help; + printf '```\n'; + sed -n '/END KVAZAAR HELP MESSAGE/{:a;p;n;ba}' -- "$1"; +} >> "$tmpfile" + +mv -- "$tmpfile" "$1"