API

Initialisation

The library mostly works on the libdng_info objects. There’s only a single initialisation function

int libdng_init()

This function should be called exactly once before using any of the other functionality of the library. The purpose of this call is to register new tags into libtiff which is required before any other interaction.

DNG objects

All the state for writing is stored in the libdng_info struct. These functions work by manipulating this instance.

void libdng_new(libdng_info *dng)

Initialize the value of a libdng_info struct for further operation. This needs to be cleaned up with libdng_free.

libdng_info dng = {0};
libdng_new(&dng);

void libdng_free(libdng_info *dng)

Clean up the allocations of libdng_new

libdng_info dng = {0};
libdng_new(&dng);

// Do important stuff here

libdng_free(&dng);

int libdng_set_mode_from_name(libdng_info *dng, const char *name)

Set the pixel format for the raw data that will be written into the DNG. This configures the CFA pattern, bit depth and whitelevel metadata. The valid names are the V4L2 fourcc codes and the constant names.

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_mode_from_name(&dng, "SRGGB10P");

libdng_free(&dng);

Affected tags:

• TIFFTAG_CFAPATTERN

• TIFFTAG_WHITELEVEL

• TIFFTAG_BITSPERSAMPLE

Supported values:

fourcc	constant name	Depth
RGGB	SRGGB8	8
GRBG	SGRBG8	8
GBRG	SGBRG8	8
BGGR	SBGGR8	8
RG10	SRGGB10	10
BA10	SGRBG10	10
GB10	SGBRG10	10
BG10	SBGGR10	10
pRAA	SRGGB10P	10
pgAA	SGRBG10P	10
pGAA	SGBRG10P	10
pBAA	SBGGR10P	10
RG12	SRGGB12	12
BA12	SGRBG12	12
GB12	SGBRG12	12
BG12	SBGGR12	12
pRCC	SRGGB12P	12
pgCC	SGRBG12P	12
pGCC	SGBRG12P	12
pBCC	SBGGR12P	12
RG16	SRGGB16	16
GR16	SGRBG16	16
GB16	SGBRG16	16
BYR2	SBGGR16	16

int libdng_set_mode_from_pixfmt(libdng_info *dng, uint32_t pixfmt)

This function performs the same tasks as libdng_set_mode_from_name but uses the numeric fourcc value instead of a string. This is for passing through the format from the V4L2 subsystem directly.

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_mode_from_pixfmt(&dng, V4L2_PIX_FMT_SGBRG12P);

libdng_free(&dng);

Affected tags:

• TIFFTAG_CFAPATTERN

• TIFFTAG_WHITELEVEL

• TIFFTAG_BITSPERSAMPLE

int libdng_set_make_model(libdng_info *dng, const char *make, const char *model)

Set the make and model name for the camera or other digitizing equipment that produced the raw data. The make and model are also concatinated together to produce the “unique camera model” field that is usually shown to end-users as the camera model.

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_make_model(&dng, "Nikon", "D3300");

libdng_free(&dng);

Affected tags:

• TIFFTAG_MAKE

• TIFFTAG_MODEL

• TIFFTAG_UNIQUECAMERAMODEL

int libdng_set_software(libdng_info *dng, const char *software)

Set the name and version number of the software used to produce the image. On phones this value is usually set to the camera application.

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_software(&dng, "Megapixels 2.0");

libdng_free(&dng);

Affected tags:

• TIFFTAG_SOFTWARE

int libdng_set_datetime(libdng_info *dng, struct tm time)

Set the date and time the picture was taken or digitized. This is stored as both TIFF and EXIF metadata. Instead of specifying a tm struct the libdng_set_datetime_now function can be used to directly use the current time.

libdng_info dng = {0};
libdng_new(&dng);

time_t rawtime;
time(&rawtime);
struct tm now = *(localtime(&rawtime));

libdng_set_datetime(&dng, now);

libdng_free(&dng);

Affected tags:

• TIFFTAG_DATETIME

• EXIFTAG_DATETIMEORIGINAL

• EXIFTAG_DATETIMEDIGITIZED

int libdng_set_datetime_now(libdng_info *dng)

Set the date and time the picture was taken or digitized to the current date and time. This is a shortcut method for libdng_set_datetime.

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_datetime_now(&dng);

libdng_free(&dng);

Affected tags:

• TIFFTAG_DATETIME

• EXIFTAG_DATETIMEORIGINAL

• EXIFTAG_DATETIMEDIGITIZED

int libdng_set_orientation(libdng_info *dng, uint16_t orientation)

Set the date and time the picture was taken or digitized to the current date and time. This is a shortcut method for libdng_set_datetime.

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_datetime_now(&dng);

libdng_free(&dng);

Affected tags:

• TIFFTAG_DATETIME

• EXIFTAG_DATETIMEORIGINAL

