Argus NvRaw Tool

Argus NvRaw (nvargus_nvraw) is a Bayer raw command line interface (CLI) capture tool for the NVIDIA® Jetson™ platform which runs on Jetson Linux (L4T). It saves a captured image and its metadata in a file using nvraw format, described below. It can also save a captured image in JPEG, YUV, and headerless raw formats. It accepts user-specified manual exposure control parameters.
You can use Argus NvRaw to initiate a capture after auto white balance (AWB )and auto exposure (AE) convergence have been achieved by providing a large number of frames to be skipped.
Nvraw format, also called Bayer raw format, nvraw is a NVIDIA proprietary file format for saving Bayer Raw image captures and associated metadata. An nvraw file has a file extension of .nvraw. If the image contains multiple exposures, as from HDR image captures, an nvraw file can save the individual exposures as well.
Nvraw files are used mainly for tuning and improving image quality during camera driver development. Hence, Argus NvRaw is targeted to camera driver developers who have engaged a scaling partner to assist with tuning a driver for optimum image quality. By capturing nvraw images, you can provide data that your partner can use to tune the camera driver.

Prerequisites for Use

This section describes hardware, operating system, and other software prerequisites for using Argus NvRaw.
nvargus_nvraw is an executable binary file that is part of the flashed image on a Jetson device. The executable may be found in the system path after flashing. No additional installation is needed.

Hardware and Operating System Prerequisites

You need the following hardware and operating system to perform camera software development:
An NVIDIA® Jetson™ Xavier™ NX, Jetson Nano™, Jetson AGX Xavier™ series, or Jetson TX2 series device
Jetson Linux installed on the Jetson device

Software Package Prerequisites

You need the following software packages on the Jetson device:
NVIDIA Libargus Camera API (a part of the NVIDIA JetPack SDK). For more information about JetPack SDK, see the page Introduction to JetPack in NVIDIA JetPack SDK.
A functional camera sensor driver

Camera Sensor Modes

Camera sensors can have more than one mode. Each mode has a resolution, frame rate, CSI and dynamic bit depths, and mode type. Each mode is identified by an unsigned; integer. The first mode is mode 0, and the last is mode m−1, where m is the number of modes.
Different camera sensors support modes the fall into either or both of two mode types:
SDR (Standard Dynamic Range), also known as Bayer mode type. This mode type is supported by almost every camera sensor. Image pixels are not compressed, and no conversion is needed for rendering the image on a viewer.
HDR (High Dynamic Range), also known WDR (Wide Dynamic Range). This mode type is not as widely supported as SDR. In this mode type the camera captures more than one exposure per image. The resulting output image may be compressed, in which case a view needs information about the compression to recover the original pixel information.
HDR mode has sub-modes, one of which is WDR PWL (Wide Dynamic Range Piecewise Linear). In this sub-mode, images are compressed based on a set of x and y coordinates, reducing the reduced number of bits needed to hold pixel data. The same set of coordinates are used to decompress the pixels and recover the original data.
When you run the nvargus_nvraw command, you select a mode with a command line option. (See the section Usage, below.) If you select an HDR mode, you may have to enter additional mode-specific information on the command line.

nvargus_nvraw Command

This section describes the usage of the nvargus_nvraw command, and shows several examples of its use.

Usage

