librtcore.h

Go to the documentation of this file.

/*
 *
 * WKTRaster - Raster Types for PostGIS
 * http://trac.osgeo.org/postgis/wiki/WKTRaster
 *
 * Copyright (C) 2011-2013 Regents of the University of California
 *   <bkpark@ucdavis.edu>
 * Copyright (C) 2010-2011 Jorge Arevalo <jorge.arevalo@deimos-space.com>
 * Copyright (C) 2010-2011 David Zwarg <dzwarg@azavea.com>
 * Copyright (C) 2009-2011 Pierre Racine <pierre.racine@sbf.ulaval.ca>
 * Copyright (C) 2009-2011 Mateusz Loskot <mateusz@loskot.net>
 * Copyright (C) 2008-2009 Sandro Santilli <strk@kbt.io>
 * Copyright (C) 2013 Nathaneil Hunter Clay <clay.nathaniel@gmail.com
 *
 * This program 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 2
 * of the License, or (at your option) any later version.
 *
 * This program 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 this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 */
 
/******************************************************************************
* Some rules for *.(c|h) files in rt_core
*
* All functions in rt_core that receive a band index parameter
*   must be 0-based
*
* Variables and functions internal for a public function should be prefixed
*   with _rti_, e.g. _rti_iterator_arg.
******************************************************************************/
 
#ifndef LIBRTCORE_H_INCLUDED
#define LIBRTCORE_H_INCLUDED
 
/* define the systems */
#if defined(__linux__)  /* (predefined) */
#if !defined(LINUX)
#define LINUX
#endif
#if !defined(UNIX)
#define UNIX        /* make sure this is defined */
#endif
#endif
 
 
#if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__OpenBSD__)    /* seems to work like Linux... */
#if !defined(LINUX)
#define LINUX
#endif
#if !defined(UNIX)
#define UNIX        /* make sure this is defined */
#endif
#endif
 
#if defined(__GNU__)    /* GNU/Hurd is also like Linux */
#if !defined(LINUX)
#define LINUX
#endif
#if !defined(UNIX)
#define UNIX        /* make sure this is defined */
#endif
#endif
 
#if defined(__MSDOS__)
#if !defined(MSDOS)
#define MSDOS       /* make sure this is defined */
#endif
#endif
 
#if defined(__WIN32__) || defined(__NT__) || defined(_WIN32)
#if !defined(WIN32)
#define WIN32
#endif
#if defined(__BORLANDC__) && defined(MSDOS) /* Borland always defines MSDOS */
#undef  MSDOS
#endif
#endif
 
#if defined(__APPLE__)
#if !defined(UNIX)
#define UNIX
#endif
#endif
 
#if defined(sun) || defined(__sun)
#if !defined(UNIX)
#define UNIX
#endif
#endif
 
#include <stdio.h> /* for printf, sprintf */
#include <stdlib.h> /* For size_t, srand and rand */
#include <stdint.h> /* For C99 int types */
#include <string.h> /* for memcpy, strlen, etc */
#include <float.h> /* for FLT_EPSILON, DBL_EPSILON and float type limits */
#include <limits.h> /* for integer type limits */
 
#include "liblwgeom.h"
 
#include "gdal_alg.h"
#include "gdal_frmts.h"
#include "gdal.h"
#include "gdalwarper.h"
#include "cpl_vsi.h"
#include "cpl_conv.h"
#include "ogr_api.h"
#include "ogr_srs_api.h"
 
#include "../../postgis_config.h"
#include "../raster_config.h"
 
#ifndef __GNUC__
# define __attribute__ (x)
#endif
 
typedef struct rt_raster_t* rt_raster;
typedef struct rt_band_t* rt_band;
typedef struct rt_pixel_t* rt_pixel;
typedef struct rt_mask_t* rt_mask;
typedef struct rt_geomval_t* rt_geomval;
typedef struct rt_bandstats_t* rt_bandstats;
typedef struct rt_histogram_t* rt_histogram;
typedef struct rt_quantile_t* rt_quantile;
typedef struct rt_valuecount_t* rt_valuecount;
typedef struct rt_gdaldriver_t* rt_gdaldriver;
typedef struct rt_reclassexpr_t* rt_reclassexpr;
 
typedef struct rt_iterator_t* rt_iterator;
typedef struct rt_iterator_arg_t* rt_iterator_arg;
 
typedef struct rt_colormap_entry_t* rt_colormap_entry;
typedef struct rt_colormap_t* rt_colormap;
 
/* envelope information */
typedef struct {
        double MinX;
        double MaxX;
        double MinY;
        double MaxY;
 
        double UpperLeftX;
        double UpperLeftY;
} rt_envelope;
 
