YUView Help

Welcome to YUView. At it's core, YUView is a platform independent powerful viewer and player of raw video files in the YUV format. A multitude of different YUV formats as well as different conversions to RGB are supported. Furthermore, YUView supports raw RGB files, various types of image sequences, coded HEVC files, an overlay of statistics, comparison tools and the list goes on.

In the following, we want to provide an overview of YUView and all of its features as well as some valuable hints:

1. The Main Window
2. Supported File Formats
3. Keyboard Shortcuts and State Handler

## 1. The Main Window

The main window of YUView is organized around one central view where the video and other items are displayed. Around this central widget, there are several dockable panels that provide various functions. All panels are freely movable and un-dockable. (Hint: The default layout of the dockable panels can be restored under Help->Reset Window Layout) In the following we will go into detail on the central view and the panels one by one:

### 1.1. The central view and the Display Options Panel

Everything in YUView revolves around the central view. Here, the item that is currently selected in the playlist is shown. Use the left mouse button to drag the view and the right mouse button to zoom into a specific region in the item. Furthermore, you can zoom in and out using the mouse wheel or the '+' and '-' buttons. Use Ctl+F or double click the view to put it into full screen mode. Some more features of the central view can be controlled in the display options panel:

- Split- and comparison view: This feature enables the direct comparison of two items. Activate the split and select two items in the playlist. A vertical line will split the view into two parts. This split line can be moved with the mouse. The two items will be shown each on one of the two sides. There are two modes how the items can be arranged:
  - Side-By-Side: The two items are shown next to each other so that the same region of each item is shown in it's corresponding view. This way, the same region in two items can be directly compared.
  - Comparison: In comparison mode, the two items are placed at the same position (on top of each other) and the vertical split line can be used to switch between the two items.
- Separate View: The separate view enables an additional windows, which has an identical sibling to the central view in the main view. It has the same features as the other central view (moving, zooming, splitting, going to full screen...). You can link the two views by activating Link Views. If active, both views will always show the same section of the item(s). All operations (moving, zooming etc.) will also show in the other view. This mode is great for presenting with two computer screens. Put the separate view on the external screen and keep full control on the primary screen. For performance reasons, playback only runs on the separate view. Activate Playback in primary view to enable playback in both views.
- Draw Grid: Draw a regular grid on top of the item with the given distance (in pixels) between grid lines. The color of the lines can be changed in the settings dialog.
- Zoom Box: The zoom box is an overlay in the bottom right of the central view that provides a magnification as well as detailed information about the pixel currently under the mouse cursor. If present, it also gives information about the shown statistics values.

Hint 1: You can reset the central view by pressing Ctrl+0
Hint 2: The central view supports touch navigation and touch gestures (3 finger horizontal to switch frames, 3 finger vertical to switch sequences)

### 1.2. The Playlist Panel

The playlist contains a list of items that will be played back from top to bottom (if the repeat mode is set to repeat all of course). This can be files that were opened (like YUV or HEVC files) or other special types. Within the playlist you can rearrange items by dragging them around. Some special items also allow other items to be dropped onto them. Items can be added by opening a file (File->Open, Right mouse click onto the playlist or the button underneath the playlist) or right clicking onto the playlist and creating one of the special items:

- Text frame: A text frame renders a text in the middle of the screen for a specific amount of time. This is very helpful for visual tests or for demonstrations to indicate what is going to be displayed next. In combination with an overlay, it can render additional information on top or next to a video.
  Hint: The text frame understands HTML syntax.
- Difference Sequence: A difference sequence can calculate and display the pixel wise difference between two items. If both items are YUV files, the difference will be calculated directly in the YUV domain. Information on the calculation can be found in the info panel. Just drop two files onto this item to calculate the difference. The difference can be amplified by the amplification factor in the properties panel.
  Hint: Activate the zoom box to inspect the original values of both items and the difference value.
  Hint: If you mark two items, right click on one of them and then click "Add Difference Sequence", the selected items will automatically be added to the difference.
- Overlay: An overlay just draws all the items that it contains on top of each other in the order they are in the playlist. Drop two or more items onto the overlay to show them both. The alignment of the items can be set in the properties panel.
  Hint: If you mark one or more items, right click on one of them and then click "Add Overlay", the selected items will automatically be added to the overlay.

### 1.3. The Properties Panel

