image.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2009-2014 johannes hanika.
    Copyright (C) 2010 Bruce Guenter.
    Copyright (C) 2010-2011 Henrik Andersson.
    Copyright (C) 2010-2012, 2014, 2016, 2018-2019 Tobias Ellinghaus.
    Copyright (C) 2011 José Carlos García Sogo.
    Copyright (C) 2011-2012, 2014 Jérémy Rosen.
    Copyright (C) 2011 Robert Bieber.
    Copyright (C) 2012 Christian Tellefsen.
    Copyright (C) 2012 marcel.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2013 Jean-Sébastien Pédron.
    Copyright (C) 2013, 2015, 2018-2022 Pascal Obry.
    Copyright (C) 2013-2017 Roman Lebedev.
    Copyright (C) 2013 Ulrich Pegelow.
    Copyright (C) 2014 Dan Torop.
    Copyright (C) 2014 Edouard Gomez.
    Copyright (C) 2014 Pascal de Bruijn.
    Copyright (C) 2014-2016 Pedro Côrte-Real.
    Copyright (C) 2017 Žilvinas Žaltiena.
    Copyright (C) 2018 Kelvie Wong.
    Copyright (C) 2019-2021 Aldric Renaudin.
    Copyright (C) 2019 Andreas Schneider.
    Copyright (C) 2019 August Schwerdfeger.
    Copyright (C) 2019 Bill Ferguson.
    Copyright (C) 2019-2022 Hanno Schwalm.
    Copyright (C) 2019 Jacques Le Clerc.
    Copyright (C) 2019 luzpaz.
    Copyright (C) 2019-2022 Philippe Weyland.
    Copyright (C) 2020-2021, 2023, 2025-2026 Aurélien PIERRE.
    Copyright (C) 2020 Chris Elston.
    Copyright (C) 2020 JP Verrue.
    Copyright (C) 2020 Matthieu Volat.
    Copyright (C) 2020 U-DESKTOP-HQME86J\marco.
    Copyright (C) 2021 Daniel Vogelbacher.
    Copyright (C) 2021 Miloš Komarčević.
    Copyright (C) 2021 Ralf Brown.
    Copyright (C) 2022 HansBull.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2022 paolodepetrillo.
    Copyright (C) 2023, 2025 Alynx Zhou.
    Copyright (C) 2023 Ricky Moon.
    Copyright (C) 2024-2025 Guillaume Stutin.
    
    darktable is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    darktable is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    
    You should have received a copy of the GNU General Public License
    along with darktable.  If not, see <http://www.gnu.org/licenses/>.
*/
 
#pragma once
 
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
 
#include "common/colorspaces.h"
#include "common/dtpthread.h"
#include "develop/format.h"
#include <glib.h>
#include <inttypes.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum dt_imageio_retval_t
{
  DT_IMAGEIO_OK = 0,         // all good :)
  DT_IMAGEIO_FILE_NOT_FOUND, // file has been lost
  DT_IMAGEIO_FILE_CORRUPTED, // file contains garbage
  DT_IMAGEIO_CACHE_FULL,     // dt's caches are full :(
  DT_IMAGEIO_UNSUPPORTED_FORMAT,  // file format not supported by loader
  DT_IMAGEIO_UNSUPPORTED_FEATURE, // format supported but uses unsupported feature
  DT_IMAGEIO_UNSUPPORTED_CAMERA,  // camera model not supported by loader
  DT_IMAGEIO_LOAD_FAILED,         // internal loader failure
  DT_IMAGEIO_IOERROR              // I/O error while reading file
} dt_imageio_retval_t;
 