/* function return error states */
typedef enum {
        ES_NONE = 0, /* no error */
        ES_ERROR = 1 /* generic error */
} rt_errorstate;
 
/* Pixel types */
typedef enum {
    PT_1BB=0,     /* 1-bit boolean            */
    PT_2BUI=1,    /* 2-bit unsigned integer   */
    PT_4BUI=2,    /* 4-bit unsigned integer   */
    PT_8BSI=3,    /* 8-bit signed integer     */
    PT_8BUI=4,    /* 8-bit unsigned integer   */
    PT_16BSI=5,   /* 16-bit signed integer    */
    PT_16BUI=6,   /* 16-bit unsigned integer  */
    PT_32BSI=7,   /* 32-bit signed integer    */
    PT_32BUI=8,   /* 32-bit unsigned integer  */
    PT_32BF=10,   /* 32-bit float             */
    PT_64BF=11,   /* 64-bit float             */
    PT_END=13
} rt_pixtype;
 
typedef enum {
        ET_INTERSECTION = 0,
        ET_UNION,
        ET_FIRST,
        ET_SECOND,
        ET_LAST,
        ET_CUSTOM
} rt_extenttype;
 
typedef enum {
        GSR_OVERLAPS = 0,
        GSR_TOUCHES,
        GSR_CONTAINS,
        GSR_CONTAINSPROPERLY,
        GSR_COVERS,
        GSR_COVEREDBY
} rt_geos_spatial_test;
 
typedef void* (*rt_allocator)(size_t size);
typedef void* (*rt_reallocator)(void *mem, size_t size);
typedef void  (*rt_deallocator)(void *mem);
typedef void  (*rt_message_handler)(const char* string, va_list ap)
  __attribute__ (( format(printf,1,0) ));
 
/*******************************************************************
 * Functions that may be used by the raster core function's caller
 * (for example: rt_pg functions, test functions, future loader/exporter)
 *******************************************************************/
extern void rt_install_default_allocators(void);
 
 
extern void* rtalloc(size_t size);
extern void* rtrealloc(void* mem, size_t size);
extern void rtdealloc(void* mem);
 
/******************************************************************/
 
 
void rterror(const char *fmt, ...);
void rtinfo(const char *fmt, ...);
void rtwarn(const char *fmt, ...);
 
 
void * default_rt_allocator(size_t size);
void * default_rt_reallocator(void * mem, size_t size);
void default_rt_deallocator(void * mem);
void default_rt_error_handler(const char * fmt, va_list ap);
void default_rt_warning_handler(const char * fmt, va_list ap);
void default_rt_info_handler(const char * fmt, va_list ap);
 
 
/* Debugging macros */
#if POSTGIS_DEBUG_LEVEL > 0
 
/* Display a simple message at NOTICE level */
#define RASTER_DEBUG(level, msg) \
    do { \
        if (POSTGIS_DEBUG_LEVEL >= level) \
            rtinfo("[%s:%s:%d] " msg, __FILE__, __func__, __LINE__); \
    } while (0);
 
/* Display a formatted message at NOTICE level (like printf, with variadic arguments) */
#define RASTER_DEBUGF(level, msg, ...) \
    do { \
        if (POSTGIS_DEBUG_LEVEL >= level) \
            rtinfo("[%s:%s:%d] " msg, __FILE__, __func__, __LINE__, __VA_ARGS__); \
    } while (0);
 
#else
 
/* Empty prototype that can be optimised away by the compiler for non-debug builds */
#define RASTER_DEBUG(level, msg) \
    ((void) 0)
 
/* Empty prototype that can be optimised away by the compiler for non-debug builds */
#define RASTER_DEBUGF(level, msg, ...) \
    ((void) 0)
 
#endif
 
/*- memory context -------------------------------------------------------*/
 
void rt_set_handlers(rt_allocator allocator, rt_reallocator reallocator,
        rt_deallocator deallocator, rt_message_handler error_handler,
        rt_message_handler info_handler, rt_message_handler warning_handler);
 
 
 
/*- rt_pixtype --------------------------------------------------------*/
 
int rt_pixtype_size(rt_pixtype pixtype);
 
int rt_pixtype_alignment(rt_pixtype pixtype);
 
/* Return human-readable name of pixel type */
const char* rt_pixtype_name(rt_pixtype pixtype);
 
/* Return pixel type index from human-readable name */
rt_pixtype rt_pixtype_index_from_name(const char* pixname);
 
double rt_pixtype_get_min_value(rt_pixtype pixtype);
 
