VQ Probe v1.4 User Guide

Contents


Legal

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH VICUE SOFT PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN VICUE SOFT'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, VICUE SOFT ASSUMES NO LIABILITY WHATSOEVER AND VICUE SOFT DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF VICUE SOFT PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. UNLESS OTHERWISE AGREED IN WRITING BY VICUE SOFT, THE VICUE SOFT PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE VICUE SOFT PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR.

ViCue Soft may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." ViCue Soft reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.

The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.

Contact your local ViCue Soft sales office or your distributor to obtain the latest specifications and before placing your product order.

MPEG is an international standard for video compression/decompression promoted by ISO. Implementations of MPEG CODECs, or MPEG enabled platforms may require licenses from various entities, including ViCue Soft.

*Other names and brands may be claimed as the property of others. Copyright © 2020, ViCue Soft. All Rights reserved.

Overview

VQ Probe is a software tool for Video Elementary Stream visual comparison.

The tool shipped as a Graphical User Interface application for Windows, MacOS and Linux.

Supported Video Codecs

  • H.264/AVC
  • H.265/HEVC
  • H.266/VVC (4:2:0 only)
  • AV1
  • MJPEG

Supported Uncompressed Formats

  • YUV
  • Y4M

Supported Chroma Subsampling

  • 4:2:0
  • 4:2:2
  • 4:4:4

Supported Bit Depth

  • 8 bit
  • 10 bit

Supported Video Metrics

Offline Activation