typedef enum
{
  // the first 0x7 in flags are reserved for star ratings.
  // see view.h:
  //  DT_VIEW_DESERT = 0,
  //  DT_VIEW_STAR_1 = 1,
  //  DT_VIEW_STAR_2 = 2,
  //  DT_VIEW_STAR_3 = 3,
  //  DT_VIEW_STAR_4 = 4,
  //  DT_VIEW_STAR_5 = 5,
  DT_IMAGE_REJECTED = 1 << 3,
 
  // next field unused, but it used to be.
  // old DB entries might have it set.
  // To reuse : force to 0 in DB loading and force to 0 in DB saving
  // Use it to store a state that doesn't need to go in DB
  DT_IMAGE_THUMBNAIL_DEPRECATED = 1 << 4,
  // set during import if the image is low-dynamic range, i.e. doesn't need demosaic, wb, highlight clipping
  // etc.
  DT_IMAGE_LDR = 1 << 5,
  // set during import if the image is raw data, i.e. it needs demosaicing.
  DT_IMAGE_RAW = 1 << 6,
  // set during import if images is a high-dynamic range image..
  DT_IMAGE_HDR = 1 << 7,
  // set when marked for deletion
  DT_IMAGE_REMOVE = 1 << 8,
  // set when auto-applying presets have been applied to this image.
  DT_IMAGE_AUTO_PRESETS_APPLIED = 1 << 9,
  // legacy flag. is set for all new images. i hate to waste a bit on this :(
  DT_IMAGE_NO_LEGACY_PRESETS = 1 << 10,
  // local copy status
  DT_IMAGE_LOCAL_COPY = 1 << 11,
  // image has an associated .txt file for overlay
  DT_IMAGE_HAS_TXT = 1 << 12,
  // image has an associated wav file
  DT_IMAGE_HAS_WAV = 1 << 13,
  // image is a bayer pattern with 4 colors (e.g., CYGM or RGBE)
  DT_IMAGE_4BAYER = 1 << 14,
  // image was detected as monochrome
  DT_IMAGE_MONOCHROME = 1 << 15,
  // DNG image has exif tags which are not cached in the database but must be read and stored in dt_image_t
  // when the image is loaded.
  DT_IMAGE_HAS_ADDITIONAL_DNG_TAGS = 1 << 16,
  // image is an sraw
  DT_IMAGE_S_RAW = 1 << 17,
  // image has a monochrome preview tested
  DT_IMAGE_MONOCHROME_PREVIEW = 1 << 18,
  // image has been set to monochrome via demosaic module
  DT_IMAGE_MONOCHROME_BAYER = 1 << 19,
  // image has a flag set to use the monochrome workflow in the modules supporting it
  DT_IMAGE_MONOCHROME_WORKFLOW = 1 << 20,
  // the decoded buffer carries a CFA mosaic (dsc.filters != 0), i.e. it still needs
  // demosaicing. Set/cleared by dt_image_buffer_resolve_flags() from the decoded buffer
  // descriptor. This is the bit that separates a mosaiced raw from an already-demosaiced
  // raw (sRAW / linear DNG), a distinction that otherwise only lives in the dsc.filters
  // field which is never stored in the database. Persisted to DB through the image cache.
  DT_IMAGE_MOSAIC = 1 << 21,
  // the codec has decoded the file at least once, so the buffer-derived classification
  // (DT_IMAGE_MOSAIC and the dsc descriptor) is authoritative. Until this bit is set the
  // pipeline class is only a provisional guess inferred from the filename extension at
  // import time. Persisted to DB through the image cache.
  DT_IMAGE_BUFFER_RESOLVED = 1 << 22,
} dt_image_flags_t;
 
typedef enum dt_image_pipe_class_t
{
  DT_IMAGE_PIPE_UNKNOWN = 0, // not yet resolved and the extension gave no hint
  DT_IMAGE_PIPE_MOSAIC_RAW,  // raw colorimetry + CFA mosaic: needs rawprepare AND demosaic
  DT_IMAGE_PIPE_LINEAR_RAW,  // raw colorimetry, already demosaiced (sRAW / linear DNG): rawprepare, no demosaic
  DT_IMAGE_PIPE_RGB_LDR,     // display-referred integer RGB (jpg/png/tiff8...)
  DT_IMAGE_PIPE_RGB_HDR,     // scene/linear float RGB (exr/pfm/hdr/float-tiff)
} dt_image_pipe_class_t;
 
typedef enum dt_image_colorspace_t
{
  DT_IMAGE_COLORSPACE_NONE,
  DT_IMAGE_COLORSPACE_SRGB,
  DT_IMAGE_COLORSPACE_ADOBE_RGB
} dt_image_colorspace_t;
 