rt_errorstate rt_pixtype_compare_clamped_values(
        rt_pixtype pixtype,
        double val, double refval,
        int *isequal
);
 
/*- rt_pixel ----------------------------------------------------------*/
 
/*
 * Convert an array of rt_pixel objects to two 2D arrays of value and NODATA.
 * The dimensions of the returned 2D array are [Y][X], going by row Y and
 * then column X.
 *
 * @param npixel : array of rt_pixel objects
 * @param count : number of elements in npixel
 * @param mask : mask to be respected when returning array
 * @param x : the column of the center pixel (0-based)
 * @param y : the line of the center pixel (0-based)
 * @param distancex : the number of pixels around the specified pixel
 * along the X axis
 * @param distancey : the number of pixels around the specified pixel
 * along the Y axis
 * @param value : pointer to pointer for 2D value array
 * @param nodata : pointer to pointer for 2D NODATA array
 * @param dimx : size of value and nodata along the X axis
 * @param dimy : size of value and nodata along the Y axis
 *
 * @return ES_NONE on success, ES_ERROR on error
 */
rt_errorstate rt_pixel_set_to_array(
        rt_pixel npixel,uint32_t count,
        rt_mask mask,
        int x, int y,
        uint16_t distancex, uint16_t distancey,
        double ***value,
        int ***nodata,
        int *dimx, int *dimy
);
 
/*- rt_band ----------------------------------------------------------*/
 
rt_band rt_band_new_inline(
        uint16_t width, uint16_t height,
        rt_pixtype pixtype,
        uint32_t hasnodata, double nodataval,
        uint8_t* data
);
 
rt_band rt_band_new_offline(
        uint16_t width, uint16_t height,
        rt_pixtype pixtype,
        uint32_t hasnodata, double nodataval,
        uint8_t bandNum, const char* path
);
 
rt_band
rt_band_new_offline_from_path(
        uint16_t width,
        uint16_t height,
        int hasnodata,
        double nodataval,
        uint8_t bandNum,
        const char* path,
        int force
);
 
rt_band rt_band_duplicate(rt_band band);
 
int rt_band_is_offline(rt_band band);
 
const char* rt_band_get_ext_path(rt_band band);
 
uint64_t rt_band_get_file_size(rt_band band);
 
uint64_t rt_band_get_file_timestamp(rt_band band);
 
rt_errorstate rt_band_get_ext_band_num(rt_band band, uint8_t *bandnum);
 
rt_pixtype rt_band_get_pixtype(rt_band band);
 
uint16_t rt_band_get_width(rt_band band);
 
uint16_t rt_band_get_height(rt_band band);
 
int rt_band_get_ownsdata_flag(rt_band band);
 
/* set ownsdata flag */
void rt_band_set_ownsdata_flag(rt_band band, int flag);
 
void* rt_band_get_data(rt_band band);
 
rt_errorstate rt_band_load_offline_data(rt_band band);
 
void rt_band_destroy(rt_band band);
 
int rt_band_get_hasnodata_flag(rt_band band);
 
void rt_band_set_hasnodata_flag(rt_band band, int flag);
 
rt_errorstate rt_band_set_isnodata_flag(rt_band band, int flag);
 
int rt_band_get_isnodata_flag(rt_band band);
 
rt_errorstate rt_band_set_nodata(rt_band band, double val, int *converted);
 
rt_errorstate rt_band_get_nodata(rt_band band, double *nodata);
 
rt_errorstate rt_band_set_pixel_line(
        rt_band band,
        int x, int y,
        void *vals, uint32_t len
);
 
rt_errorstate rt_band_set_pixel(
        rt_band band,
        int x, int y,
        double val,
        int *converted
);
 
rt_errorstate rt_band_get_pixel_line(
        rt_band band,
        int x, int y,
        uint16_t len,
        void **vals, uint16_t *nvals
);
 
rt_errorstate rt_band_get_pixel(
        rt_band band,
        int x, int y,
        double *value,
        int *nodata
);
 
uint32_t rt_band_get_nearest_pixel(
        rt_band band,
        int x, int y,
        uint16_t distancex, uint16_t distancey,
        int exclude_nodata_value,
        rt_pixel *npixels
);
 
int rt_band_get_pixel_of_value(
        rt_band band, int exclude_nodata_value,
        double *searchset, int searchcount,
        rt_pixel *pixels
);
 
double rt_band_get_min_value(rt_band band);
 
int rt_band_check_is_nodata(rt_band band);
 
int rt_band_clamped_value_is_nodata(rt_band band, double val);
 