• EXIFTAG_DATETIMEDIGITIZED

int libdng_set_neutral(libdng_info *dng, float r, float g, float b)

Set the whitebalance of the picture. The neutral whitepoint gains are the RGB gains that will be applied on top of the raw debayered data to get a properly whitebalanced picture. If the camera already uses whitebalance gain in the hardware then those should be stored in the analogbalance metadata instead and set using the libdng_set_analog_balance function.

In most cases the gain for the green channel will be 1.0f and the red and blue gains will be adjusted around that. It is important to have the right analogbalance and neutral whitebalance in the metadata to make the DNG processing software create the right color matrix from the two provided whitepoints in the metadata.

The neutral whitepoint defaults to 1.0, 1.0, 1.0.

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_neutral(&dng, 1.2f, 1.0f, 1.6f);

libdng_free(&dng);

Affected tags:

• TIFFTAG_ASSHOTNEUTRAL

int libdng_set_analog_balance(libdng_info *dng, float r, float g, float b)

Set the ADC gain used to whitebalance the sensor readings before they were digitized in the RAW file. This will be used to normalize the raw data again before using the rest of the color pipeline. Most sensors will not whitebalance the raw bayer data but some sensors in 8-bit CFA output might do this to optimize the use of the available bits a bit more.

For the whitebalance after the capture of the raw data the libdng_set_neutral function should be used to store the measured whitebalance.

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_analog_balance(&dng, 1.2f, 1.0f, 1.6f);

libdng_free(&dng);

Affected tags:

• TIFFTAG_ANALOGBALANCE

int libdng_load_calibration_file(libdng_info *dng, const char *path)

Load the calibration metadata from another TIFF file and append it to the final DNG output. This is used to load all the calibration data from a .dcp file which is a “DNG Color Profile”. These files are generated using profiling software and contain the colormatrices, calibration curves and LUTs to transform the raw data into a calibrated picture. The exact list of TIFF tags that are loaded with this command is the list below:

libdng_info dng = {0};
libdng_new(&dng);

libdng_load_calibration_file(&dng, "/tmp/d3300.dcp");

libdng_free(&dng);

Affected tags:

• TIFFTAG_COLOR_MATRIX_1

• TIFFTAG_COLOR_MATRIX_2

• TIFFTAG_FORWARD_MATRIX_1

• TIFFTAG_FORWARD_MATRIX_2

• TIFFTAG_CALIBRATION_ILLUMINANT_1

• TIFFTAG_CALIBRATION_ILLUMINANT_2

• TIFFTAG_PROFILE_TONE_CURVE

• TIFFTAG_PROFILE_HUE_SAT_MAP_DIMS

• TIFFTAG_PROFILE_HUE_SAT_MAP_DATA_1

• TIFFTAG_PROFILE_HUE_SAT_MAP_DATA_2

int libdng_set_exposure_program(libdng_info *dng, uint16_t mode)

Sets the exposure program used to take the picture. The intended values here are the LIBDNG_EXPOSUREPROGRAM_ constants which maps to the numbers in the DNG specification for the exposure programs:

#define LIBDNG_EXPOSUREPROGRAM_UNDEFINED 0
#define LIBDNG_EXPOSUREPROGRAM_MANUAL 1
#define LIBDNG_EXPOSUREPROGRAM_NORMAL 2
#define LIBDNG_EXPOSUREPROGRAM_APERTURE_PRIORITY 3
#define LIBDNG_EXPOSUREPROGRAM_SHUTTER_PRIORITY 4
#define LIBDNG_EXPOSUREPROGRAM_CREATIVE 5
#define LIBDNG_EXPOSUREPROGRAM_ACTION 6
#define LIBDNG_EXPOSUREPROGRAM_PORTRAIT 7
#define LIBDNG_EXPOSUREPROGRAM_LANDSCAPE 8

example use:

libdng_info dng = {0};
libdng_new(&dng);

libdng_set_exposure_program(&dng, LIBDNG_EXPOSUREPROGRAM_APERTURE_PRIORITY);

libdng_free(&dng);

Affected tags:

• EXIFTAG_EXPOSUREPROGRAM

int libdng_write(libdng_info *dng, const char *path, unsigned int width, unsigned int height, const uint8_t *data, size_t length)

This is the function that takes the raw data and stores it into a DNG file together with all the metadata that has been defined before this.

// This size is only valid for 8-bit pictures.
size_t src_size = 1280 * 720;
uint8_t *data = malloc(src_size);
// At this point the raw data should be _in_ data.

libdng_info dng = {0};
libdng_new(&dng);
if(!libdng_write(&dng, "/tmp/out.dng", 1280, 720, data, src_size)) {
  fprintf(stderr, "Could not write DNG\n");
  // handle errors here
}

free(data);
libdng_free(&dng);