The usage of nvargus_nvraw is:
nvargus_nvraw [<options>]
Where <options> is an optional set of one or more command line options. The table below describes options for this command.
Some options have optional or required values. A option’s value is a number or string that is placed between the option and the following option (if any). A string value may be enclosed in quotation marks, and must be enclosed in quotation marks if it contains whitespace characters.
Option
Description
Default value
--c <sensor_id>
Specifies the zero-based ID of the sensor to be used.
0
--mode <number>
Specifies the zero-based mode number of the sensor.
0
--file <file>
Specifies the complete pathname for the NVRAW output file.
--exp<n> "<time>,<gain>"
Specifies an exposure set containing manual values for exposure time and sensor gain. The option’s value is described in the section To specify an exposure set (the --exp<n> option), below.
Current value in the sensor driver or register. This value is not predictable.
--verbosity <level>
Specifies the verbosity of printed output. Possible values, from least to most verbose, are error, warning, info, and debug.
Verbosity levels are cumulative. For example, the printed output for info includes all of the printed output for error and warning.
error
--pwlinfo <pwl_file>
Specifies the pathname a file that defines a set of PWL (piecewise linear) decompanding points to be stored in the NVRAW image metadata after capture. Used with PWL captures if the sensor driver does not provide PWL decompanding points to nvargus_nvraw.
Each point in the PWL file is defined in the form:
linearization.compandingLut[n].x = <x_value>;
linearization.compandingLut[n].y = <y_value>;
Where <n> is the index of a decompanding point (0 to 8), <x_value> is the compressed value at that point, and <y_value> is the corresponding decompressed value.
--override
Disabled
--ts
Enables time stamp printing during logging.
--format <list>
Specifies one or more file formats in which to save output. See To specify output format (the --format option), below.
nvraw
--skipframes <count>
Number of frames to be skipped before the final frame that gets saved on the storage.
Example:
--skipframes 40
90
--help
Prints a runtime help menu.
This prints all the command line options specified in this table.
--lps
Prints a list of available sensors and their supported resolutions.
--sensorinfo
Prints information about the selected sensor and mode.

Examples: Basic Operations

This section presents several simple examples of the nvargus_nvraw command. Later sections present additional examples for various types of use.
To specify an exposure set (the exp<n> option)
The --exp<n> option specifies an exposure set containing manual values for exposure time and sensor gain.
A high dynamic range (HDR) sensor can capture several exposures for each image, numbered from 0 to N−1, where N is the number of exposures captured. Thus the ‑‑exp0 option specifies the exposure set to be used for exposure 0, ‑‑exp1 specifies the exposure set for exposure 1, and so on. The section Display further information for a specific sensor explains how to determine the number of exposures a particular HDR sensor can capture.
The ‑‑exp<n> option has the format:
--exp<n> "<time>,<gain>"
Where:
<n> is the zero-based number of an HDR exposure.
The value of <n> currently may not be greater than 0. Exposure time and sensor gain for exposure 1 onwards are determined by the HDR ratio internally in nvargus_nvraw.
<time> is the exposure time of exposure n, in seconds.
<gain> is the sensor gain for exposure n, e.g. 1.0 for no gain, 2.0 for 2x gain, etc.
Spaces between <time> and <gain> are allowed but not required.
If any value is omitted, the tool uses the value in the sensor driver or register. This value is not predictable. If <gain> is omitted, the trailing comma may be omitted.
To specify error override (the ‑‑override option)
The ‑‑override option overrides certain errors. If an overridden error occurs, Argus NvRaw continues to run as if there were no error.
Currently this option overrides one error:
If the frame is compressed, the decompression information must be provided by the driver or a user-supplied file specified by the --pwlinfo command line parameter. If decompression information is not provided by either source, that is an error.
The ‑‑override option is useful while you are bringing up the driver if you must capture an image, then gather some data to define PWL decompanding points to provide to the driver. This option ensures that the capture can proceed even though PWL decompanding points are not yet available.
To specify output format (the ‑‑format option)
The ‑‑format option specifies a comma-separated list of one or more file formats in which to save output. The file formats must be chosen from this table:
File format (‑‑format option)
Type of file
File extension
NVRAW
nvraw_v3 format file
.nvraw
YUV
YUV 8-bit 4:2:0 format file
.yuv
JPG
JPEG format file
.jpg
RAW
Headerless raw format file and its corresponding metadata file
.raw and .txt
For example, this option specifies output files in nvraw_v3, JPG, and YUV 8‑bit 4:2:0 formats:
--format "nvraw, jpg, yuv"
In the following example, this option specifies output files in nvraw_v3 and headerless Bayer raw formats:
--format "nvraw, raw"
Each output file has the basename specified by the --file option. If the ‑‑format option is present and its value is jpg or yuv, the output file has the extension jpg or yuv; if its value is nvraw, the output file is assigned the same extension.