rt_errorstate
rt_band_corrected_clamped_value(
        rt_band band,
        double val,
        double *newval, int *corrected
);
 
rt_bandstats rt_band_get_summary_stats(
        rt_band band,
        int exclude_nodata_value, double sample, int inc_vals,
        uint64_t *cK, double *cM, double *cQ
);
 
rt_histogram rt_band_get_histogram(
        rt_bandstats stats,
        uint32_t bin_count, double *bin_widths, uint32_t bin_widths_count,
        int right, double min, double max,
        uint32_t *rtn_count
);
 
rt_quantile rt_band_get_quantiles(rt_bandstats stats,
        double *quantiles, int quantiles_count, uint32_t *rtn_count);
 
struct quantile_llist;
int quantile_llist_destroy(
        struct quantile_llist **list,
        uint32_t list_count
);
 
rt_quantile rt_band_get_quantiles_stream(
        rt_band band,
        int exclude_nodata_value, double sample,
        uint64_t cov_count,
        struct quantile_llist **qlls, uint32_t *qlls_count,
        double *quantiles, uint32_t quantiles_count,
        uint32_t *rtn_count
);
 
rt_valuecount rt_band_get_value_count(
        rt_band band, int exclude_nodata_value,
        double *search_values, uint32_t search_values_count, double roundto,
        uint32_t *rtn_total, uint32_t *rtn_count
);
 
rt_band rt_band_reclass(
        rt_band srcband, rt_pixtype pixtype,
        uint32_t hasnodata, double nodataval,
        rt_reclassexpr *exprset, int exprcount
);
 
/*- rt_raster --------------------------------------------------------*/
 
rt_raster rt_raster_new(uint32_t width, uint32_t height);
 
rt_raster rt_raster_from_wkb(const uint8_t* wkb, uint32_t wkbsize);
 
rt_raster rt_raster_from_hexwkb(const char* hexwkb, uint32_t hexwkbsize);
 
uint8_t *rt_raster_to_wkb(rt_raster raster, int outasin, uint32_t *wkbsize);
 
char *rt_raster_to_hexwkb(rt_raster raster, int outasin, uint32_t *hexwkbsize);
 
void rt_raster_destroy(rt_raster raster);
 
/* Get number of bands */
uint16_t rt_raster_get_num_bands(rt_raster raster);
 
rt_band rt_raster_get_band(rt_raster raster, int bandNum);
 
/* Get number of rows */
uint16_t rt_raster_get_width(rt_raster raster);
 
/* Get number of columns */
uint16_t rt_raster_get_height(rt_raster raster);
 
int rt_raster_add_band(rt_raster raster, rt_band band, int index);
 
int rt_raster_generate_new_band(
        rt_raster raster,
        rt_pixtype pixtype,
        double initialvalue,
        uint32_t hasnodata, double nodatavalue,
        int index
);
 
void rt_raster_set_scale(rt_raster raster,
                               double scaleX, double scaleY);
 
double rt_raster_get_x_scale(rt_raster raster);
 
double rt_raster_get_y_scale(rt_raster raster);
 
void rt_raster_set_offsets(rt_raster raster,
                           double x, double y);
 
double rt_raster_get_x_offset(rt_raster raster);
 
double rt_raster_get_y_offset(rt_raster raster);
 
void rt_raster_set_skews(rt_raster raster,
                             double skewX, double skewY);
 
double rt_raster_get_x_skew(rt_raster raster);
 
double rt_raster_get_y_skew(rt_raster raster);
 
void rt_raster_get_phys_params(rt_raster rast,
        double *i_mag, double *j_mag, double *theta_i, double *theta_ij) ;
 
void rt_raster_set_phys_params(rt_raster rast,
        double i_mag, double j_mag, double theta_i, double theta_ij) ;
 
 
void rt_raster_calc_phys_params(double xscale,
        double xskew, double yskew, double yscale,
        double *i_mag, double *j_mag, double *theta_i, double *theta_ij) ;
 
 
int rt_raster_calc_gt_coeff(double i_mag,
        double j_mag, double theta_i, double theta_ij,
        double *xscale, double *xskew, double *yskew, double *yscale) ;
 
void rt_raster_set_srid(rt_raster raster, int32_t srid);
 
int32_t rt_raster_get_srid(rt_raster raster);
 
rt_errorstate rt_raster_get_inverse_geotransform_matrix(
        rt_raster raster,
        double *gt, double *igt
);
 
void rt_raster_get_geotransform_matrix(rt_raster raster,
        double *gt);
 
void rt_raster_set_geotransform_matrix(rt_raster raster,
        double *gt);
 