typedef struct dt_image_raw_parameters_t
{
  unsigned legacy : 24;
  unsigned user_flip : 8; // +8 = 32 bits.
} dt_image_raw_parameters_t;
 
typedef enum dt_exif_image_orientation_t
{
  EXIF_ORIENTATION_NONE              = 1,
  EXIF_ORIENTATION_FLIP_HORIZONTALLY = 2,
  EXIF_ORIENTATION_FLIP_VERTICALLY   = 4,
  EXIF_ORIENTATION_ROTATE_180_DEG    = 3,
  EXIF_ORIENTATION_TRANSPOSE         = 5,
  EXIF_ORIENTATION_ROTATE_CCW_90_DEG = 8,
  EXIF_ORIENTATION_ROTATE_CW_90_DEG  = 6,
  EXIF_ORIENTATION_TRANSVERSE        = 7
} dt_exif_image_orientation_t;
 
typedef enum dt_image_orientation_t
{
  ORIENTATION_NULL    = -1,     //-1, or autodetect
  ORIENTATION_NONE    = 0,      // 0
  ORIENTATION_FLIP_Y  = 1 << 0, // 1
  ORIENTATION_FLIP_X  = 1 << 1, // 2
  ORIENTATION_SWAP_XY = 1 << 2, // 4
 
  /* ClockWise rotation == "-"; CounterClockWise rotation == "+" */
  ORIENTATION_FLIP_HORIZONTALLY = ORIENTATION_FLIP_X, // 2
  ORIENTATION_FLIP_VERTICALLY   = ORIENTATION_FLIP_Y, // 1
  ORIENTATION_ROTATE_180_DEG    = ORIENTATION_FLIP_Y | ORIENTATION_FLIP_X, // 3
  ORIENTATION_TRANSPOSE         = ORIENTATION_SWAP_XY, // 4
  ORIENTATION_ROTATE_CCW_90_DEG = ORIENTATION_FLIP_X | ORIENTATION_SWAP_XY, // 6
  ORIENTATION_ROTATE_CW_90_DEG  = ORIENTATION_FLIP_Y | ORIENTATION_SWAP_XY, // 5
  ORIENTATION_TRANSVERSE        = ORIENTATION_FLIP_Y | ORIENTATION_FLIP_X | ORIENTATION_SWAP_XY // 7
} dt_image_orientation_t;
 
typedef enum dt_image_loader_t
{
  LOADER_UNKNOWN  =  0,
  LOADER_TIFF     =  1,
  LOADER_PNG      =  2,
  LOADER_J2K      =  3,
  LOADER_JPEG     =  4,
  LOADER_EXR      =  5,
  LOADER_RGBE     =  6,
  LOADER_PFM      =  7,
  LOADER_GM       =  8,
  LOADER_RAWSPEED =  9,
  LOADER_PNM      = 10,
  LOADER_AVIF     = 11,
  LOADER_IM       = 12,
  LOADER_HEIF     = 13,
  LOADER_LIBRAW   = 14,
  LOADER_WEBP     = 15,
  LOADER_COUNT    = 16, // keep last
} dt_image_loader_t;
 
typedef enum dt_image_path_source_t
{
  DT_IMAGE_PATH_NONE = 0,
  DT_IMAGE_PATH_LOCAL_COPY,
  DT_IMAGE_PATH_LOCAL_COPY_LEGACY,
  DT_IMAGE_PATH_ORIGINAL
} dt_image_path_source_t;
 
static const struct
{
  const char *tooltip;
  const char flag;
} loaders_info[LOADER_COUNT] =
{
  { N_("unknown"),         '.'}, // EMPTY_FIELD
  { N_("tiff"),            't'},
  { N_("png"),             'p'},
  { N_("j2k"),             'J'},
  { N_("jpeg"),            'j'},
  { N_("exr"),             'e'},
  { N_("rgbe"),            'R'},
  { N_("pfm"),             'P'},
  { N_("GraphicsMagick"),  'g'},
  { N_("rawspeed"),        'r'},
  { N_("netpnm"),          'n'},
  { N_("avif"),            'a'},
  { N_("ImageMagick"),     'i'},
  { N_("heif"),            'h'},
  { N_("libraw"),          'l'},
  { N_("webp"),            'w'}
};
 