Examples: Displaying Sensor Information

The first example lists the configurations available for a specified sensor. The second one displays detailed information about a specified configuration.
To list available sensor configurations
Enter this command:
nvargus_nvraw --lps
For an ov5693 sensor, the command displays this output:
nvargus_nvraw version 1.0.0
Number of supported sensor entries 3
Entry Source Mode Uniquename Resolution FR BitDepth SensorMode
Index CSI Dyn
0 0 0 2592x1944 30 10 10 Bayer
1 0 1 2592x1458 30 10 10 Bayer
2 0 2 1280x 720 120 10 10 Bayer
All of this sensor’s modes are the SDR (Bayer) mode type, each with a different resolution and or frame rate.
For an IMX185 sensor, it displays this:
nvargus_nvraw version 1.0.0
Number of supported sensor entries 5
Entry Source Mode Uniquename Resolution FR BitDepth SensorMode
Index CSI Dyn
0 0 0 1920x1080 30 12 12 Bayer
1 0 1 1920x1080 30 10 10 Bayer
2 0 2 1920x1080 60 12 12 Bayer
3 0 3 1920x1080 60 10 10 Bayer
4 0 4 1920x1080 30 12 16 Bayer_WDR_PWL
Modes 0 through 3 are regular SDR (or Bayer) mode type; mode 4 is a WDR PWL mode.
To display further information for a specific sensor
Enter this command:
$ nvargus_nvraw --c <sensor_id> --mode <mode_number> --sensorinfo
This is an example of an actual command for SDR mode:
$ nvargus_nvraw --c 0 --mode 0 --sensorinfo
The command displays output like this:
nvargus_nvraw version 1.0.0
Number of sensors 1, Number of modes for selected sensor 5
 
Selected sensor: imx185_bottom_liimx185 ID 0 Mode 0
Number of exposures 1
Index Exposure time Range Sensor Gain Range
0 0.000030 - 0.660000 1.00 - 251.19
This is an example of an actual command, for WDR PWL mode.
$ nvargus_nvraw --c 0 --mode 4 --sensorinfo
The command displays output like this:
nvargus_nvraw version 1.0.0
Number of sensors 1, Number of modes for selected sensor 5
 
Selected sensor: imx185_bottom_liimx185 ID 0 Mode 4
Number of exposures 1
Index Exposure time Range Sensor Gain Range
0 0.002433 - 0.660000 1.000000 - 3.981071
1 0.000152 - 0.041250 1.000000 - 3.981071
 
HDR Ratio: 16.00
Note: The ratio between the Exposure Time in Exposure 0 and
the Exposure Time in Exposure 1 will be equal to HDR Ratio

Examples: Capturing Images