rt_errorstate rt_raster_cell_to_geopoint(
        rt_raster raster,
        double xr, double yr,
        double* xw, double* yw,
        double *gt
);
 
rt_errorstate rt_raster_geopoint_to_cell(
        rt_raster raster,
        double xw, double yw,
        double *xr, double *yr,
        double *igt
);
 
rt_errorstate rt_raster_get_convex_hull(rt_raster raster, LWGEOM **hull);
 
rt_errorstate rt_raster_get_envelope(rt_raster raster, rt_envelope *env);
 
rt_errorstate rt_raster_get_envelope_geom(rt_raster raster, LWGEOM **env);
 
rt_errorstate rt_raster_get_perimeter(
        rt_raster raster, int nband,
        LWGEOM **perimeter
);
 
/*
 * Compute skewed extent that covers unskewed extent.
 *
 * @param envelope : unskewed extent of type rt_envelope
 * @param skew : pointer to 2-element array (x, y) of skew
 * @param scale : pointer to 2-element array (x, y) of scale
 * @param tolerance : value between 0 and 1 where the smaller the tolerance
 * results in an extent approaching the "minimum" skewed extent.
 * If value <= 0, tolerance = 0.1.  If value > 1, tolerance = 1.
 *
 * @return skewed raster who's extent covers unskewed extent, NULL on error
 */
rt_raster
rt_raster_compute_skewed_raster(
        rt_envelope extent,
        double *skew,
        double *scale,
        double tolerance
);
 
LWPOLY* rt_raster_pixel_as_polygon(rt_raster raster, int x, int y);
 
rt_errorstate rt_raster_surface(rt_raster raster, int nband, LWMPOLY **surface);
 
rt_geomval
rt_raster_gdal_polygonize(
        rt_raster raster, int nband,
        int exclude_nodata_value,
        int * pnElements
);
 
void* rt_raster_serialize(rt_raster raster);
 
rt_raster rt_raster_deserialize(void* serialized, int header_only);
 
int rt_raster_is_empty(rt_raster raster);
 
int rt_raster_has_band(rt_raster raster, int nband);
 
int rt_raster_copy_band(
        rt_raster torast, rt_raster fromrast,
        int fromindex, int toindex
);
 
rt_raster rt_raster_from_band(rt_raster raster, uint32_t *bandNums,
        int count);
 
rt_band rt_raster_replace_band(rt_raster raster, rt_band band,
        int index);
 
rt_raster rt_raster_clone(rt_raster raster, uint8_t deep);
 
uint8_t *rt_raster_to_gdal(rt_raster raster, const char *srs,
        char *format, char **options, uint64_t *gdalsize);
 
rt_gdaldriver rt_raster_gdal_drivers(uint32_t *drv_count, uint8_t cancc);
 
GDALDatasetH rt_raster_to_gdal_mem(
        rt_raster raster,
        const char *srs,
        uint32_t *bandNums,
        int *excludeNodataValues,
        int count,
        GDALDriverH *rtn_drv, int *destroy_rtn_drv
);
 
rt_raster rt_raster_from_gdal_dataset(GDALDatasetH ds);
 
rt_raster rt_raster_gdal_warp(
        rt_raster raster,
        const char *src_srs, const char *dst_srs,
        double *scale_x, double *scale_y,
        int *width, int *height,
        double *ul_xw, double *ul_yw,
        double *grid_xw, double *grid_yw,
        double *skew_x, double *skew_y,
        GDALResampleAlg resample_alg, double max_err);
 
rt_raster rt_raster_gdal_rasterize(const unsigned char *wkb,
        uint32_t wkb_len, const char *srs,
        uint32_t num_bands, rt_pixtype *pixtype,
        double *init, double *value,
        double *nodata, uint8_t *hasnodata,
        int *width, int *height,
        double *scale_x, double *scale_y,
        double *ul_xw, double *ul_yw,
        double *grid_xw, double *grid_yw,
        double *skew_x, double *skew_y,
        char **options
);
 
rt_errorstate rt_raster_intersects(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        int *intersects
);
 
rt_errorstate rt_raster_overlaps(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        int *overlaps
);
 
rt_errorstate rt_raster_contains(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        int *contains
);
 
rt_errorstate rt_raster_contains_properly(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        int *contains
);
 
rt_errorstate rt_raster_touches(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        int *touches
);
 
rt_errorstate rt_raster_covers(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        int *covers
);
 
rt_errorstate rt_raster_coveredby(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        int *coveredby
);
 
rt_errorstate rt_raster_within_distance(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        double distance,
        int *dwithin
);
 