The properties panel can be used to change the properties of the currently selected item. The controls in this panel depend on the kind of item that is currently being selected. The specific controls are explained later but the controls that most items have in common are explained here.

Firstly, all items that are index by frames (like a video or image sequence) offer the following controls:

The start and end frame controls can be used to display only a subset of all frames in the sequence. E.g. you could select to only display the first 100 frames. The navigation bar will change accordingly. The rate control will set the desired playback rate. YUView will try to get as close as possible to this rate. If playback is too slow, try to increase/activate the cache. Finally, the sampling control can be set to only display every nth frame in the sequence and skip the frames in between.

With the second set of controls, the Frame size (width and height) of the sequence can be changed. The size can either be defined freely or the frame size drop-down offers a set of commonly used video sizes.

All items that are shown statically for a certain amount of time (like text items or images) do not offer these controls. Instead a duration control allows you to control the time that the item is displayed for if playback is running.

### 1.4. The Navigation Bar

The navigation bar at the bottom of the window is similar to the navigation bars known from other media players. Playback can be started, paused and stopped. There is a horizontal slider and a spin box next to it for navigation within the selected sequence. When playback is running, the label next to the spin box will inform you about the currently drawn frame rate. Lastly, the repeat mode can be switched using the button on the right:

- Repeat Off: Repeat is off. When the end of the current item is reached, the next item in the playlist will be played. If the last frame of the last item in the playlist is reached, playback is stopped.
- Repeat One: Repeat the currently selected item. If the end of the current item is reached, playback will start over at the beginning of the currently selected item.
- Repeat All: Repeat the entire playlist. When the end of the current item is reached, the next item in the playlist will be played. If the last frame of the last item in the playlist is reached, playback will continue with the first item in the playlist.

### 1.5. The Info Panel

The info panel provides additional information on the item that is currently selected in the playlist. It sometimes also provides warnings.

## 2. Supported File Formats

YUView supports a wide variety of file formats. Just use the File->Open dialog to load the files into the playlist.

### 2.1 YUV Files

Firstly, YUView of course supports raw YUV formats with a wide range of subsampling modes, bit depths and packing options. When you open a YUV file, firstly, YUView will try to obtain the frame size and the YUV format from the file name. YUView recognizes the explicit frame size and frame rate indication separated by underscores like: "Something_2160x1440_60_8_more.yuv". In addition, the common size indication names like CIF, 1080p or VGA are supported. If the size could not be obtained from the filename, YUView will try to guess the size from the first two frames of the raw YUV data. Of course the frame size and other settings can also be changed in the properties panel. The following properties are specific to files that provide data in the YUV format:

- Scale, Offset, Invert: For the luma and chroma component, a scale, an offset and (optionally) inversion can be set to transform the YUV values before transformation to RGB. The value difference to offset is scaled by scale relative to offset. The used equation is:

  YOut = inv*(YIn-offset) * scale + offset; (inv is -1 if inversion is activated and 1 if not)

- YUV Format: Here you can select the YUV format or the raw input data (subsampling, bit depth...). Select one of the predefined formats or select 'custom...' to define a custom format (see below).
- Color Components: Which of the YUV components should be displayed? You can choose all or the luma or one of the color planes individually.
- Chroma Interpolation: If the color components are subsampled, how should interpolation to the full resolution be performed?
- Color Conversion: How to convert YUV to RGB. Several ITU recommendations are selectable.

If the required YUV format of the raw input data is not in the YUV format list, select "Custom..." to configure a specific YUV format:

- Chroma Subsampling: How is the chroma component subsampled? Various subsampling modes are supported:
  - 4:4:4: There is no subsampling
  - 4:2:2: Subsampling by a factor of 2 in horizontal direction
  - 4:2:2: Subsampling by a factor of 2 in horizontal and vertical direction
  - 4:4:0: Subsampling by a factor of 2 in vertical direction
  - 4:1:0: Subsampling by a factor of 4 in horizontal and vertical direction
  - 4:1:1: Subsampling by a factor of 4 in horizontal direction
  - 4:0:0: Luma only. No chroma components are present.