typedef struct dt_image_geoloc_t
{
  double longitude, latitude, elevation;
} dt_image_geoloc_t;
 
struct dt_cache_entry_t;
 
typedef struct dt_image_t
{
  // minimal exif data here (all in multiples of 4-byte to interface nicely with c++):
  int32_t exif_inited;
  dt_image_orientation_t orientation;
  float exif_exposure;
  float exif_exposure_bias;
  float exif_aperture;
  float exif_iso;
  float exif_focal_length;
  float exif_focus_distance;
  float exif_crop;
  char exif_maker[64];
  char exif_model[64];
  char exif_lens[128];
  GTimeSpan exif_datetime_taken;
 
  char camera_maker[64];
  char camera_model[64];
  char camera_alias[64];
  char camera_makermodel[128];
  char camera_legacy_makermodel[128];
  gboolean camera_missing_sample;
 
  char filename[DT_MAX_FILENAME_LEN];
  char fullpath[PATH_MAX];
  char local_copy_path[PATH_MAX];
  char local_copy_legacy_path[PATH_MAX];
  char folder[PATH_MAX];
  char filmroll[PATH_MAX];
  char datetime[200];
 
  // common stuff
 
  // to understand this, look at comment for dt_histogram_roi_t
  int32_t width, height, p_width, p_height;
  int32_t crop_x, crop_y, crop_width, crop_height;
 
  // used by library
  int32_t num, flags, film_id, id, group_id, version;
  uint32_t group_members;
  uint32_t history_items;
  uint64_t history_hash;
 
  // mipmap_hash is stored in database as an attempt to record the validity
  // of thumbnails stored on the disk cache. But it is actually unusable until we
  // have one hash per mipmap size. So it's not implemented anywhere for now.
  // Saving all hashes for all mipmap sizes will change the database structure and
  // loose compatibility.
  uint64_t mipmap_hash;
  uint64_t self_hash;
 
  //timestamps
  GTimeSpan import_timestamp, change_timestamp, export_timestamp, print_timestamp;
 
  dt_image_loader_t loader;
 
  dt_iop_buffer_dsc_t dsc;
 
  float d65_color_matrix[9]; // the 3x3 matrix embedded in some DNGs
  uint8_t *profile;          // embedded profile, for example from JPEGs
  uint32_t profile_size;
  dt_image_colorspace_t colorspace; // the colorspace that is specified in exif. mostly used for jpeg files
 
  dt_image_raw_parameters_t legacy_flip; // unfortunately needed to convert old bits to new flip module.
 
  /* gps coords */
  dt_image_geoloc_t geoloc;
 
  /* needed in exposure iop for Deflicker */
  uint16_t raw_black_level;
  uint16_t raw_black_level_separate[4];
  uint32_t raw_white_point;
 
  /* needed to fix some manufacturers madness */
  uint32_t fuji_rotation_pos;
  float pixel_aspect_ratio;
 
  /* White balance coeffs from the raw */
  dt_aligned_pixel_t wb_coeffs;
 
  /* Adobe coeffs from the raw */
  float adobe_XYZ_to_CAM[4][3];
 
  /* DefaultUserCrop */
  dt_boundingbox_t usercrop;
 
  /* GainMaps from DNG OpcodeList2 exif tag */
  GList *dng_gain_maps;
 
  /* Color labels */
  int color_labels;
  int rating;
 
  gboolean has_localcopy;
  gboolean has_audio;
  gboolean is_bw;
  gboolean is_bw_flow;
  gboolean is_hdr;
 
  /* convenience pointer back into the image cache, so we can return dt_image_t* there directly. */
  struct dt_cache_entry_t *cache_entry;
} dt_image_t;
 
// image buffer operations:
void dt_image_init(dt_image_t *img);
void dt_image_refresh_makermodel(dt_image_t *img);
gboolean dt_image_is_raw(const dt_image_t *img);
gboolean dt_image_is_ldr(const dt_image_t *img);
gboolean dt_image_is_hdr(const dt_image_t *img);
 