rt_errorstate rt_raster_fully_within_distance(
        rt_raster rast1, int nband1,
        rt_raster rast2, int nband2,
        double distance,
        int *dfwithin
);
 
/*
 * Return ES_ERROR if error occurred in function.
 * Paramter aligned returns non-zero if two rasters are aligned
 *
 * @param rast1 : the first raster for alignment test
 * @param rast2 : the second raster for alignment test
 * @param *aligned : non-zero value if the two rasters are aligned
 * @param *reason : reason why rasters are not aligned
 *
 * @return ES_NONE if success, ES_ERROR if error
 */
rt_errorstate rt_raster_same_alignment(
        rt_raster rast1,
        rt_raster rast2,
        int *aligned, char **reason
);
 
/*
 * Return raster of computed extent specified extenttype applied
 * on two input rasters.  The raster returned should be freed by
 * the caller
 *
 * @param rast1 : the first raster
 * @param rast2 : the second raster
 * @param extenttype : type of extent for the output raster
 * @param *rtnraster : raster of computed extent
 * @param *offset : 4-element array indicating the X,Y offsets
 * for each raster. 0,1 for rast1 X,Y. 2,3 for rast2 X,Y.
 *
 * @return ES_NONE if success, ES_ERROR if error
 */
rt_errorstate
rt_raster_from_two_rasters(
        rt_raster rast1, rt_raster rast2,
        rt_extenttype extenttype,
        rt_raster *rtnraster, double *offset
);
 
rt_errorstate
rt_raster_iterator(
        rt_iterator itrset, uint16_t itrcount,
        rt_extenttype extenttype, rt_raster customextent,
        rt_pixtype pixtype,
        uint8_t hasnodata, double nodataval,
        uint16_t distancex, uint16_t distancey,
        rt_mask mask,
        void *userarg,
        int (*callback)(
                rt_iterator_arg arg,
                void *userarg,
                double *value,
                int *nodata
        ),
        rt_raster *rtnraster
);
 
rt_raster rt_raster_colormap(
        rt_raster raster, int nband,
        rt_colormap colormap
);
 
/*- utilities -------------------------------------------------------*/
 
/*
 * rt_core memory functions
 */
extern void *rtalloc(size_t size);
extern void *rtrealloc(void *mem, size_t size);
extern void rtdealloc(void *mem);
 
/*
 * GDAL driver flags
 */
 
#define GDAL_ENABLE_ALL "ENABLE_ALL"
#define GDAL_DISABLE_ALL "DISABLE_ALL"
#define GDAL_VSICURL "VSICURL"
 
/*
 * Set of functions to clamp double to int of different size
 */
 
#if !defined(POSTGIS_RASTER_WARN_ON_TRUNCATION)
#define POSTGIS_RASTER_WARN_ON_TRUNCATION 0
#endif
 
#define POSTGIS_RT_1BBMAX 1
#define POSTGIS_RT_2BUIMAX 3
#define POSTGIS_RT_4BUIMAX 15
 
uint8_t
rt_util_clamp_to_1BB(double value);
 
uint8_t
rt_util_clamp_to_2BUI(double value);
 
uint8_t
rt_util_clamp_to_4BUI(double value);
 
int8_t
rt_util_clamp_to_8BSI(double value);
 
uint8_t
rt_util_clamp_to_8BUI(double value);
 
int16_t
rt_util_clamp_to_16BSI(double value);
 
uint16_t
rt_util_clamp_to_16BUI(double value);
 
int32_t
rt_util_clamp_to_32BSI(double value);
 
uint32_t
rt_util_clamp_to_32BUI(double value);
 
float
rt_util_clamp_to_32F(double value);
 
int
rt_util_dbl_trunc_warning(
        double initialvalue,
        int32_t checkvalint, uint32_t checkvaluint,
        float checkvalfloat, double checkvaldouble,
        rt_pixtype pixtype
);
 
GDALResampleAlg
rt_util_gdal_resample_alg(const char *algname);
 
GDALDataType
rt_util_pixtype_to_gdal_datatype(rt_pixtype pt);
 
rt_pixtype
rt_util_gdal_datatype_to_pixtype(GDALDataType gdt);
 
/*
        get GDAL runtime version information
*/
const char*
rt_util_gdal_version(const char *request);
 
/*
        computed extent type from c string
*/
rt_extenttype
rt_util_extent_type(const char *name);
 
/*
        convert the spatial reference string from a GDAL recognized format to either WKT or Proj4
*/
char*
rt_util_gdal_convert_sr(const char *srs, int proj4);
 
/*
        is the spatial reference string supported by GDAL
*/
int
rt_util_gdal_supported_sr(const char *srs);
 
