image_repository.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2025 Aurélien PIERRE.
 
    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/>.
*/
 
#ifndef DT_DATABASE_IMAGE_REPOSITORY_H
#define DT_DATABASE_IMAGE_REPOSITORY_H
 
#include "common/image.h"
 
#include <sqlite3.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
G_BEGIN_DECLS
 
gboolean dt_image_repository_load(const int32_t imgid, dt_image_t *img);
 
void dt_image_repository_store(const dt_image_t *img);
 
typedef void (*dt_image_repository_collected_cb)(void *user_data, const dt_image_t *info);
 
void dt_image_repository_foreach_collected(dt_image_repository_collected_cb cb, void *user_data);
 
/* ---------------------------------------------------------------------------------------
 *  Grouping
 *
 *  `main.images.group_id`. Every image belongs to exactly one group, whose id is the id of
 *  one of its members; a lone image is its own group. These return and take plain image
 *  ids -- `common/grouping.c` keeps the rules (who leads a group, what happens to the rest
 *  when the leader leaves) and the image-cache updates that go with them.
 * ------------------------------------------------------------------------------------- */
 
/* ---------------------------------------------------------------------------------------
 *  Duplicating and copying a row, with everything that hangs off it
 *
 *  An image is one `main.images` row plus satellites in `main.color_labels`,
 *  `main.meta_data` and `main.tagged_images`. Copying one means copying all four, in one
 *  place, or the copy is silently partial -- which is why these are single calls rather
 *  than a set of per-table ones the caller would have to remember to make.
 *  (`main.module_order` is deliberately NOT among them: it travels with the history, which
 *  the caller copies next via dt_history_copy_and_paste_on_image().)
 * ------------------------------------------------------------------------------------- */
 
int32_t dt_image_repository_duplicate(const int32_t imgid, const int32_t newversion);
 
typedef struct dt_image_version_t
{
  int version;
  int32_t imgid;
  char *version_name;   
} dt_image_version_t;
 
void dt_image_version_free(gpointer data);
 
GList *dt_image_repository_get_versions(const int32_t film_id, const char *filename,
                                        const int name_keyid);
 
GList *dt_image_repository_get_duplicate_ids(const int32_t imgid);
 
int32_t dt_image_repository_copy_to_film(const int32_t imgid, const int32_t filmid,
                                         const char *new_filename, const char *old_filename);
 
/* ---------------------------------------------------------------------------------------
 *  The two reads that write a sidecar
 *
 *  Both distinguish a NULL column from a zero one, which is why they carry `has_*` flags
 *  rather than a sentinel: 0 is a legitimate longitude and a legitimate timestamp.
 * ------------------------------------------------------------------------------------- */
 
typedef struct dt_image_xmp_row_t
{
  char *filename;              
  int flags;
  int raw_parameters;
  int history_end;
  double longitude, latitude, altitude;
  gboolean has_longitude, has_latitude, has_altitude;
  int64_t datetime_taken;
} dt_image_xmp_row_t;
 
gboolean dt_image_repository_get_xmp_row(const int32_t imgid, dt_image_xmp_row_t *row);
 
void dt_image_repository_xmp_row_cleanup(dt_image_xmp_row_t *row);
 
typedef struct dt_image_timestamps_t
{
  int64_t import_timestamp, change_timestamp, export_timestamp, print_timestamp;
  gboolean has_import, has_change, has_export, has_print;
} dt_image_timestamps_t;
 
gboolean dt_image_repository_get_timestamps(const int32_t imgid, dt_image_timestamps_t *ts);
 
/* ---------------------------------------------------------------------------------------
 *  Identity lookups
 *
 *  Finding the row for a file on disk. Both of these answer -1 for "no such image", which is
 *  what dt_image_invalid() tests.
 * ------------------------------------------------------------------------------------- */
 
int32_t dt_image_repository_find_by_film_and_filename(const int32_t film_id, const char *filename);
 
int32_t dt_image_repository_find_by_folder_and_filename(const char *folder, const char *filename);
 
 
/* ---------------------------------------------------------------------------------------
 *  Versions, flags and the write timestamp
 * ------------------------------------------------------------------------------------- */
 
int dt_image_repository_get_version(const int32_t imgid);
 
gboolean dt_image_repository_set_version(const int32_t imgid, const int version);
 
int dt_image_repository_count_others_with_flag(const int32_t imgid, const int flag);
 
GList *dt_image_repository_get_ids_with_flag_among(GList *imgids, const int flag);
 
gboolean dt_image_repository_set_flag_among(GList *imgids, const int flag);
 
GList *dt_image_repository_get_full_paths(GList *imgids);
 
GList *dt_image_repository_get_ids_with_flag(const int flag);
 
gboolean dt_image_repository_set_flags(const int32_t imgid, const int flags);
 
typedef void (*dt_image_repository_path_row_cb)(const int32_t imgid,
                                                const int64_t write_timestamp,
                                                const int version,
                                                const char *image_path,
                                                const int flags,
                                                void *user_data);
 
void dt_image_repository_foreach_with_path(dt_image_repository_path_row_cb cb, void *user_data);
 
/* ---------------------------------------------------------------------------------------
 *  Geolocation
 *
 *  `main.images.latitude`/`longitude`, restricted to the current collection. The map view
 *  asks two questions of it: where to centre, and which images fall inside the viewport.
 * ------------------------------------------------------------------------------------- */
 