The first example captures an SDR image. The second captures a WDR PWL image.
To capture a standard dynamic range (SDR) NVRAW image
An SDR image contains a single exposure. It is designated “exposure 0,” so you refer to its properties with the option ‑‑exp0. You can optionally specify manual exposure parameters during the capture.
Enter this command:
$ nvargus_nvraw --c <sensor_id> --mode <mode_number> \
--exp0 "<time>,<gain>" --file <filename>
Where:
<sensor_id> is the zero-based ID of the sensor to be used
<mode_number> is the zero-based mode number of the mode to be used
<n> is the number of the image to capture
<time> is the capture’s exposure time in seconds
<gain> is the gain to apply to the capture
The command specifies a single --exp<n> option which references one of the exposures provided by the sensor. To display a list of exposures available for a sensor, use the --sensorinfo option shown above.
If you do not specify --exp<n>, the sensor driver’s current values are used.
This is an example of an actual command:
$ nvargus_nvraw --c 0 --mode 0 --file /home/ubuntu/sample.nvraw \
--exp0 "0.000034, 5"
The command displays output like this:
argus_nvraw version 1.0.0
+-------------- Exposure info results -------------+
| Exposure | Exposure Time | Sensor Gain |
| 0 | 0.000034 | 5.00 |
+--------------------------------------------------+
writeToFile: file /home/ubuntu/sample.nvraw is successfully created
To capture a WDR PWL NVRAW image
Without specifying manual exposure information:
Enter a command like the following one, modifying it as appropriate to suit your use case. Use the mode number that specifies WDR PWL capability for your camera sensor.
$ nvargus_nvraw --c 0 --mode 4 --file /home/ubuntu/sample.nvraw
The command displays output similar to that shown below. This example shows that the camera is capturing two exposures per image, with exposure time and sensor gain taken from the sensor driver’s current values.
argus_nvraw version 1.0.0
+------ Exposure info results -----------+
| Exposure | Exposure Time | Sensor Gain |
| 0 | 0.033333 | 3.98107 |
| 1 | 0.002083 | 3.98107 |
+----------------------------------------+
HDR Ratio: 16.00
Note: The ratio between the Exposure Time in Exposure 0 and
the Exposure Time in Exposure 1 is equal to HDR Ratio
writeToFile: file /home/ubuntu/sample.nvraw is successfully created
Specifying manual exposure information:
Even though HDR mode supports 2 exposures, the user can provide the manual exposure information of only the first exposure (exp0). Manual exposure information of the second exposure (exp1) is computed from the first exposure using the HDR ratio.
This is an example of an actual command:
$ nvargus_nvraw --c 0 --mode 4 --file /home/ubuntu/sample.nvraw \
--exp0 "0.05671, 2.0"
The command displays output like this. Exposure time of the first exposure reflects user specified value and that of second exposure is a 1/16th of the first exposure.
argus_nvraw version 1.0.0
+------ Exposure info results -----------+
| Exposure | Exposure Time | Sensor Gain |
| 0 | 0.056710 | 2.00000 |
| 1 | 0.003544 | 2.00000 |
+----------------------------------------+
HDR Ratio: 16.00
Note: The ratio between the Exposure Time in Exposure 0 and
the Exposure Time in Exposure 1 is equal to HDR Ratio
writeToFile: file /home/ubuntu/sample.nvraw is successfully created
PWL Decompanding Points
The nvargus_nvraw utility needs a PWL (piecewise linear) decompanding curve to re-linearize PWL RAW images captured with a PWL sensor.
The utility looks first for a user-provided PWL information file that contains a set of PWL decompanding points that define the curve. If no file is provided, it tries to get PWL decompanding points from the sensor driver. If the sensor driver does not provide PWL decompanding points either, the utility prints the error “Missing PWL Knee Points” and terminates.
You can provide PWL decompanding points by storing them in a file, as described in the following sections.
PWL Information File
You can define a PWL companding curve in a PWL information file. You specify the file to nvm_nvraw with the ‑‑pwlinfo option:
$ nvargus_nvraw --c <sensor_id> --mode <mode_number> \
--file <output_file> --pwlinfo <pwl_file>
The file can define up to nine PWL decompanding points. Each point is defined by a pair of settings:
linearization.compandingLut[n].x = <xn>;
linearization.compandingLut[n].y = <yn>;
Where:
<n> is the index of a decompanding point, in the range 0 to 8.
<xn> is the compressed value of point <n>.
<yn> is the decompressed value of point <n>.
Example or a PWL Information File
This is the contents of a PWL information file that defines two decompanding points:
linearization.compandingLut[0].x = 10.0;
linearization.compandingLut[0].y = 23645.0;
linearization.compandingLut[1].x = 400.0;
linearization.compandingLut[1].y = 53845.0;
Example of a Command that Uses a PWL Information File
This is an nvargus_raw command that uses a decompanding file named sensor_pwlinfo.txt:
$ nvargus_nvraw --c 0 --mode 4 \
--file /home/ubuntu/sample.nvraw --pwlinfo pwlinfo.txt
The command’s output looks like this:
nvargus_nvraw version 1.0.0
capture: Total captured frame count 90
capture: Successfully read 4 PWL Knee points from user provided file /tmp/pwlinfo.txt
+------ Exposure info results -----------+
| Exposure | Exposure Time | Sensor Gain |
| 0 | 0.033333 | 3.98107 |
| 1 | 0.002083 | 3.98107 |
+----------------------------------------+
HDR Ratio: 16.00
Note: The ratio between the Exposure Time in Exposure 0 and
the Exposure Time in Exposure 1 is equal to HDR Ratio
writeToFile: file /home/ubuntu/sample.nvraw is successfully created
Using the --override Option
The command line option ‑‑override tells the nvargus_nvraw utility to override certain ordinarily terminal errors and continue running.
Currently ‑‑override controls only one error, “Missing PWL decompanding points,” which means that PWL decompanding points were not available from either a PWL information file or the camera sensor. For information about how a PWL information file is created and used, see the section Examples: Displaying Sensor Information.
To capture a JPEG and YUV image
A JPEG or YUV file’s name comprises the basename from the ‑‑file option and the extension .jpg (for a JPEG) file or .yuv (for a YUV file). In case of a .yuv file, the resolution of the camera sensor is also incorporated into the basename.
Enter this command:
$ nvargus_nvraw --c <sensor_id> --mode <mode_number> \
--file <filename> --format “jpg, yuv”
This is an example of an actual command:
$ nvargus_nvraw --c 0 --mode 0 --file /home/ubuntu/sample.jpg \
‑–format "yuv, jpg"
It displays output like this:
argus_nvraw version 1.0.0
writeToFile_Jpeg: file /home/ubuntu/sample.jpg is successfully created
writeToFile_Yuv: file /home/ubuntu/sample_2592x1944.yuv is successfully created
To capture a headerless Bayer raw image
A headerless Bayer raw image file contains only raw pixels. It is accompanied by a text file that contains the metadata associated with the image.
This is an example of an actual command for capturing a headerless Bayer raw image:
$ nvargus_nvraw --c 0 --mode 0 --file /home/ubuntu/sample \
-–format "raw"
It displays output like this:
$ nvargus_nvraw --c 0 --mode 0 --file /home/ubuntu/sample --format "raw"
nvargus_nvraw version 1.0.0
capture: Total captured frame count 90
+------ Exposure info results -----------+
| Exposure | Exposure Time | Sensor Gain |
| 0 | 0.033333 | 3.98107 |
+----------------------------------------+
writeToFile_HeaderlessRaw: files /home/ubuntu/sample.raw and /home/ubuntu/sample.txt are successfully created

Examples: Other Operations

This section contains examples that do not belong in any other group.
To specify a number of frames to skip
You can specify a number of frames to skip before the frame to save to the storage file by using the –skipframes option.
Enter a command like this:
$ nvargus_nvraw --c <sensor_id> --mode <mode_number> \
--file <filename> --skipframes <count>
Where <count> is the number of frames to skip.
This is an example of an actual command which skips the first 20 frames and captures the image in the 21st:
$ nvargus_nvraw --c 0 --mode 0 --file /home/ubuntu/sample.nvraw \
‑‑skipframes 20
It displays output like this:
argus_nvraw version 1.0.0
capture: Total captured frame count 21
+-------------- Exposure info results -------------+
| Exposure | Exposure Time | Sensor Gain |
| 0 | 0.000034 | 5.00 |
+--------------------------------------------------+
writeToFile: file /home/ubuntu/sample.nvraw is successfully created

Limitations

Green JPG and YUV Images
If you use the --format option to generate JPEG or YUV format files while using an Omnivision OV5693 sensor, the generated images have a green cast.