rt_errorstate
rt_util_gdal_sr_auth_info(GDALDatasetH hds, char **authname, char **authcode);
 
/*
        is GDAL configured correctly?
*/
int
rt_util_gdal_configured(void);
 
/*
        register all GDAL drivers
*/
int
rt_util_gdal_register_all(int force_register_all);
 
/*
        is the driver registered?
*/
int
rt_util_gdal_driver_registered(const char *drv);
 
/*
        wrapper for GDALOpen and GDALOpenShared
*/
GDALDatasetH
rt_util_gdal_open(const char *fn, GDALAccess fn_access, int shared);
 
void
rt_util_from_ogr_envelope(
        OGREnvelope     env,
        rt_envelope *ext
);
 
void
rt_util_to_ogr_envelope(
        rt_envelope ext,
        OGREnvelope     *env
);
 
LWPOLY *
rt_util_envelope_to_lwpoly(
        rt_envelope ext
);
 
int
rt_util_same_geotransform_matrix(
        double *gt1,
        double *gt2
);
 
/* coordinates in RGB and HSV are floating point values between 0 and 1 */
rt_errorstate
rt_util_rgb_to_hsv(
        double rgb[3],
        double hsv[3]
);
 
/* coordinates in RGB and HSV are floating point values between 0 and 1 */
rt_errorstate
rt_util_hsv_to_rgb(
        double hsv[3],
        double rgb[3]
);
 
/*
        helper macros for consistent floating point equality checks.
        NaN equals NaN for NODATA support.
*/
#define FLT_NEQ(x, y) ((x != y) && !(isnan(x) && isnan(y)) && (fabs(x - y) > FLT_EPSILON))
#define FLT_EQ(x, y) ((x == y) || (isnan(x) && isnan(y)) || (fabs(x - y) <= FLT_EPSILON))
#define DBL_NEQ(x, y) ((x != y) && !(isnan(x) && isnan(y)) && (fabs(x - y) > DBL_EPSILON))
#define DBL_EQ(x, y) ((x == y) || (isnan(x) && isnan(y)) || (fabs(x - y) <= DBL_EPSILON))
 
/*
        helper macro for symmetrical rounding
*/
#define ROUND(x, y) (((x > 0.0) ? floor((x * pow(10, y) + 0.5)) : ceil((x * pow(10, y) - 0.5))) / pow(10, y))
 
struct rt_raster_serialized_t {
    /*---[ 8 byte boundary ]---{ */
    uint32_t size; /* required by postgresql: 4 bytes */
    uint16_t version; /* format version (this is version 0): 2 bytes */
    uint16_t numBands; /* Number of bands: 2 bytes */
 
    /* }---[ 8 byte boundary ]---{ */
    double scaleX; /* pixel width: 8 bytes */
 
    /* }---[ 8 byte boundary ]---{ */
    double scaleY; /* pixel height: 8 bytes */
 
    /* }---[ 8 byte boundary ]---{ */
    double ipX; /* insertion point X: 8 bytes */
 
    /* }---[ 8 byte boundary ]---{ */
    double ipY; /* insertion point Y: 8 bytes */
 
    /* }---[ 8 byte boundary ]---{ */
    double skewX; /* skew about the X axis: 8 bytes */
 
    /* }---[ 8 byte boundary ]---{ */
    double skewY; /* skew about the Y axis: 8 bytes */
 
    /* }---[ 8 byte boundary ]--- */
    int32_t srid; /* Spatial reference id: 4 bytes */
    uint16_t width; /* pixel columns: 2 bytes */
    uint16_t height; /* pixel rows: 2 bytes */
};
 
/* NOTE: the initial part of this structure matches the layout
 *       of data in the serialized form version 0, starting
 *       from the numBands element
 */
struct rt_raster_t {
    uint32_t size;
    uint16_t version;
 
    /* Number of bands, all share the same dimension
     * and georeference */
    uint16_t numBands;
 
    /* Georeference (in projection units) */
    double scaleX; /* pixel width */
    double scaleY; /* pixel height */
    double ipX; /* geo x ordinate of the corner of upper-left pixel */
    double ipY; /* geo y ordinate of the corner of bottom-right pixel */
    double skewX; /* skew about the X axis*/
    double skewY; /* skew about the Y axis */
 
    int32_t srid; /* spatial reference id */
    uint16_t width; /* pixel columns - max 65535 */
    uint16_t height; /* pixel rows - max 65535 */
    rt_band *bands; /* actual bands */
 
};
 
struct rt_extband_t {
    uint8_t bandNum; /* 0-based */
    char* path; /* internally owned */
                void *mem; /* loaded external band data, internally owned */
};
 