- Bit Depth: How many bits per color component are there? If the bit depth is greater than 8, we will assume multiple bytes per component.
- Endianness: If the bit depth is greater 8 (there are multiple byte per value), what is the order of these bytes? Big endian (most significant byte first) or little endian (least significant byte first).
- Chroma Offset: At what position, relative to the luma position are the chroma samples placed? A shift of 0 means the positions are aligned. A value of 0.5 refers to the position between two luma samples. All offsets are positive and shift the position to the right and down. The figure above illustrates an example for 4:2:0 subsampling (both horizontal and vertical direction are subsampled by a factor of 2). The squares mark the positions of the luma samples. The circles mark all possible chroma positions relative to the luma position with their respective coordinates (x,y). For a subsampling of 4:2:0, the position (0, 0.5) is the default position. For all other subsampling modes, (0,0) is assumed as the default.
  Hint: For the actual conversion to RGB, also the interpolation mode must be considered. For example, if nearest neighbor interpolation is selected, there is no difference between a chroma offset of 0 and 0.5.
  Hint: Zoom in until the YUV values are shown on top of the pixels. Here, the values for U and V are drawn shifted according to the current shift settings.
- Planar or Packed: The raw values can be sorted in two different ways: Planar or Packed...

### 2.2 RGB Files

Another raw format that YUView supports are raw data in the RGB format. As for YUV files, the size of the sequence can be set using the width/height controls or a predefined size can be set using the frame size drop-down. The following properties of RGB items can be set:

- RGB Format: Configure the format of the raw RGB data. Select one of the predefined formats or "Custom..." to edit a custom RGB format (see below).
- Components: Choose which of the three components you want to display. R, G, B or all.
- Scale and invert: Scale every value of the component by the given factor and apply inversion if set.

The format of the raw RGB data can be configured in the RGB format drop-down. If the required format is not in the list of presets, a custom format can be configured using the "Custom..." entry:

- RGB Order: In what order are the components (R,G,B) ordered in the bitstream? There are 6 possible combinations.
- Bit Depth: How many bits per pixel and component are there? If the bit depth is greater 8, more than one byte per pixel is assumed.
- Planar: Are the values in the bitstream sorted by components (planar) or sorted by pixel (packed): Planar: All values of each color component are collocated in the file. The file is organized by color planes. (E.g.: RRRRGGGGBBBB)Non planar: All components of each pixel are collocated in the file. The file is organized by pixels. (E.g.: RGBRGBRGBRGB)
- Alpha Channel: Is there an additional alpha channel after the RGB values?

### 2.3 Image files and Image Sequences

Since Qt already supports loading of images in various formats, YUView also makes use of this feature. A single image will be opened as a playlist item that is shown for a specific amount of time. If the image name contains a number at the end (E.g. Something00001.png), YUView will try to look for a numbered image sequence. The image sequence will behave like any other video sequence (the start/end frame, frame rate and the sampling can be set).

### 2.4 Statistics Files (.csv)

YUView supports a special kind of plain text CSV file. This file can contain raw (integer) values or (integer) vector values for a range of blocks within a range of frames. Basically, there is a list of entries, where each entry contains 8 values: A frame index, a x and y position of the block in pixels, the width and height of the block in pixels, a type ID, the value (one integer for pure values, 2 integers for vectors). The type ID then refers to a header entry, that defines, how the values can be mapped to color or how the vectors are drawn. YUView then takes this information, maps the values to colors and draws correspondingly colored blocks and/or vectors to the screen.

If you write some code to generate these files directly in the encoder/decoder, you can display virtually any data per block or vectors per block in YUView. This could include for example coding modes, cost per block, prediction modes or motion vectors. Hint: Move the statistics file and the corresponding reconstruction video into an overlay to show the data on top of the reconstruction. Please refer to the CSV file Wiki page for a detailed explanation of the CSV file format.

