software-manual.tex

\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.8\linewidth]{figures/YUView}
  \caption{YUView}
  \label{fig:yuview}
\end{figure}

\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.5\linewidth]{figures/raceHorsesShot2MotionVectors}
  \caption{Motion vectors}
  \label{fig:motion-vectors}
\end{figure}


\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.5\linewidth]{figures/raceHorsesShot3SkipFlag}
  \caption{Skip flag}
  \label{fig:skip-flag}
\end{figure}

\subsection{Adding statistics}
\label{sec:adding-statistics}

In order to add further block statistics, do the following:


\begin{description}
\item[source/Lib/CommonLib/dtrace_blockstatistics.h]
  Add your statistic to the BlockStatistic enum:	
\begin{minted}{c++}
enum class BlockStatistic {
  // general
  PredMode,
  PartSize,
  Depth,
\end{minted}
  
Further, add your statistic to the map blockstatistic2description:
\begin{minted}{c++}
static const std::map<BlockStatistic, 
  std::tuple<std::string, BlockStatisticType, std::string>> 
  blockstatistic2description =
{
  { BlockStatistic::PredMode, 
    std::tuple<std::string, BlockStatisticType, std::string>
    {"PredMode", BlockStatisticType::Flag, ""}},
  { BlockStatistic::MergeFlag,
    std::tuple<std::string, BlockStatisticType, std::string>
    {"MergeFlag", BlockStatisticType::Flag, ""}},
  { BlockStatistic::MVL0,
    std::tuple<std::string, BlockStatisticType, std::string>
    {"MVL0", BlockStatisticType::Vector, "Scale: 4"}},
  YOURS
\end{minted}


\item[source/Lib/CommonLib/dtrace_blockstatistics.cpp] All code for
  writing syntax elements is kept in this file in
  getAndStoreBlockStatistics. This function is called once for each
  CTU, after it has been en/decoded. The following macros have been
  defined to facilitate writing of block statistics:
\begin{minted}{c++}
DTRACE_BLOCK_SCALAR(ctx,channel,cs_cu_pu,stat_type,val)   
DTRACE_BLOCK_SCALAR_CHROMA(ctx,channel,cs_cu_pu,stat_type,val)
DTRACE_BLOCK_VECTOR(ctx,channel,cu_pu,stat_type,v_x,v_y)    
DTRACE_BLOCK_AFFINETF(ctx,channel,pu,stat_type,v_x0,v_y0,v_x1,v_y1,v_x2,v_y2) 
\end{minted}

An example:
\begin{minted}{c++}
DTRACE_BLOCK_SCALAR(g_trace_ctx, D_BLOCK_STATISTICS_ALL, 
  cu, GetBlockStatisticName(BlockStatistic::PredMode), cu.predMode);
\end{minted}


\item[Block statistics for debugging] The statistics can also be used
  to write out other data, not just syntax elements. Add your
  statistics to dtrace_blockstatistics.h. Where it should be used the
  following headers have to be included:
\begin{minted}{c++}
#include "dtrace_next.h"
#include "dtrace_blockstatistics.h"
\end{minted}
\end{description}





\section{Using the stream merge tool}
\label{sec:stream-merge-tool}

The StreamMergeApp tool takes multiple single-layer (singe nuh_layer_id) bistreams 
as inputs and merge them into a multi-layer bistream by interleaving the Picture Units
from the input single layer bistreams. During the merge, the tool assigns a new unique
nuh_layer_id for each input bitstream as well as unique parameter sets identifiers for each layer.
Then the decoder can specify which layer bitstream to be decoded through the command line option "-p nuh_layer_id".

Some current limitations of the tool:
\begin{itemize}
\item All input bitstreams are single layer and thus all layers in the output bitstream are independent layers.
\item Each layer in the output bitstream is abitrarily put in an individual OLS and is also an output layer.
\item All parameter sets from the input bitstreams are treated as different parameter sets. There is thus no parameters sets sharing in the output bitstream.
\item The slice header in the input bitstreams shall contain no picture header structure and no alf information.
\end{itemize}


\subsection{Usage}
\label{sec:stream-merge-usage}

\begin{minted}{bash}
StreamMergeApp 	<bitstream1> <bitstream2> [<bitstream3> ...] <outfile>
\end{minted}

The command line options bistreamX specify the file names of the input single-layer 
bistreams. At least two input bitstreams need to be specified. The merged multi-layer 
bistream will be stored into the outfile.




\section{Using the subpicture merge tool}
\label{sec:subpicture-merge-tool}

The SubpicMergeApp takes multiple bitstreams as inputs and merges them into one output bitstream where each input bitstream forms a single subpicture. Subpicture layout and input bitstreams are defined in a subpicture list file. Sequence parameter set and picture parameter set are modified accordingly based on the layout.

The merge tool has an alternative mode for merging YUV files. This mode can be used for verifying YUV output after decoding merged bitstream.

If VTM encoder is used for encoding input bitstreams, it is recommnended that ALF, CCALF, joint chroma coding, LMCS and AMaxBT are disabled. This prevents those tools having parameters with different values in different subpictures which would result in merged bitstream being non-conformant.

\subsection{Usage}
\label{sec:subpicture-merge-usage}

\begin{minted}{bash}
SubpicMergeApp [-l <subpiclistfile>] [-o <outfile>] [-m 0|1] [-yuv 0|1] [-d <bitdepth>] [-f 400|420|422|444]
\end{minted}

\begin{table}[ht]
\footnotesize
\centering
\begin{tabular}{lp{0.5\textwidth}}
\hline
 \thead{Option} &
 \thead{Description} \\
\hline
\texttt{--help} & Prints parameter usage. \\
\texttt{-l} & File containing list of input pictures to be merged \\
\texttt{-o} & Output file name \\
\texttt{-m} & Enable mixed NALU type bitstreams merging \\
\texttt{-yuv} & Perform YUV merging (instead of bitstream merging) \\
\texttt{-d} & Bitdepth for YUV merging \\
\texttt{-f} & Chroma format for YUV merging, 420 (default), 400, 422 or 444 \\
\hline
\end{tabular}
\end{table}

Format of the subpicture list file given with '-l' command is as follows:

\begin{minted}{bash}
subpic1_width  subpic1_height  subpic1_x  subpic1_y  subpic1_bitstream_file
subpic2_width  subpic2_height  subpic2_x  subpic2_y  subpic2_bitstream_file
...
subpicN_width  subpicN_height  subpicN_x  subpicN_y  subpicN_bitstream_file
\end{minted}

Coordinates x and y define the location of top-left corner of the subpicture in the merged picture. Parameters width, height, x and y are given in units of luma samples.

YUV merging uses the same file format, only difference being that YUV file name is supplied instead of bitstream file name.

\end{document}