struct rt_band_t {
    rt_pixtype pixtype;
    int32_t offline;
    uint16_t width;
    uint16_t height;
    int32_t hasnodata; /* a flag indicating if this band contains nodata values */
    int32_t isnodata;   /* a flag indicating if this band is filled only with
                           nodata values. flag CANNOT be TRUE if hasnodata is FALSE */
    double nodataval; /* int will be converted ... */
    int8_t ownsdata; /* 0, externally owned. 1, internally owned. only applies to data.mem */
 
                rt_raster raster; /* reference to parent raster */
 
    union {
        void* mem; /* actual data, externally owned */
        struct rt_extband_t offline;
    } data;
 
};
 
struct rt_pixel_t {
        int x; /* column */
        int y; /* line */
 
        uint8_t nodata;
        double value;
 
        LWGEOM *geom;
};
 
struct rt_mask_t {
  uint16_t dimx;
  uint16_t dimy;
  double **values;
  int **nodata;
  int weighted; /* 0 if not weighted values 1 if weighted values */
};
 
/* polygon as LWPOLY with associated value */
struct rt_geomval_t {
        LWPOLY *geom;
        double val;
};
 
/* summary stats of specified band */
struct rt_bandstats_t {
        double sample;
        uint32_t count;
 
        double min;
        double max;
        double sum;
        double mean;
        double stddev;
 
        double *values;
        int sorted; /* flag indicating that values is sorted ascending by value */
};
 
/* histogram bin(s) of specified band */
struct rt_histogram_t {
        uint32_t count;
        double percent;
 
        double min;
        double max;
 
        int inc_min;
        int inc_max;
};
 
/* quantile(s) of the specified band */
struct rt_quantile_t {
        double quantile;
        double value;
        uint32_t has_value;
};
 
/* listed-list structures for rt_band_get_quantiles_stream */
struct quantile_llist {
        uint8_t algeq; /* AL-GEQ (1) or AL-GT (0) */
        double quantile;
        uint64_t tau; /* position in sequence */
 
        struct quantile_llist_element *head; /* H index 0 */
        struct quantile_llist_element *tail; /* H index last */
        uint32_t count; /* # of elements in H */
 
        /* faster access to elements at specific intervals */
        struct quantile_llist_index *index;
        uint32_t index_max; /* max # of elements in index */
 
        uint64_t sum1; /* N1H */
        uint64_t sum2; /* N2H */
};
 
struct quantile_llist_element {
        double value;
        uint32_t count;
 
        struct quantile_llist_element *prev;
        struct quantile_llist_element *next;
};
 
struct quantile_llist_index {
        struct quantile_llist_element *element;
        uint32_t index;
};
 
/* number of times a value occurs */
struct rt_valuecount_t {
        double value;
        uint32_t count;
        double percent;
};
 
/* reclassification expression */
struct rt_reclassexpr_t {
        struct rt_reclassrange {
                double min;
                double max;
                int inc_min; /* include min */
                int inc_max; /* include max */
                int exc_min; /* exceed min */
                int exc_max; /* exceed max */
        } src, dst;
};
 
/* raster iterator */
struct rt_iterator_t {
        rt_raster raster;
        uint16_t nband; /* 0-based */
        uint8_t nbnodata; /* no band = treat as NODATA  */
};
 
/* callback argument from raster iterator */
struct rt_iterator_arg_t {
        /* # of rasters, Z-axis */
        uint16_t rasters;
        /* # of rows, Y-axis */
        uint32_t rows;
        /* # of columns, X-axis */
        uint32_t columns;
 
        /* axis order: Z,X,Y */
        /* individual pixel values */
        double ***values;
        /* 0,1 value of nodata flag */
        int ***nodata;
 
        /* X,Y of pixel from each input raster */
        int **src_pixel;
 
        /* X,Y of pixel from output raster */
        int dst_pixel[2];
};
 
/* gdal driver information */
struct rt_gdaldriver_t {
        int idx;
        char *short_name;
        char *long_name;
        char *create_options;
        uint8_t can_read;
        uint8_t can_write;
};
 
/* raster colormap entry */
struct rt_colormap_entry_t {
        int isnodata;
        double value;
        uint8_t color[4]; /* RGBA */
};
 
struct rt_colormap_t {
        enum {
                CM_INTERPOLATE,
                CM_EXACT,
                CM_NEAREST
        } method;
 
        int ncolor;
        uint16_t nentry;
        rt_colormap_entry entry;
};
 
#endif /* LIBRTCORE_H_INCLUDED */