/* ------------------------------------------------------------------------------------------
 * Canonical image-type API.
 *
 * Each predicate below tests exactly ONE independent fact about img->flags (no overlapping
 * conditions, no filename-extension sniffing). The mutually-exclusive classification is
 * dt_image_pipe_class(); the orthogonal predicates answer the individual "does this image
 * need stage X" questions used by module auto-enable logic. See src/doc/image-type-detection.md.
 * ------------------------------------------------------------------------------------------ */
 
dt_image_pipe_class_t dt_image_pipe_class(const dt_image_t *img);
gboolean dt_image_pipe_class_is_provisional(const dt_image_t *img);
const char *dt_image_pipe_class_name(const dt_image_pipe_class_t klass);
 
gboolean dt_image_needs_rawprepare(const dt_image_t *img);
gboolean dt_image_needs_demosaic(const dt_image_t *img);
gboolean dt_image_is_mosaiced(const dt_image_t *img);
gboolean dt_image_is_sraw(const dt_image_t *img);
 
void dt_image_buffer_resolve_flags(dt_image_t *img);
void dt_image_set_provisional_dsc(dt_image_t *img);
void dt_image_set_monochrome_flag(const int32_t imgid, gboolean monochrome);
gboolean dt_image_is_monochrome(const dt_image_t *img);
gboolean dt_image_is_matrix_correction_supported(const dt_image_t *img);
int dt_image_monochrome_flags(const dt_image_t *img);
gboolean dt_image_use_monochrome_workflow(const dt_image_t *img);
void dt_image_print_debug_info(const dt_image_t *img, const char *context);
void dt_image_full_path(const int32_t imgid, char *pathname, size_t pathname_len, gboolean *from_cache, const char *calling_func);
void dt_image_local_copy_paths_from_fullpath(const char *fullpath, int32_t imgid, char *local_copy_path,
                                             size_t local_copy_len, char *local_copy_legacy_path,
                                             size_t local_copy_legacy_len);
dt_image_path_source_t dt_image_choose_input_path(const dt_image_t *img, char *pathname,
                                                  size_t pathname_len, gboolean force_cache);
void dt_image_film_roll_directory(const dt_image_t *img, char *pathname, size_t pathname_len);
const char *dt_image_film_roll_name(const char *path);
void dt_image_film_roll(const dt_image_t *img, char *pathname, size_t pathname_len);
void dt_image_path_append_version_no_db(int version, char *pathname, size_t pathname_len);
void dt_image_path_append_version(const int32_t imgid, char *pathname, size_t pathname_len);
void dt_image_print_exif(const dt_image_t *img, char *line, size_t line_len);
/* set rating to img flags */
void dt_image_set_xmp_rating(dt_image_t *img, const int rating);
/* get rating from img flags */
int dt_image_get_xmp_rating(const dt_image_t *img);
int dt_image_get_xmp_rating_from_flags(const int flags);
GList* dt_image_find_xmps(const char* filename);
int32_t dt_image_get_id_full_path(const gchar *filename);
int32_t dt_image_get_id(int32_t film_id, const gchar *filename);
int32_t dt_image_import(int32_t film_id, const char *filename, gboolean raise_signals);
int32_t dt_image_import_lua(int32_t film_id, const char *filename);
void dt_image_remove(const int32_t imgid);
int32_t dt_image_duplicate_with_version(const int32_t imgid, const int32_t newversion);
int32_t dt_image_duplicate(const int32_t imgid);
void dt_image_history_changed(const int32_t imgid, const gboolean refresh_filmstrip);
void dt_image_flip(const int32_t imgid, const int32_t cw);
void dt_image_set_flip(const int32_t imgid, const dt_image_orientation_t user_flip);
dt_image_orientation_t dt_image_get_orientation(const int32_t imgid);
void dt_image_set_location(const int32_t imgid, const dt_image_geoloc_t *geoloc,
                           const gboolean undo_on, const gboolean group_on);
void dt_image_set_locations(const GList *img, const dt_image_geoloc_t *geoloc,
                           const gboolean undo_on);
void dt_image_set_images_locations(const GList *imgs, const GArray *gloc,
                                   const gboolean undo_on);