VQ Probe requires your computer to be connected to the Internet to start your trial period. If you have no internet connection, or have restricted internet access, then you have the option of activating your copy of VQ Probe offline. To do so:

  1. Choose to Help > Offline Activation.... A dialog will be opened: Activation Dialog
  2. Press Next button. The next page will appear: Activation Dialog: Activation Type
  3. Offline Activation is already chosen. So just press Next Button again. An instruction will appear: Activation Dialog: Get the Product Key
  4. Login to https://portal.vicuesoft.com with the email you used to download VQ Probe.
  5. Go to Licenses page [https://portal.vicuesoft.com/private/licenses] (https://portal.vicuesoft.com/private/licenses)
  6. Press Generate Key next to your VQ Probe license: ViCueSoft Customer Portal: Generate Key
  7. A key will be generated: ViCueSoft Customer Portal: Generated Key
  8. Copy it. Return to VQ Probe application's Offline Activation Dialog and paste it: Activation Dialog: Product Key
  9. Press Generate Request File button and choose the location where the generated file should be saved.
  10. Once Save button is pressed, the file will be generated. In case of success, the green message will appear under the button, and you can go to next wizard's page: Activation Dialog: Generate Key Success Message Otherwise, a red error message will appear: Activation Dialog: Generate Key Error Message Please fix the issue and atry to generate file again.
  11. Return back to the Customer Portal and click Offline Activation button: ViCueSoft Customer Portal: Offline Activation Button
  12. Next, you will see the page of VQ Probe offline activation. PressChoose File button: ViCueSoft Customer Portal: Uploading Request File
  13. In the opened dialog choose the file you have created in step 10. Then press Upload button.
  14. A Response File will be downloaded automatically to your default downloads folder.
  15. Go to VQ Probe, press Upload Response File and choose the file you have just received: Activation Dialog: Uploading Response File
  16. In case of no errors you will see the green message: Activation Dialog: Activation is Done Congratulations! Your copy of VQ Probe is activated. In case of red error message please check your key, make sure you have chosen the correct files, and then try again.
NOTE In case of any difficulties please ask us for help by writing at [info@vicuesoft.com](mailto:info@vicuesoft.com).

Graphical User Interface Overview

The main window of VQ Probe has the following elements:

  • Project View
  • Playback View
  • Quality Metrics View
Main Window

Main Window

Project View

The window used to setup and manage your workspace: add and remove video files, select which ones will be displayed in Playback View, create and remove RD Curves, set RD Curve anchor used for BD Rate calculation.

Project View

Project View

The view can be shown or hidden by using Window > Project View from the main menu, or by using hotkeys (Shift + Cmd + P on Windows and Linux, or Shift + Cmd + P on MacOS).

Playback View

Playback View

Playback View

  • left file area displays a part of the current frame of the left file
  • right file area displays a part of the current frame of the right file
  • vertical split line is placed between two images; it allows the user to change the width of the left and right images
  • buttons to choose which component(s) are shown:
  • YUV: show YUV
  • Y: show only Y plane
  • U: show only U plane
  • V: show only V plane
  • buttons to choose the format of numbers in Playback View
  • dec: show numbers as decimal
  • hex: show numbers as hexadecimal
  • view mode:
  • L|R: show left and right files divided by the splitter line
  • Ref: show reference file
  • L|R / Ref Diff: show the difference of left and reference files on the left, and the difference of right and reference files on the right side of the screen
  • navigation buttons:
  • first frame: go to first frame
  • previous frame: go to previous frame
  • play/pause: start playback or pause, respectively
  • next frame: go to next frame
  • last frame: go to last frame

All buttons are duplicated by the appropriate items in the Playback menu. Hotkeys are also available for the buttons listed above. Please follow the main menu for exact hotkeys depending on the Operating System you use.

NOTE The left or right area might not display frame after navigation. This implies that there is no corresponding frame in the appropriate file where the other file has a frame with the same frame number. This happens if opened files have different numbers of frames.

Quality Metrics View

Quality Metrics View

Quality Metrics View

The view consists of the following elements:

  • two tabs:
  • Metrics: the one contains regular metric values for each file
  • L/R Quality Diff shows the difference between metrics of the file on the right side and the one on the left side
  • RD Curves contains RD Curves (if exists) as well as BD Rate information
  • Metric combo-box to choose a metric to display on the main area. That could be one of the following:
  • PSNR YUV, PSNR Y, PSNR U, PSNR V
  • SSIM YUV, SSIM Y, SSIM U, SSIM V
  • VMAF YUV, VMAF Y, VMAF U, VMAF V
  • Run/Stop buttons are to start or stop, respectively, metrics calculation

Run button is disabled if a reference file is not opened. Once the user clicks the Run button, it is replaced by the Stop button. And vice versa: once the user clicks Stop, or when the metrics calculation process is done, Run appears again, and replaces the Stop button.

Quality Metrics View can be hidden or shown by checking or unchecking Window > Metrics View, or by using hotkeys (Shift + Cmd + M on Windows and Linux, or Shift + Cmd + M on MacOS).

Functionality

Project

Once Vq Probe is launched, it has an empty project by default. You may open a project saved before, or, you can setup the project for your needs from scratch. To do so, start from adding source files.

Add Source File(s)

By source files we assume video files that are used in analysis and metrics calculation, as well as any other operations within VQ Probe. These could be uncompressed files as well as encoded files.

Source file(s) can be added to the current project in several ways:

  • via Project View
  • By pressing "+" button on Source Files panel of Project View. The standard system open files dialog will be opened. Select one or more files and press Open button. Selected files will be analyzed then. If the file(s) are valid and supported by VQ Probe, they will be added to the list of files. Otherwise, a message box with error description will appear.
  • by dropping file(s) on the Playback View. File(s) will be added to Project View

Now, when files are successfully opened, their information is displayed on the screen: codec, resolution, bitrate, framerate (default 25 is used), and frame count.

Project View: Add Source File(s)

Project View: Add Source File(s)

NOTE Files must have the same resolution as well as the same chroma subsampling format.

Possible reasons why file(s) cannot be added are:

  • the file(s) is not supported (please follow appropriate section for the list of supported formats)
  • the files have different resolution and/or chroma subsampling format
  • an internal application error

Remove Source File(s)

Select one or more files from the list on Source Files tab and press right mouse button. In the opened menu choose Remove.

Project View: Remove Source File(s)

Project View: Remove Source File(s)

Select Files Displaying

Use checkboxes from Left, Right or Ref columns to set appropriate file as to be displayed as left, right or reference, respectively, on Playback View:

Project View: Select Files for Displaying

Project View: Select Files for Displaying

Create RD Curve

Press right mouse button at any empty space or on any RD Curve item on RD Curves tab. Choose Add RD Curve from the opened menu. Enter a name for the new RD Curve and press OK button.

Add Curve

Add Curve

You cannot also choose the name of any existing RD Curve. You cannot also choose the name of any already existed RD Curve. In both cases you will be prompted to choose another name.

Remove RD Curve(s)

Press right mouse button on any one or more RD Curves on RD Curves tab, then choose Remove from the opened menu.

Remove RD Curve(s)

Remove RD Curve(s)

Add Source File(s) to RD Curve

Select one or more source files on Source Files tab, then select Add to RD Curve menu item. You will see the list of RD Curves where it's allowed to add the selected source files:

Add Source File(s) to RD Curve

Add Source File(s) to RD Curve

Selected source files from the example above cannot be added to AVC nor HEVC RD Curves because they are already added.

NOTE Reference file cannot be added to an RD Curve.

Once you added source file(s) to an RD Curve, they will appear in the list of RD Curves:

Newly Added Source File(s) in RD Curve List

Newly Added Source File(s) in RD Curve List

Remove Source File(s) from RD Curve

Choose one or more source files on RD Curve tab, press right mouse button and choose Remove:

Remove Source File(s) from RD Curve

Remove Source File(s) from RD Curve

All the selected source files will be removed, even if they are referring to different RD Curves.

Set RD Curve as Anchor

An anchor RD Curve is used to calculate BD Rate. BD Rate will be calculated for all other RD Curves and relatively to the one marked as an anchor RD Curve.

To mark an RD Curve as anchor, select that RD Curve and press right mouse button:

Mark RD Curve as Anchor

Mark RD Curve as Anchor

Once marked, its name will be changed:

RD Curve Marked as Anchor

RD Curve Marked as Anchor

Opening YUV Files

Open YUV File Dialog

Open YUV File Dialog

Y4M files are opened automatically. In case of a regular YUV file, the user will be asked to specify video parameters, such as resolution, chroma subsampling, whether it's packed or planar, and bit depth.

Choose the parameter of a file. Once a parameter is changed, the preview image updates. So, you can tune parameters until the image looks correct to you.

NOTE Once the user opened a specific file via the dialog, consequent openings of the same file will use the previous parameters as the default parameters.

Crop

For YUV/Y4M files you have the option to crop the image. This is can be done in Open YUV File Dialog: Open YUV File Dialog There are 4 parameters to setup crop:

  • left: position in pixels where to start crop horizontally
  • top: position in pixels where to start crop vertically
  • width: width of the cropped area in pixels
  • height: height of the cropped area in pixels

Once any of these parameters changed, the cropped area visualisation will be updated on the left side of the dialog.

NOTE cropping parameters will be automatically changed to the neares multiple of 4 or 8 depending on the Plane Order. You may find the details under information sign on the dialog.

Playback

Playback can be started by clicking the appropriate Play button, by choosing menu item Playback > Play/Pause or by using the hotkey Space. To stop playback, press the Pause button, choose the menu item Playback > Play/Pause or use hotkey Space.

Framerate used for playback can be set to one of the values placed under Playback > Framerate menu. Default value is 25 fps.

NOTE Depending on hardware resources, video framerate of playback can be less than targeted in the menu.

YUV Values

YUV values of the opened file(s) (left, right or reference) become available starting at zoom ratio 32. These values will look as follows:

YUV Values

YUV Values

If the current visible component is chosen for displaying one plane (Y, U, or V), the values for that specific component will be shown. For example:

Y Values

Y Values

Use dec and hex switch to show values in decimal or hexadecimal formats, respectively.

Heat Map: Difference of Left(Right) and Reference

This mode allows you to visualize in the form of heat map the difference of a specific left file's frame with the appropriate frame of the reference file as well as the difference of a specific right file's frame with the appropriate frame of the reference file.

Please choose L|R / Ref Diff (or View > Show Left/Right and Reference Difference option from the main menu, or press F3 on your keyboard) to show the heat map. It looks as follows:

Heat Map View

Heat Map View

The color represents the difference between a specific pixel of the left (right) frame and specific pixel of the reference frame, from 0 to the maximum difference:

Heat Map Colors Meaning

Heat Map Colors Meaning

For example, white color means there is no difference.

Once zoomed in to zoom ratio 32 and above, the values of the difference will be shown:

Heat Map YUV Difference Values

Heat Map YUV Difference Values

You may also choose a specific plane (Y, U, or V) to show the difference of a specific plane.

Zoom

Video can be zoomed in as well as zoomed out. Following are the options:

  • choose menu items View > Zoom In and View > Zoom Out to zoom in and zoom out, respectively
  • use keyboard shortcuts

Specific key combinations depend on the Operating System the application is running on. You may find the exact shortcut combination in under View menu

  • press Ctrl key and left mouse button to start selection of the area to zoom to specific area. Video will be zoomed in once mouse button is released

There are some additional convenient functions:

  • change the size to the actual video resolution by using View > Actual Size
  • fit the video to the window's size by choosing View > Fit to Window in the menu

Video Quality Metrics

VQ Probe allows the user to calculate video quality metrics. The list of quality metrics is provided in section Supported Video Metrics.

The functionality of video quality metrics calculation is available on Metrics View.

Once at least one target file is opened, and the reference file is opened, Probe is ready to calculate video quality metrics. The user can do that in one of the following ways:

  • by clicking Metrics > Run in the main menu
  • by clicking Run in Metrics View
  • by using hotkeys: Cmd + M, Cmd + R (MacOS) or Ctrl + M, Ctrl + R (Windows, Linux)

Next, metrics calculation starts for every available metric: PSNR, SSIM and VMAF. Values appear immediately:

VMAF Calculated Values

VMAF Calculated Values

Run button is disabled if there is no reference file opened.

Run button is replaced by Stop during the metrics calculation process.

The currently visible metric can be changed via the Metric combo-box.

The user can show exact numbers for specific frame by moving the cursor over a graph. A tooltip will show the frame number and metric values for that frame.

Metrics View: Navigation

Metrics View: Navigation

You can navigate by clicking on a specific frame in Metrics View. After that, the actual image(s) in Playback View will be changed according to the selected frame.

Similar, once the current frame is changed in Playback View, the current frame selection in Metrics View will be changed.

Zoom

The following hotkeys can be used to zoom in or out on graphs in Metrics View:

  • left mouse click will start custom rectangle selection; zooming is applied once the button is released
  • right mouse click will zoom the graph back to default
  • Shift + mouse scroll will zoom the graph by the both X and Y Axes
  • Cmd + mouse scroll (MacOS) or Ctrl + mouse scroll (Windows, Linux) will zoom the graph by the X Axis

Quality Difference

L/R Quality Diff tab allows the user to get the difference between the metrics of the right file and the metrics of the left file. In other words, it shows by how much the right file is better than the left file:

VMAF Quality Difference

VMAF Quality Difference

The values on the graph will be negative if the right file is of a lower quality than the left file. For example:

VMAF Negative Quality Difference

VMAF Negative Quality Difference

RD Curves

RD Curves tab allows you to plot RD Curves as well as calculate BD Rates. Please make sure you setup RD Curve list (please refer to Project section).

Once all metrics are finished, RD Curves will appear on appropriate tab:

RD Curves tab

RD Curves tab

The tab contains the following information: - BD Rates: the list of BD Rates. First RD Curve assumed as the anchor. BD Rates for other RD Curves are calculated in relation to the anchor RD Curve - File List: the list of RD Curves and files they consist of - RD Curve plot: a plot that consists of points, each of them is an average appropriate metric value at specific average file's bitrate

Changing Metric combo-box will change the current RD Curves plot to a plot for selected metric.

Known Limitations

  • While using 4K+ resolution, the "+" button of Open File(s) Dialog is too small.

Third Party Libraries

VQ Probe uses certain 3rd party libraries, as listed below. You may find the full text of each license in the following folder: Windows/Linux – licenses folder under your application's folder; MacOS – vq_probe.app/Contents/SharedSupport/licenses.

Qt

Qt is licensed under the GNU Lesser General Public License (LGPL) version 3.

Project homepage https://www.qt.io/, upstream version: 5.13.1.

Copyright (C) 2019 The Qt Company Ltd and other contributors

You may find the full text of the license in Qt_license file of your binary package.

Qwt

Qwt is licensed under Qwt License, Version 1.0.

Project homepage https://qwt.sourceforge.io/, upstream version: 6.1.4.

Copyright (c) 2019 Uwe Rathmann

You may find the full text of the license in qwt_license file of your binary package.

FFmpeg

FFmpeg is licensed under GNU Lesser General Public License (LGPL) version 2.1.

Project homepage https://ffmpeg.org, upstream version: 4.2.2.

Copyright (c) 2000-2019 the FFmpeg developers

You may find the full text of the license in ffmpeg_license file of your binary package.

Libvmaf

Libvmaf is licensed under BSD+Patent license.

Project homepage https://github.com/Netflix/vmaf, upstream version: 1.3.16.

Copyright (c) 2020 Netflix, Inc.

You may find the full text of the license in libvmaf_license file of your binary package.

VVCSoftware_VTM

VVCSoftware_VTM is licensed under BSD License.

Project homepage https://vcgit.hhi.fraunhofer.de/jvet/VVCSoftware_VTM/-/tree/VTM-9.0, upstream version: 9.0.

Copyright (c) 2010-2020, ITU/ISO/IEC

You may find the full text of the license in libvvc_license file of your binary package.

dav1d

dav1d is licensed under BSD 2-clause "Simplified" License.

Project homepage https://code.videolan.org/videolan/dav1d, upstream version: 0.7.1.

Copyright © 2018-2019, VideoLAN and dav1d authors

You may find the full text of the license in dav1d_license file of your binary package.