On the left, the controls are shown for an item that can provide statistics (in this example it's an HEVC file). For every statistic type, drawing can be enabled individually using the check box. The opacity control is especially useful if the statistic file is placed in an overlay with the reconstruction. The modify button on the right allows you to modify how the values are rendered (how are values mapped to colors and how is the information rendered).

The middle image shows the statistics rendering editor. The editor is split into 3 parts, where it depends on the statistics item which of the parts are available.

Draw Block Data
  This block is available for all statistics types that provide block value data (non vector data) and allows you to control how this block data is rendered. Block data is basically a value (integer) that is associated to a specific block in a specific frame. So here, it can be controlled how the values are mapped to colors. The color mapping preview on the top gives a preview of the mapping. All changes to this dialog are also directly applied in the main window. In the Color Mapping drop down, the type of mapping from value to color can be chosen. There are 3 basic types of mapping:
  - Custom Color Gradient: The custom gradient is defined by a minimum and maximum value and by two corresponding colors. The minimum value will be mapped to the first color and the maximum value to the second color. The colors of all values in between the minimum and maximum value are linearly interpolated. If a value is not within the value interval, it will be clipped to the boundaries of the interval. The two colors can be set by the Custom Range color controls and the minimum and maximum value are set using the Value Range spin boxes.
  - Color Map: A color map is an explicit mapping where each value is mapped to an individual color. If there is no value/color entry in the color map, a default color will be used. Press the Edit Color Map button to open a dialog that enables editing of the color map (right image). Just double click the numbers and the colors to edit their value. Add new entries with the "+" button and delete entries with the "X" button. The default entry is at the button and the color component of this entry can also be edited.
    Hint: Use the Edit Color Map button to convert any currently set color mapping to a color map.
  - Predefined mappings: The remaining entries in the drop down are predefined color mapping (like jet, heat ...). Some of these might seem familiar from other plotting tools. For these predefined mappings, only the minimum and maximum value can be changed.

  Finally, with the Value Scaling option you can enable scaling of the value according to the size of the block if this was not already done on the input data.

Draw Vector Data
  This block is available for all statistics types that provide vector data and controls how the vectors are rendered. These setting include: Line style, line width, the vector head and vector color. If Scale width to zoom is activated, the line width will increase the further you zoom in (the vector thickness will increase when zoomed in). Finally Map direction to color allows you to color the vectors according to their direction. The jet color mapping is used for this.
Draw Grid
  The grid control block is available for all statistics items. As it was already mentioned, each entry (value or vector) is defined for a specific block. Here it can be controlled how (and if) a rectangle around this block is drawn. Here, the color, the line style and the line width of this boundary rectangle can be set up. Again, if Scale width to zoom is activated, the line width will increase the further you zoom in (the rectangle thickness will increase when zoomed in).

### 2.5 HEVC Files

YUView can directly open h.265/HEVC encoded files in YUView. Just use file->Open. If the file extension is .hevc, YUView will try to use libde265 to open the file. In addition to the reconstructed video, the modified version of libde265 (libde265_internals) can also provide statistics directly from the bitstream like motion vectors, prediction modes and many more. Just select a statistic type in the properties panel to display the statistics.

Note: The only supported file format is the h.265/HEVC Annex B raw file format. In this raw file format, each NAL unit starts with a predefined start code (0x00 0x00 0x00 0x01) followed by the NAL unit header and the NAL unit payload data. There is no header of the file and no support for multiple streams / audio etc. This is the file format that the HEVC reference test model software (HM software) uses. There is no support for containers like .mkv or .mp4.

## 3. Keyboard Shortcuts and State Handler

Here we want to give a list of keyboard shortcuts and mention the state handler feature. The state handler can save the current state of the view into one of 8 slots. This state includes the currently selected items, the selected frame number, the state of the splitting, the zoom factor and the view position. Use Ctrl + (1..8) to save the current state in one of the slots and the keys 1 to 8 to recall a slot. This also works with the separate view and linked views.
Note: The states are saved to/loaded from the playlist.

Finally, here is a list of all keyboard shortcuts:

Shortcut | Effect
--- | ---
Ctrl + S | Save the current playlist to file.
Delete | Remove the currently selected playlist item from the playlist.
Crtl + 0 | Reset the zoom to 1x and center the current item in the view.
Ctrl + 9 | Set the zoom so that the entire image is visible in the current view.
Ctrl + '+' | Increase the zoom factor.
Ctrl + '-' | Decrease the zoom factor.
Ctrl + L | Show/Hide the playlist dock widget.
Ctrl + D | Show/Hide the display options dock widget.
Ctrl + P | Show/Hide the item properties dock widget.
Ctrl + I | Show/Hide the file info dock widget.
Ctrl + F | Toggle full screen.
Ctrl + W | Toggle the separate view.
Space | Toggle play/pause.
Up / Down | Switch to the next/previous item in the playlist.
Left / Down | Go to the previous/next frame in the sequence.
Ctrl + (0..8) | Save the current view state (zoom factor, position, frame, playlist item) in one of the slots.
(0..8) | Recall the view state from one of the slots.