update 3c9d6ae

antmicro · Sep 24, 2024 · ecf0556 · ecf0556
commit ecf0556
Show file tree

Hide file tree

Showing 244 changed files with 4,690 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 14baac6af4f42c029005d0a6ec6cc62e
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.nojekyll b/.nojekyll
diff --git a/_images/add-skip.png b/_images/add-skip.png
diff --git a/_images/bayer-pattern-examples.png b/_images/bayer-pattern-examples.png
diff --git a/_images/channel-masks.png b/_images/channel-masks.png
diff --git a/_images/color-format.png b/_images/color-format.png
diff --git a/_images/color_channels_01.png b/_images/color_channels_01.png
diff --git a/_images/color_channels_02.png b/_images/color_channels_02.png
diff --git a/_images/color_channels_03.png b/_images/color_channels_03.png
diff --git a/_images/color_channels_04.png b/_images/color_channels_04.png
diff --git a/_images/empty-gui.png b/_images/empty-gui.png
diff --git a/_images/endiannes_01.png b/_images/endiannes_01.png
diff --git a/_images/endiannes_02.png b/_images/endiannes_02.png
diff --git a/_images/endianness.png b/_images/endianness.png
diff --git a/_images/hexdump.png b/_images/hexdump.png
diff --git a/_images/hexdump_01.png b/_images/hexdump_01.png
diff --git a/_images/hexdump_02.png b/_images/hexdump_02.png
diff --git a/_images/import-file-menu.png b/_images/import-file-menu.png
diff --git a/_images/mmb-click.png b/_images/mmb-click.png
diff --git a/_images/rawview_01.png b/_images/rawview_01.png
diff --git a/_images/rawview_02.png b/_images/rawview_02.png
diff --git a/_images/rawview_03.png b/_images/rawview_03.png
diff --git a/_images/remove_byte_01.png b/_images/remove_byte_01.png
diff --git a/_images/remove_byte_02.png b/_images/remove_byte_02.png
diff --git a/_images/resolution.png b/_images/resolution.png
diff --git a/_images/reverse.png b/_images/reverse.png
diff --git a/_images/reverse_bytes_01.png b/_images/reverse_bytes_01.png
diff --git a/_images/reverse_bytes_02.png b/_images/reverse_bytes_02.png
diff --git a/_images/reverse_bytes_03.png b/_images/reverse_bytes_03.png
diff --git a/_images/theme-change.png b/_images/theme-change.png
diff --git a/_sources/formats.md.txt b/_sources/formats.md.txt
@@ -0,0 +1,160 @@
+# Supported color formats
+
+## RGB
+
+The RGB color model uses 3 colors: **R**ed, **G**reen, and **B**lue to construct all the colors.
+Each parameter in this format represents the intensity of the colors, expressed on a scale dependent on its bit depth.
+
+```{list-table} RGB pixel formats
+:header-rows: 1
+:widths: 1 2
+
+* - Name
+  - VL42 Identifier
+* - RGB332
+  - V4L2_PIX_FMT_RGB332
+* - ARGB444
+  - V4L2_PIX_FMT_ARGB444
+* - RGBA444
+  - V4L2_PIX_FMT_RGBA444
+* - ABGR444
+  - V4L2_PIX_FMT_ABGR444
+* - BGRA444
+  - V4L2_PIX_FMT_BGRA444
+* - ARGB555
+  - V4L2_PIX_FMT_ARGB555
+* - RGBA555
+  - V4L2_PIX_FMT_RGBA555
+* - ABGR555
+  - V4L2_PIX_FMT_ABGR555
+* - BGRA555
+  - V4L2_PIX_FMT_BGRA555
+* - RGB565
+  - V4L2_PIX_FMT_RGB565
+* - BGR24
+  - V4L2_PIX_FMT_BGR24
+* - RGB24
+  - V4L2_PIX_FMT_RGB24 
+* - ABGR32
+  - V4L2_PIX_FMT_ABGR32
+* - BGRA32
+  - V4L2_PIX_FMT_BGRA32
+* - RGBA32
+  - V4L2_PIX_FMT_RGBA32
+* - ARGB32
+  - V4L2_PIX_FMT_ARGB32
+```
+
+## YUV
+
+The YUV color model consists of 3 elements:
+- Y is the brightness or luminescence information
+- U is the red color (chroma) difference value
+- V is the blue color (chroma) difference value
+
+Both color difference values can be calculated by subtracting the Y value from the RGB color space's blue component (for U) or red component (for V).
+Raviewer uses the following formulas to calculate each of the YUV values:
+
+**Y = R *  .299000 + G *  .587000 + B *  .114000**
+
+**U = R * -.168736 + G * -.331264 + B *  .500000 + 128**
+
+**V = R *  .500000 + G * -.418688 + B * -.081312 + 128**
+
+```{list-table} YUV pixel formats
+:header-rows: 1
+:widths: 1 3 2
+
+* - Name
+  - VL42 Identifier
+  - Pixel plane
+* - UYVY
+  - V4L2_PIX_FMT_UYVY
+  - PACKED
+* - YUYV
+  - V4L2_PIX_FMT_YUYV
+  - PACKED
+* - VYUY
+  - V4L2_PIX_FMT_VYUY
+  - PACKED
+* - YVYU
+  - V4L2_PIX_FMT_YVYU
+  - PACKED
+* - NV12
+  - V4L2_PIX_FMT_NV12
+  - SEMI-PLANAR
+* - NV21
+  - V4L2_PIX_FMT_NV21
+  - SEMI-PLANAR 
+* - I420
+  - V4L2_PIX_FMT_YUV420
+  - PLANAR
+* - YV12
+  - V4L2_PIX_FMT_YVU420
+  - PLANAR
+* - I422
+  - V4L2_PIX_FMT_YUV422P
+  - PLANAR
+```
+
+## Bayer RGB
+
+Bayer format is a raw video format produced by image sensors that include a Bayer filter.
+A Bayer filter is a color filter array in which RGB color filters are arranged on a grid of square photosensors.
+A Bayer filter uses two green filter elements for each red and blue filter element.
+The filter array can be arranged in 4 distinct patterns.
+Their names are derived from the order of the filters in a single 2x2 pixel square:
+
+![Bayer pattern examples](./img/bayer-pattern-examples.png)
+
+Bayer format is a popular raw image format used in many modern color image sensors.
+
+```{list-table} Bayer RGB pixel formats
+:header-rows: 1
+:widths: 1 2
+
+* - Name
+  - VL42 Identifier
+* - RGGB
+  - V4L2_PIX_FMT_SRGGB8
+* - RG10
+  - V4L2_PIX_FMT_SRGGB10
+* - RG12
+  - V4L2_PIX_FMT_SRGGB12
+* - RG16
+  - V4L2_PIX_FMT_SRGGB16
+```
+
+## Grayscale
+
+In the grayscale color format, each pixel only conveys intensity information.
+This information can be expressed on a scale dependent on its bit depth, where the minimum value represents white, and the maximum value represents black.
+
+```{list-table} Grayscale pixel formats
+:header-rows: 1
+:widths: 1 2
+
+* - Name
+  - VL42 Identifier
+* - GRAY
+  - V4L2_PIX_FMT_GRAY
+* - GRAY10
+  - V4L2_PIX_FMT_Y10
+* - GRAY12
+  - V4L2_PIX_FMT_Y12
+```
+
+(adding-new-color-formats)=
+
+## Adding new color formats
+
+Currently, two classes can be used to describe color formats: `ColorFormat` and `SubsampledColorFormat` (found in `app/image/color_format.py`).
+To create a new color format:
+
+1. In `color_format.py`, add a new instance of one of the color format classes with the appropriate fields filled in under the AVAILABLE_FORMATS list.
+2. Add parsing and displaying functions to the `AbstractParser` in `common.py`.You can also use other parsers from the folder or implement a new one.
+3. The utility provides a proper parser by checking color format parameters (mainly `PixelFormat`) so make sure that your new color format has a valid translation of parameters to one of the parsers (you can find this functionality in `app/parser/factory.py`).
+
+```{note}
+Keep in mind that if you choose to implement a new parser, remember that `parse()` should return a one-dimensional `ndarray` with values read from the binary file, while `display()` should return an RGB-formatted 3-dimensional `ndarray` consisting of original color format values converted to RGB24.
+```
diff --git a/_sources/index.md.txt b/_sources/index.md.txt
@@ -0,0 +1,11 @@
+# {{project}}
+
+```{toctree}
+:maxdepth: 2
+
+introduction
+installation
+quickstart
+usage
+formats
+```
diff --git a/_sources/installation.md.txt b/_sources/installation.md.txt
@@ -0,0 +1,33 @@
+# Installation
+
+## Requirements
+
+For Raviewer to work, you need to have [Python 3.9](https://www.python.org/downloads/) or higher installed on your system.
+
+You also need the following Python libraries:
+
+* [numpy](https://numpy.org/doc/stable/)
+* [opencv-python](https://docs.opencv.org/4.x/index.html)
+* [dearpygui](https://dearpygui.readthedocs.io/en/latest/) == 1.1.1
+* [terminaltables](https://robpol86.github.io/terminaltables/)
+* [pytest](https://docs.pytest.org/en/7.1.x/)
+
+```{note}
+Raviewer will automatically download any missing libraries.
+```
+
+## Installation
+
+### Arch Linux
+
+```bash
+sudo pacman -Sy python-pip git
+pip install git+https://github.com/antmicro/raviewer.git
+```
+
+### Debian
+
+```bash
+sudo apt-get install python3-pip git python3-pil.imagetk
+pip install git+https://github.com/antmicro/raviewer.git
+```
diff --git a/_sources/introduction.md.txt b/_sources/introduction.md.txt
@@ -0,0 +1,22 @@
+# What is Raviewer?
+
+Raviewer is Antmicro's open-source image analysis tool, created to streamline the process of video debugging.
+It handles arbitrary binary data and visualizes it using selected parameters so that you can quickly and efficiently analyze any image you want.
+
+When your project involves operations like building a camera system, capturing the data with an FPGA board, or implementing camera drivers for new cameras or platforms, the sheer number of moving parts you are juggling before you get usable video makes debugging a difficult process.
+This is where Raviewer may come in handy and help you accelerate and simplify your product development.
+
+It helped us immensely with some of our projects, like when we built the FPGA debayering core, which included a demosaicing system that changes raw data from CCD or CMOS sensors.
+Initially, the project was created for our internal needs, but we decided to release it to help reduce frustration related to working with complex engineering problems.
+
+## Core features
+
+Raviewer supports many popular color formats like [RGB, YUV, BAYER, or GRAYSCALE](formats.md) and lets you add new color formats.
+
+- [Checkboxes controlling the displayed channels](controlling-color-channels)
+- [On-click displaying raw data making up a pixel as decoded RGB and YUV](color-picker)
+- [Conversion of the whole or selected part of an image to more complex formats (JPEG, PNG) or raw data](exporting-data)
+- [An option to append or remove n bytes from the beginning of the image series](adding-skipping-bytes)
+- [Hexadecimal preview mode](hexadecimal-preview-mode)
+- [Terminal functionality](command-line-arguments)
+- [Theme manager to adjust font and theme preferences](theme-manager)
diff --git a/_sources/quickstart.md.txt b/_sources/quickstart.md.txt
@@ -0,0 +1,132 @@
+# Quick start
+
+After installing Raviewer, you can start an empty GUI (without any data loaded) using:
+
+```
+raviewer
+```
+
+## GUI
+
+Raviewer's GUI is divided into three sections: the work area on the left; properties settings on the right; and the top menu:
+
+![Raviewer empty GUI](./img/empty-gui.png "Raviewer empty GUI")
+
+## Importing a file
+
+You can import a file to Raviewer by clicking **File** > **Open** from the top menu and selecting the file of your choice:
+
+![Importing a file](./img/import-file-menu.png "Import file menu")
+
+## Choosing a color format
+
+Raviewer supports a vast catalog of color formats, the full list of which you can see in the [chapter devoted to color formats](formats).
+
+Depending on the sensor you are extracting data from, RAW files can use one of many color formats.
+You need to select the color format of your file from the **Color format** dropdown menu:
+
+![Color formats](./img/color-format.png "Color formats")
+
+## Setting the resolution
+
+After choosing an appropriate color format for your file, you must adjust the resolution setting to display the preview properly.
+
+![Setting resolution](./img/resolution.png "Setting resolution")
+
+The default width in Raviever is 800px, and the height is calculated automatically, so in most cases, you can omit the latter.
+
+```{note}
+You can change the resolution in Raviewer using [command line arguments](command-line-arguments), but you must specify the path to the file you want to open for it to work properly.
+
+To open a file with a resolution of 1000x750, you would run:
+
+```bash
+raviewer -w 1000 -H 750 -f /path/to/file
+```
+
+The preview should produce a correct, good-looking image if you have set the appropriate color format, [endianness](changing-endianness), and resolution.
+
+(controlling-color-channels)=
+
+## Controlling color channels
+
+One of the common mistakes you may encounter when working with imported files is the swapped color channels.
+You can change the displayed color channels to determine if they have been properly assigned.
+
+```{note}
+In some color formats, you can also see if the alpha channel is working correctly.
+```
+
+You can easily control which color channel masks are currently being displayed by checking or unchecking boxes on the menu:
+
+![Channel masks](./img/channel-masks.png "Channel masks")
+
+Unchecking a box will cause the values of a chosen channel to be set to 0 on every pixel of the picture (except for the alpha channel, which is set to its maximum value).
+
+To see how controlling color channels may help you identify issues with your frames, have a look at this BGR24 frame:
+
+![Controlling color channels 01](./img/color_channels_01.png "Controlling color channels 01")
+
+When you select another, wrong color format (in this case, RGB24), you can see that the colors do not match the original ones:
+
+![Controlling color channels 02](./img/color_channels_02.png "Controlling color channels 02")
+
+To quickly identify the root of the problem, turn the color channels on and off.
+When only the red channel is turned on, balls that are blue in reality are shown as very bright:
+
+![Controlling color channels 04](./img/color_channels_03.png "Controlling color channels 04")
+
+When only the blue channel is turned on, in reality, orange, pink, or red balls are shown as very bright.
+
+![Controlling color channels 04](./img/color_channels_04.png "Controlling color channels 04")
+
+That means that channels R and B are swapped, and the format of our frame is not RGB24 but BGR24.
+
+(selecting-an-area)=
+
+## Selecting an area
+
+You can select an area of your picture by holding **LMB** (left mouse button) and dragging it over your screen.
+The selected area will be highlighted in green, and you can see its size in the bottom-right corner.
+
+The selected area can then be exported to PNG by selecting **File** > **Export** > **PNG** > **Selection** from the top menu, or to RAW by selecting **File** > **Export** > **RAW** > **Selection**.
+
+(zooming-in)=
+
+## Zooming in
+
+You can zoom in on an area of your picture by holding **RMB** (right mouse button) and dragging it over your screen.
+The selected area will be highlighted in yellow, and upon releasing **RMB**, Raviewer will fill the whole available workspace with the selected area.
+
+(color-picker)=
+
+## Color picker
+
+You can display raw data making up a pixel by using **LMB** (left mouse button).
+It will show you RGB and YUV values as well as the hue, saturation, and lightness of a pixel.
+You will also be able to see the information about the bytes in a component:
+
+![Color picker](./img/mmb-click.png "Color picker")
+
+Bytes in components display the channel value in the selected format.
+You can use this information to determine if the color channel values are correct.
+
+The color picker can help you spot anomalies within your files, like the alpha channel not being set to its maximum value on a picture without transparent elements.
+
+```{note}
+Color channel values in the color picker differ from those on the right side because the former have been converted to their 8-bit RGB counterparts.
+```
+
+The **Bytes in components** window can be closed using **RMB** anywhere in the window.
+
+(exporting-data)=
+
+## Exporting data
+
+Using the top menu, you can export data from Raviewer to PNG or RAW format.
+
+To export a file to PNG, use: **File** > **Export** > **PNG** > **Image**.
+
+To export a file to RAW, use: **File** > **Export** > **RAW** > **Image**.
+
+You can also [export only a snippet of your picture](selecting-an-area).