HARP Toolkit

Tutorial - Basic Usage

The following is meant for the older version v1.0:

This tutorial provides a first, easy example of how to use HARP on the command line. We recommend that you start with this tutorial, since it also serves as a self check of your compiled HARP binaries. Make sure you see what is depicted below, and only then proceed to the other tutorials.

Before you start: make sure that you have successfully installed all prerequisites and compiled HARP by changing into its directory and running the build script (see How To Compile).

Please report any bugs you find to dominic[DOT]h[DOT]springer[AT]gmail.com
Thank you!

To run HARP for the first time, just change into the HARP directory and execute the script run_examples.sh. Give it a minute or two. The script runs the HM encoder TAppEnc for each of the three different HM configurations lowdelayP, lowdelay, and randomaccess. Under ./tmp, the script generates numerous visualizations for each POC and configuration. For the lowdelayP configuration, you should see the following (from left to right, top to bottom: original POC, prediction units, reference indices, transform units):

     
     

Example: Running the HM Encoder

Lets have a look at how the script calls the encoder to produce the above images (current working directory is ./tmp)

../bin/TAppEncoder -c ../Src_HM/cfg/encoder_lowdelay_P_main.cfg -i ../Various/Resources/Special/LMS_Logo_640x360.yuv --SourceWidth=640 --SourceHeight=360 --QP=10 --FrameRate=30 --InputBitDepth=8 --FrameSkip=0 -f 3 -b encoder_lowdelay_P_main/str.bin -o encoder_lowdelay_P_main/rec.yuv --HARP_ObsPOCs=0,1,2,3 --HARP_ObsCTUs=14 --HARP_PUs --HARP_TUs --HARP_RefIndices --HARP_UnitCloseup --HARP_RDO --HARP_TmpDir=encoder_lowdelay_P_main

All arguments up to "-o" are described by the HM documentation and are not HARP-related. For a comprehensive list of HM's arguments, run ../bin/TAppEncoder --help. HARP itself is controlled by the arguments starting with the --HARP prefix. The following will activate all major analysis tools of HARP, including the CTU-focused unit closeup and RDO analysis:
--HARP_PUs --HARP_TUs --HARP_RefIndices --HARP_UnitCloseup --HARP_RDO

HARP's output directory defaults to  "./". Use --HARP_TmpDir=[TmpDir] to specifiy a different directory. For safety reasons, it must be relative and is not allowed to lie outside the HARP directory.

The last two arguments advise HARP to only export information about POCs 0 to 3, with the CTU closeups and the RDO analysis only rendered for CTU 14:
--HARP_ObsPOCs=0,1,2,3 --HARP_ObsCTUs=14 

Example: Running the HM Decoder

The script also calls the decoder after each of the encoder bitstreams has been created. For the LowDelay-P configuration, the decoder call looks like this (current working directory is ./tmp)

../bin/TAppDecoder -b encoder_lowdelay_P_main/str.bin -o encoder_lowdelay_P_main/rec_DEC.yuv --HARP_TmpDir=encoder_lowdelay_P_main

Respite some encoder-only information (like original pixel data in PicOrg, or RDO information), the CTU tree information in PyPOC*.pkl resembles the information of the encoder-generated PyPOC*.pkl files. You can double check HARP by adding --HARP_PUs to the decoder command line.

Are you new to HEVC and HM and plan to do some modifications?

If so, the CTU closeup is probably a good starting point. Run the script run_examples.sh (see above) to generate some CTU closeups for a start! You can safe a lot of time by just having a look on how HM's classes and structs are accessed in the file CShow_UnitCloseup.h. Especially the recursive quadtree processing and the z-scan/raster-scan indexing of HM's atomic data units (so called storage units, SU) may be difficult due to the scarce documentation. So relax, get a tee and take your time comparing the created image POC00002_UnitCloseup_CTU0014.png to the source code until you get an idea of how HM accesses its data structures. It will take some time, so be patient! :)

For the above example, the CTU closeup looks like this:

Compare this closeup of CTU 14 to the overview of all prediction units (top right in the above 2x2 image table, click to enlarge). The CU modes of this closeup directly resemble those in the prediction unit overview. The source file CShow_UnitCloseup.h, which creates the above closeup, makes sure that all important HM encoder information is printed in each CU. If you are planing to work on the HM code base for the first time, we recommend that you start with the AbsIdxInLCU variable: it behaves in z-scan order and is directly related to the recursive quadtree processing. Try to understand how it is incremented in z-scan order from CU to CU. AbsIdxInLCU is also essential for calculating absolute pixel positions of Coding Units (CUs), Prediction Units (PUs), Transform Units (TUs), or Motion Vectors (MVs). Look at the code of CShow_UnitCloseup.h to get an idea of how this works.