void dt_image_get_location(const int32_t imgid, dt_image_geoloc_t *geoloc);
uint32_t dt_image_altered(const int32_t imgid);
void dt_image_cleanup(void);
 
static inline dt_image_orientation_t dt_image_orientation(const dt_image_t *img)
{
  return img->orientation != ORIENTATION_NULL ? img->orientation : ORIENTATION_NONE;
}
 
static inline dt_image_orientation_t dt_image_orientation_to_flip_bits(const int orient)
{
  switch(orient)
  {
    case EXIF_ORIENTATION_NONE:
      return ORIENTATION_NONE;
    case EXIF_ORIENTATION_FLIP_HORIZONTALLY:
      return ORIENTATION_FLIP_HORIZONTALLY;
    case EXIF_ORIENTATION_ROTATE_180_DEG:
      return ORIENTATION_ROTATE_180_DEG;
    case EXIF_ORIENTATION_FLIP_VERTICALLY:
      return ORIENTATION_FLIP_VERTICALLY;
    case EXIF_ORIENTATION_TRANSPOSE:
      return ORIENTATION_TRANSPOSE;
    case EXIF_ORIENTATION_ROTATE_CW_90_DEG:
      return ORIENTATION_ROTATE_CW_90_DEG;
    case EXIF_ORIENTATION_TRANSVERSE:
      return ORIENTATION_TRANSVERSE;
    case EXIF_ORIENTATION_ROTATE_CCW_90_DEG:
      return ORIENTATION_ROTATE_CCW_90_DEG;
    default:
      return ORIENTATION_NONE;
  }
}
 
int32_t dt_image_move(const int32_t imgid, const int32_t filmid);
int32_t dt_image_rename(const int32_t imgid, const int32_t filmid, const gchar *newname);
int32_t dt_image_copy(const int32_t imgid, const int32_t filmid);
int32_t dt_image_copy_rename(const int32_t imgid, const int32_t filmid, const gchar *newname);
int dt_image_local_copy_set(const int32_t imgid);
int dt_image_local_copy_reset(const int32_t imgid);
/* check whether it is safe to remove a file */
gboolean dt_image_safe_remove(const int32_t imgid);
/* try to sync .xmp for all local copies */
void dt_image_local_copy_synch();
// xmp functions:
int dt_image_write_sidecar_file(const int32_t imgid);
void dt_image_synch_xmp(const int selected);
void dt_image_synch_xmps(const GList *img);
void dt_image_synch_all_xmp(const gchar *pathname);
gboolean dt_image_get_xmp_mode();
 
// set datetime to exif_datetime_taken field
void dt_image_set_datetime(const GList *imgs, const char *datetime, const gboolean undo_on);
// set datetimeS to exif_datetime_taken field
void dt_image_set_datetimes(const GList *imgs, const GArray *dtime, const gboolean undo_on);
// return image datetime string into the given buffer (size = DT_DATETIME_LENGTH)
void dt_image_get_datetime(const int32_t imgid, char *datetime);
 
char *dt_image_get_audio_path(const int32_t imgid);
char *dt_image_get_audio_path_from_path(const char *image_path);
char *dt_image_get_text_path(const int32_t imgid);
char *dt_image_get_text_path_from_path(const char *image_path);
char *dt_image_build_text_path_from_path(const char *image_path);
 
float dt_image_get_exposure_bias(const struct dt_image_t *image_storage);
 
char *dt_image_camera_missing_sample_message(const struct dt_image_t *img, gboolean logmsg);
void dt_image_check_camera_missing_sample(const struct dt_image_t *img);
void dt_get_dirname_from_imgid(gchar *dir, const int32_t imgid);
// Search for duplicate's sidecar files and import them if found and not in DB yet
int dt_image_read_duplicates(const uint32_t id, const char *filename, const gboolean clear_selection);
 
#ifdef __cplusplus
}
#endif
 
// clang-format off
// modelines: These editor modelines have been set for all relevant files by tools/update_modelines.py
// vim: shiftwidth=2 expandtab tabstop=2 cindent
// kate: tab-indents: off; indent-width 2; replace-tabs on; indent-mode cstyle; remove-trailing-spaces modified;
// clang-format on