typedef struct dt_image_geo_bounds_t
{
  double min_latitude, max_latitude;
  double min_longitude, max_longitude;
  int count;   
} dt_image_geo_bounds_t;
 
gboolean dt_image_repository_get_collected_geo_bounds(dt_image_geo_bounds_t *bounds);
 
typedef struct dt_image_geo_point_t
{
  int32_t imgid;
  double longitude;
  double latitude;
} dt_image_geo_point_t;
 
dt_image_geo_point_t *dt_image_repository_get_collected_geo_points(const double lon1, const double lon2,
                                                                   const double lat1, const double lat2,
                                                                   int *count);
 
/* ---------------------------------------------------------------------------------------
 *  Do these images agree?
 * ------------------------------------------------------------------------------------- */
 
typedef enum dt_image_field_t
{
  DT_IMAGE_FIELD_FILM_ROLL = 0,
  DT_IMAGE_FIELD_FILM_ROLL_ID,
  DT_IMAGE_FIELD_IMGID,          
  DT_IMAGE_FIELD_GROUP_ID,
  DT_IMAGE_FIELD_FILENAME,
  DT_IMAGE_FIELD_VERSION,
  DT_IMAGE_FIELD_PATH,
  DT_IMAGE_FIELD_LOCAL_COPY,
  DT_IMAGE_FIELD_IMPORT_TIMESTAMP,
  DT_IMAGE_FIELD_CHANGE_TIMESTAMP,
  DT_IMAGE_FIELD_EXPORT_TIMESTAMP,
  DT_IMAGE_FIELD_PRINT_TIMESTAMP,
  DT_IMAGE_FIELD_FLAGS,
  DT_IMAGE_FIELD_MODEL,
  DT_IMAGE_FIELD_MAKER,
  DT_IMAGE_FIELD_LENS,
  DT_IMAGE_FIELD_APERTURE,
  DT_IMAGE_FIELD_EXPOSURE,
  DT_IMAGE_FIELD_EXPOSURE_BIAS,
  DT_IMAGE_FIELD_FOCAL_LENGTH,
  DT_IMAGE_FIELD_FOCUS_DISTANCE,
  DT_IMAGE_FIELD_ISO,
  DT_IMAGE_FIELD_DATETIME,
  DT_IMAGE_FIELD_WIDTH,
  DT_IMAGE_FIELD_HEIGHT,
  DT_IMAGE_FIELD_EXPORT_WIDTH,
  DT_IMAGE_FIELD_EXPORT_HEIGHT,
  DT_IMAGE_FIELD_META_TITLE,     
  DT_IMAGE_FIELD_META_DESCRIPTION,
  DT_IMAGE_FIELD_META_CREATOR,
  DT_IMAGE_FIELD_META_PUBLISHER,
  DT_IMAGE_FIELD_META_RIGHTS,
  DT_IMAGE_FIELD_META_NOTES,
  DT_IMAGE_FIELD_META_VERSION_NAME,
  DT_IMAGE_FIELD_META_IMAGE_ID,
  DT_IMAGE_FIELD_LATITUDE,
  DT_IMAGE_FIELD_LONGITUDE,
  DT_IMAGE_FIELD_ALTITUDE,
  DT_IMAGE_FIELD_COUNT
} dt_image_field_t;
 
int *dt_image_repository_count_distinct_fields(GList *imgids);
 
int64_t dt_image_repository_get_write_timestamp(const int32_t imgid);
 
void dt_image_repository_touch_write_timestamp(const int32_t imgid);
 
gboolean dt_image_repository_set_write_timestamp(const int32_t imgid, const int64_t timestamp);
 
gboolean dt_image_repository_delete(const int32_t imgid);
 
GList *dt_image_repository_get_group_members(const int32_t group_id, const int32_t exclude_imgid);
 
typedef struct dt_image_group_member_t
{
  int32_t imgid;
  int version;
  char *filename;
} dt_image_group_member_t;
 
void dt_image_group_member_free(gpointer data);
 
GList *dt_image_repository_get_group_member_rows(const int32_t group_id);
 
int dt_image_repository_count_in_id_range(const int32_t min_imgid, const int32_t max_imgid);
 
typedef void (*dt_image_repository_id_filename_cb)(const int32_t imgid, const char *filename,
                                                   void *user_data);
 
void dt_image_repository_foreach_in_id_range(const int32_t min_imgid, const int32_t max_imgid,
                                             dt_image_repository_id_filename_cb cb,
                                             void *user_data);
 
gboolean dt_image_repository_insert_import(const int32_t film_id, const char *filename,
                                           const int flags, const int64_t import_timestamp);
 
int32_t dt_image_repository_find_group_for_pattern(const int32_t film_id,
                                                   const char *filename_pattern,
                                                   const gboolean leader_only,
                                                   const int32_t exclude_imgid);
 
gboolean dt_image_repository_set_group(const int32_t imgid, const int32_t group_id);
 
 
void dt_image_repository_reassign_group(const int32_t from_group_id, const int32_t to_group_id,
                                        const int32_t exclude_imgid);
 
GList *dt_image_repository_get_ratings(const int32_t imgid);
 
void dt_image_repository_cleanup(void);
 
G_END_DECLS
 
 
#ifdef __cplusplus
}
#endif
 
#endif // DT_DATABASE_IMAGE_REPOSITORY_H
 
// 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