source: trunk/raster/rt_core/rt_api.h @ 9559

Last change on this file since 9559 was 9559, checked in by dustymugs, 4 years ago

Merge branch 'master' into HEAD

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 50.7 KB
Line 
1/*
2 * $Id: rt_api.h 9559 2012-03-27 19:25:23Z dustymugs $
3 *
4 * WKTRaster - Raster Types for PostGIS
5 * http://www.postgis.org/support/wiki/index.php?WKTRasterHomePage
6 *
7 * Copyright (C) 2011-2012 Regents of the University of California
8 *   <bkpark@ucdavis.edu>
9 * Copyright (C) 2010-2011 Jorge Arevalo <jorge.arevalo@deimos-space.com>
10 * Copyright (C) 2010-2011 David Zwarg <dzwarg@azavea.com>
11 * Copyright (C) 2009-2011 Pierre Racine <pierre.racine@sbf.ulaval.ca>
12 * Copyright (C) 2009-2011 Mateusz Loskot <mateusz@loskot.net>
13 * Copyright (C) 2008-2009 Sandro Santilli <strk@keybit.net>
14 *
15 * This program is free software; you can redistribute it and/or modify
16 * it under the terms of the GNU General Public License as published by
17 * the Free Software Foundation; either version 3 of the License, or
18 * (at your option) any later version.
19 *
20 * This program is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23 * GNU General Public License for more details.
24 *
25 * You should have received a copy of the GNU General Public License
26 * along with this program; if not, write to the Free Software
27 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
28 *
29 */
30
31#ifndef RT_API_H_INCLUDED
32#define RT_API_H_INCLUDED
33
34/* define the systems */
35#if defined(__linux__)  /* (predefined) */
36#if !defined(LINUX)
37#define LINUX
38#endif
39#if !defined(UNIX)
40#define UNIX        /* make sure this is defined */
41#endif
42#endif
43
44
45#if defined(__FreeBSD__) || defined(__OpenBSD__)    /* seems to work like Linux... */
46#if !defined(LINUX)
47#define LINUX
48#endif
49#if !defined(UNIX)
50#define UNIX        /* make sure this is defined */
51#endif
52#endif
53
54#if defined(__MSDOS__)
55#if !defined(MSDOS)
56#define MSDOS       /* make sure this is defined */
57#endif
58#endif
59
60#if defined(__WIN32__) || defined(__NT__) || defined(_WIN32)
61#if !defined(WIN32)
62#define WIN32
63#endif
64#if defined(__BORLANDC__) && defined(MSDOS) /* Borland always defines MSDOS */
65#undef  MSDOS
66#endif
67#endif
68
69#if defined(__APPLE__)
70#if !defined(UNIX)
71#define UNIX
72#endif
73#endif
74
75#if defined(sun) || defined(__sun)
76#if !defined(UNIX)
77#define UNIX
78#endif
79#endif
80
81/* if we are in Unix define stricmp to be strcasecmp and strnicmp to */
82/* be strncasecmp. I'm not sure if all Unices have these, but Linux */
83/* does. */
84#if defined(UNIX)
85#if !defined(HAVE_STRICMP)
86#define stricmp     strcasecmp
87#endif
88#if !defined(HAVE_STRNICMP)
89#define strnicmp    strncasecmp
90#endif
91#endif
92
93#include <stdlib.h> /* For size_t, srand and rand */
94#include <stdint.h> /* For C99 int types */
95#include <float.h> /* for FLT_EPSILON, DBL_EPSILON and float type limits */
96#include <limits.h> /* for integer type limits */
97#include <math.h>
98
99#include "lwgeom_geos.h"
100#include "liblwgeom.h"
101
102#include "gdal_alg.h"
103#include "gdal_frmts.h"
104#include "gdal.h"
105#include "gdalwarper.h"
106#include "ogr_api.h"
107#include "ogr_srs_api.h"
108#include "cpl_vsi.h"
109#include "cpl_conv.h"
110#include "../../postgis_config.h"
111#include "../raster_config.h"
112
113/**
114 * @file rt_api.h
115 *
116 * This library is the generic raster handling section of PostGIS. The raster
117 * objects, constructors, destructors, and a set of spatial processing functions
118 * are implemented here.
119 *
120 * The library is designed for use in non-PostGIS applications if necessary. The
121 * units tests at test/core (and the future loader/dumper programs) are examples
122 * of non-PostGIS applications using rt_core.
123 *
124 * Programs using this library should set up the default memory managers and error
125 * handlers by implementing an rt_init_allocators() function, which can be as
126 * a wrapper around the rt_install_default_allocators() function if you want
127 * no special handling for memory management and error reporting.
128 *
129 **/
130
131/**
132 * Types definitions
133 */
134typedef struct rt_raster_t* rt_raster;
135typedef struct rt_band_t* rt_band;
136typedef struct rt_geomval_t* rt_geomval;
137typedef struct rt_bandstats_t* rt_bandstats;
138typedef struct rt_histogram_t* rt_histogram;
139typedef struct rt_quantile_t* rt_quantile;
140typedef struct rt_valuecount_t* rt_valuecount;
141typedef struct rt_gdaldriver_t* rt_gdaldriver;
142typedef struct rt_reclassexpr_t* rt_reclassexpr;
143
144/* envelope information */
145typedef struct {
146        double MinX;
147        double MaxX;
148        double MinY;
149        double MaxY;
150
151        double UpperLeftX;
152        double UpperLeftY;
153} rt_envelope;
154
155/**
156 * Enum definitions
157 */
158/* Pixel types */
159typedef enum {
160    PT_1BB=0,     /* 1-bit boolean            */
161    PT_2BUI=1,    /* 2-bit unsigned integer   */
162    PT_4BUI=2,    /* 4-bit unsigned integer   */
163    PT_8BSI=3,    /* 8-bit signed integer     */
164    PT_8BUI=4,    /* 8-bit unsigned integer   */
165    PT_16BSI=5,   /* 16-bit signed integer    */
166    PT_16BUI=6,   /* 16-bit unsigned integer  */
167    PT_32BSI=7,   /* 32-bit signed integer    */
168    PT_32BUI=8,   /* 32-bit unsigned integer  */
169    PT_32BF=10,   /* 32-bit float             */
170    PT_64BF=11,   /* 64-bit float             */
171    PT_END=13
172} rt_pixtype;
173
174typedef enum {
175        ET_INTERSECTION = 0,
176        ET_UNION,
177        ET_FIRST,
178        ET_SECOND
179} rt_extenttype;
180
181/**
182* Global functions for memory/logging handlers.
183*/
184typedef void* (*rt_allocator)(size_t size);
185typedef void* (*rt_reallocator)(void *mem, size_t size);
186typedef void  (*rt_deallocator)(void *mem);
187typedef void  (*rt_message_handler)(const char* string, va_list ap);
188
189/****************************************************************************
190 * Functions that must be implemented for the raster core function's caller
191 * (for example: rt_pg functions, test functions, future loader/exporter)
192 ****************************************************************************/
193
194/**
195 * Supply the memory management and error handling functions you want your
196 * application to use
197 */
198extern void rt_init_allocators(void);
199
200/*********************************************************************/
201
202
203/*******************************************************************
204 * Functions that may be used by the raster core function's caller
205 * (for example: rt_pg functions, test functions, future loader/exporter)
206 *******************************************************************/
207/**
208 * Apply the default memory management (malloc() and free()) and error handlers.
209 * Called inside rt_init_allocators() generally.
210 */
211extern void rt_install_default_allocators(void);
212
213
214/**
215 * Wrappers used for managing memory. They simply call the functions defined by
216 * the caller
217 **/
218extern void* rtalloc(size_t size);
219extern void* rtrealloc(void* mem, size_t size);
220extern void rtdealloc(void* mem);
221
222/******************************************************************/
223
224
225/**
226 * Wrappers used for reporting errors and info.
227 **/
228void rterror(const char *fmt, ...);
229void rtinfo(const char *fmt, ...);
230void rtwarn(const char *fmt, ...);
231
232
233/**
234* The default memory/logging handlers installed by lwgeom_install_default_allocators()
235*/
236void * default_rt_allocator(size_t size);
237void * default_rt_reallocator(void * mem, size_t size);
238void default_rt_deallocator(void * mem);
239void default_rt_error_handler(const char * fmt, va_list ap);
240void default_rt_warning_handler(const char * fmt, va_list ap);
241void default_rt_info_handler(const char * fmt, va_list ap);
242
243
244/* Debugging macros */
245#if POSTGIS_DEBUG_LEVEL > 0
246
247/* Display a simple message at NOTICE level */
248#define RASTER_DEBUG(level, msg) \
249    do { \
250        if (POSTGIS_DEBUG_LEVEL >= level) \
251            rtinfo("[%s:%s:%d] " msg, __FILE__, __func__, __LINE__); \
252    } while (0);
253
254/* Display a formatted message at NOTICE level (like printf, with variadic arguments) */
255#define RASTER_DEBUGF(level, msg, ...) \
256    do { \
257        if (POSTGIS_DEBUG_LEVEL >= level) \
258            rtinfo("[%s:%s:%d] " msg, __FILE__, __func__, __LINE__, __VA_ARGS__); \
259    } while (0);
260
261#else
262
263/* Empty prototype that can be optimised away by the compiler for non-debug builds */
264#define RASTER_DEBUG(level, msg) \
265    ((void) 0)
266
267/* Empty prototype that can be optimised away by the compiler for non-debug builds */
268#define RASTER_DEBUGF(level, msg, ...) \
269    ((void) 0)
270
271#endif
272
273/*- memory context -------------------------------------------------------*/
274
275void rt_set_handlers(rt_allocator allocator, rt_reallocator reallocator,
276        rt_deallocator deallocator, rt_message_handler error_handler,
277        rt_message_handler info_handler, rt_message_handler warning_handler);
278
279
280
281/*- rt_pixtype --------------------------------------------------------*/
282
283/**
284 * Return size in bytes of a value in the given pixtype
285 */
286int rt_pixtype_size(rt_pixtype pixtype);
287
288/**
289 * Return alignment requirements for data in the given pixel type.
290 * Fast access to pixel values of this type must be aligned to as
291 * many bytes as returned by this function.
292 */
293int rt_pixtype_alignment(rt_pixtype pixtype);
294
295/* Return human-readable name of pixel type */
296const char* rt_pixtype_name(rt_pixtype pixtype);
297
298/* Return pixel type index from human-readable name */
299rt_pixtype rt_pixtype_index_from_name(const char* pixname);
300
301/**
302 * Return minimum value possible for pixel type
303 *
304 * @param pixtype: the pixel type to get minimum possible value for
305 *
306 * @return the minimum possible value for the pixel type.
307 */
308double rt_pixtype_get_min_value(rt_pixtype pixtype);
309
310/*- rt_band ----------------------------------------------------------*/
311
312/**
313 * Create an in-db rt_band with no data
314 *
315 * @param width     : number of pixel columns
316 * @param height    : number of pixel rows
317 * @param pixtype   : pixel type for the band
318 * @param hasnodata : indicates if the band has nodata value
319 * @param nodataval : the nodata value, will be appropriately
320 *                    truncated to fit the pixtype size.
321 * @param data      : pointer to actual band data, required to
322 *                    be aligned accordingly to
323 *                    rt_pixtype_aligment(pixtype) and big enough
324 *                    to hold raster width*height values.
325 *                    Data will NOT be copied, ownership is left
326 *                    to caller which is responsible to keep it
327 *                    allocated for the whole lifetime of the returned
328 *                    rt_band.
329 *
330 * @return an rt_band, or 0 on failure
331 */
332rt_band rt_band_new_inline(
333        uint16_t width, uint16_t height,
334        rt_pixtype pixtype,
335        uint32_t hasnodata, double nodataval,
336        uint8_t* data
337);
338
339/**
340 * Create an out-db rt_band
341 *
342 * @param width     : number of pixel columns
343 * @param height    : number of pixel rows
344 * @param pixtype   : pixel type for the band
345 * @param hasnodata : indicates if the band has nodata value
346 * @param nodataval : the nodata value, will be appropriately
347 *                    truncated to fit the pixtype size.
348 * @param bandNum   : 0-based band number in the external file
349 *                    to associate this band with.
350 * @param path      : NULL-terminated path string pointing to the file
351 *                    containing band data. The string will NOT be
352 *                    copied, ownership is left to caller which is
353 *                    responsible to keep it allocated for the whole
354 *                    lifetime of the returned rt_band.
355 *
356 * @return an rt_band, or 0 on failure
357 */
358rt_band rt_band_new_offline(
359        uint16_t width, uint16_t height,
360        rt_pixtype pixtype,
361        uint32_t hasnodata, double nodataval,
362        uint8_t bandNum, const char* path
363);
364
365/**
366 * Create a new band duplicated from source band.  Memory is allocated
367 * for band path (if band is offline) or band data (if band is online).
368 * The caller is responsible for freeing the memory when the returned
369 * rt_band is destroyed.
370 *
371 * @param : the band to duplicate
372 *
373 * @return an rt_band or NULL on failure
374 */
375rt_band rt_band_duplicate(rt_band band);
376
377/**
378 * Return non-zero if the given band data is on
379 * the filesystem.
380 *
381 * @param band : the band
382 *
383 * @return non-zero if the given band data is on
384 *         the filesystem.
385 */
386int rt_band_is_offline(rt_band band);
387
388/**
389 * Return bands' external path (only valid when rt_band_is_offline
390 * returns non-zero).
391 */
392const char* rt_band_get_ext_path(rt_band band);
393
394/**
395 * Return bands' external band number (only valid when
396 * rt_band_is_offline returns non-zero).
397 */
398uint8_t rt_band_get_ext_band_num(rt_band band);
399
400/* Get pixeltype of this band */
401rt_pixtype rt_band_get_pixtype(rt_band band);
402
403/* Get width of this band */
404uint16_t rt_band_get_width(rt_band band);
405
406/* Get height of this band */
407uint16_t rt_band_get_height(rt_band band);
408
409/**
410        * Get pointer to raster band data
411        *
412        * @param band : the band who's data to get
413        *
414        * @return void pointer to band data
415        */
416void* rt_band_get_data(rt_band band);
417
418/**
419        * Load offline band's data.  Loaded data is internally owned
420        * and should not be released by the caller.  Data will be
421        * released when band is destroyed with rt_band_destroy().
422        *
423        * @param band : the band who's data to get
424        *
425        * @return 0 if success, non-zero if failure
426        */
427int rt_band_load_offline_data(rt_band band);
428
429/**
430 * Destroy a raster band
431 *
432 * @param band : the band to destroy
433 */
434void rt_band_destroy(rt_band band);
435
436/**
437 * Get hasnodata flag value
438 *
439 * @param band : the band on which to check the hasnodata flag
440 *
441 * @return the hasnodata flag.
442 */
443int rt_band_get_hasnodata_flag(rt_band band);
444
445/**
446 * Set hasnodata flag value
447 * @param band : the band on which to set the hasnodata flag
448 * @param flag : the new hasnodata flag value. Must be 1 or 0.
449 */
450void rt_band_set_hasnodata_flag(rt_band band, int flag);
451
452/**
453 * Set isnodata flag value
454 *
455 * @param band : the band on which to set the isnodata flag
456 * @param flag : the new isnodata flag value. Must be 1 or 0
457 */
458void rt_band_set_isnodata_flag(rt_band band, int flag);
459
460/**
461 * Get hasnodata flag value
462 * @param band : the band on which to check the isnodata flag
463 * @return the hasnodata flag.
464 */
465int rt_band_get_isnodata_flag(rt_band band);
466
467/**
468 * Set nodata value
469 *
470 * @param band : the band to set nodata value to
471 * @param val : the nodata value
472 *
473 * @return 0 on success, -1 on error (invalid pixel type),
474 *   1 on truncation/clamping/converting.
475 */
476int rt_band_set_nodata(rt_band band, double val);
477
478/**
479 * Get nodata value
480 *
481 * @param band : the band to set nodata value to
482 *
483 * @return nodata value
484 */
485double rt_band_get_nodata(rt_band band);
486
487/**
488 * Set values of multiple pixels.  Unlike rt_band_set_pixel,
489 * values in vals are expected to be of the band's pixel type
490 * as this function uses memcpy.
491 *
492 * @param band : the band to set value to
493 * @param x : X coordinate (0-based)
494 * @param y : Y coordinate (0-based)
495 * @param vals : the pixel values to apply
496 * @param len : # of elements in vals
497 *
498 * @return 1 on success, 0 on error
499 */
500int rt_band_set_pixel_line(
501        rt_band band,
502        uint16_t x, uint16_t y,
503        void *vals, uint16_t len
504);
505
506/**
507 * Set single pixel's value
508 *
509 * @param band : the band to set value to
510 * @param x : x ordinate (0-based)
511 * @param y : y ordinate (0-based)
512 * @param val : the pixel value
513 *
514 * @return 0 on success, -1 on error (value out of valid range),
515 *   1 on truncation/clamping/converting.
516 */
517int rt_band_set_pixel(rt_band band,
518                      uint16_t x, uint16_t y, double val);
519
520/**
521 * Get pixel value
522 *
523 * @param band : the band to get pixel value from
524 * @param x : x ordinate (0-based)
525 * @param y : x ordinate (0-based)
526 * @param *result: result if there is a value
527 *
528 * @return 0 on success, -1 on error (value out of valid range).
529 */
530int rt_band_get_pixel(rt_band band,
531                         uint16_t x, uint16_t y, double *result );
532
533
534/**
535 * Returns the minimal possible value for the band according to the pixel type.
536 * @param band: the band to get info from
537 * @return the minimal possible value for the band.
538 */
539double rt_band_get_min_value(rt_band band);
540
541/**
542 * Returns TRUE if the band is only nodata values
543 * @param band: the band to get info from
544 * @return TRUE if the band is only nodata values, FALSE otherwise
545 */
546int rt_band_is_nodata(rt_band band);
547
548/**
549 * Returns TRUE if the band is only nodata values
550 * @param band: the band to get info from
551 * @return TRUE if the band is only nodata values, FALSE otherwise
552 */
553int rt_band_check_is_nodata(rt_band band);
554
555/**
556 * Compare clamped value to band's clamped NODATA value
557 *
558 * @param band: the band whose NODATA value will be used for comparison
559 * @param val: the value to compare to the NODATA value
560 *
561 * @return 1 if clamped value is clamped NODATA
562 *         0 if clamped value is NOT clamped NODATA
563 *         -1 otherwise
564 */
565int rt_band_clamped_value_is_nodata(rt_band band, double val);
566
567/**
568 * Correct value when clamped value is clamped NODATA value.  Correction
569 * does NOT occur if unclamped value is exactly unclamped NODATA value.
570 *
571 * @param band: the band whose NODATA value will be used for comparison
572 * @param val: the value to compare to the NODATA value and correct
573 * @param newval: pointer to corrected value
574 *
575 * @return 0 on error, 1 if corrected, -1 otherwise
576 */
577int
578rt_band_corrected_clamped_value(rt_band band, double val, double *newval);
579
580/**
581 * Compute summary statistics for a band
582 *
583 * @param band: the band to query for summary stats
584 * @param exclude_nodata_value: if non-zero, ignore nodata values
585 * @param sample: percentage of pixels to sample
586 * @param inc_vals: flag to include values in return struct
587 * @param cK: number of pixels counted thus far in coverage
588 * @param cM: M component of 1-pass stddev for coverage
589 * @param cQ: Q component of 1-pass stddev for coverage
590 *
591 * @return the summary statistics for a band
592 */
593rt_bandstats rt_band_get_summary_stats(rt_band band, int exclude_nodata_value,
594        double sample, int inc_vals, uint64_t *cK, double *cM, double *cQ);
595       
596/**
597 * Count the distribution of data
598 *
599 * @param stats: a populated stats struct for processing
600 * @param bin_count: the number of bins to group the data by
601 * @param bin_width: the width of each bin as an array
602 * @param bin_width_count: number of values in bin_width
603 * @param right: evaluate bins by (a,b] rather than default [a,b)
604 * @param min: user-defined minimum value of the histogram
605 *   a value less than the minimum value is not counted in any bins
606 *   if min = max, min and max are not used
607 * @param max: user-defined maximum value of the histogram
608 *   a value greater than the max value is not counted in any bins
609 *   if min = max, min and max are not used
610 * @param rtn_count: set to the number of bins being returned
611 *
612 * @return the histogram of the data
613 */
614rt_histogram rt_band_get_histogram(rt_bandstats stats,
615        int bin_count, double *bin_widths, int bin_widths_count,
616        int right, double min, double max, uint32_t *rtn_count);
617
618/**
619 * Compute the default set of or requested quantiles for a set of data
620 * the quantile formula used is same as Excel and R default method
621 *
622 * @param stats: a populated stats struct for processing
623 * @param quantiles: the quantiles to be computed
624 * @param quantiles_count: the number of quantiles to be computed
625 * @param rtn_count: the number of quantiles being returned
626 *
627 * @return the default set of or requested quantiles for a band
628 */
629rt_quantile rt_band_get_quantiles(rt_bandstats stats,
630        double *quantiles, int quantiles_count, uint32_t *rtn_count);
631
632struct quantile_llist;
633int quantile_llist_destroy(struct quantile_llist **list,
634        uint32_t list_count);
635
636/**
637 * Compute the default set of or requested quantiles for a coverage
638 *
639 * This function is based upon the algorithm described in:
640 *
641 * A One-Pass Space-Efficient Algorithm for Finding Quantiles (1995)
642 *   by Rakesh Agrawal, Arun Swami
643 *   in Proc. 7th Intl. Conf. Management of Data (COMAD-95)
644 *
645 * http://www.almaden.ibm.com/cs/projects/iis/hdb/Publications/papers/comad95.pdf
646 *
647 * In the future, it may be worth exploring algorithms that don't
648 *   require the size of the coverage
649 *
650 * @param band: the band to include in the quantile search
651 * @param exclude_nodata_value: if non-zero, ignore nodata values
652 * @param sample: percentage of pixels to sample
653 * @param cov_count: number of values in coverage
654 * @param qlls: set of quantile_llist structures
655 * @param qlls_count: the number of quantile_llist structures
656 * @param quantiles: the quantiles to be computed
657 *   if bot qlls and quantiles provided, qlls is used
658 * @param quantiles_count: the number of quantiles to be computed
659 * @param rtn_count: the number of quantiles being returned
660 *
661 * @return the default set of or requested quantiles for a band
662 */
663rt_quantile rt_band_get_quantiles_stream(rt_band band,
664        int exclude_nodata_value, double sample,
665        uint64_t cov_count,
666        struct quantile_llist **qlls, uint32_t *qlls_count,
667        double *quantiles, int quantiles_count,
668        uint32_t *rtn_count);
669
670/**
671 * Count the number of times provided value(s) occur in
672 * the band
673 *
674 * @param band: the band to query for minimum and maximum pixel values
675 * @param exclude_nodata_value: if non-zero, ignore nodata values
676 * @param search_values: array of values to count
677 * @param search_values_count: the number of search values
678 * @param roundto: the decimal place to round the values to
679 * @param rtn_total: the number of pixels examined in the band
680 * @param rtn_count: the number of value counts being returned
681 *
682 * @return the number of times the provide value(s) occur
683 */
684rt_valuecount rt_band_get_value_count(rt_band band, int exclude_nodata_value,
685        double *search_values, uint32_t search_values_count,
686        double roundto, uint32_t *rtn_total, uint32_t *rtn_count);
687
688/**
689 * Returns new band with values reclassified
690 *
691 * @param srcband : the band who's values will be reclassified
692 * @param pixtype : pixel type of the new band
693 * @param hasnodata : indicates if the band has a nodata value
694 * @param nodataval : nodata value for the new band
695 * @param exprset : array of rt_reclassexpr structs
696 * @param exprcount : number of elements in expr
697 *
698 * @return a new rt_band or 0 on error
699 */
700rt_band rt_band_reclass(rt_band srcband, rt_pixtype pixtype,
701        uint32_t hasnodata, double nodataval,
702        rt_reclassexpr *exprset, int exprcount);
703
704/*- rt_raster --------------------------------------------------------*/
705
706/**
707 * Construct a raster with given dimensions.
708 *
709 * Transform will be set to identity.
710 * Will contain no bands.
711 *
712 * @param width : number of pixel columns
713 * @param height : number of pixel rows
714 *
715 * @return an rt_raster or 0 if out of memory
716 */
717rt_raster rt_raster_new(uint16_t width, uint16_t height);
718
719/**
720 * Construct an rt_raster from a binary WKB representation
721 *
722 * @param wkb : an octet stream
723 * @param wkbsize : size (in bytes) of the wkb octet stream
724 *
725 * @return an rt_raster or 0 on error (out of memory or
726 *         malformed WKB).
727 *
728 */
729rt_raster rt_raster_from_wkb(const uint8_t* wkb,
730                             uint32_t wkbsize);
731
732/**
733 * Construct an rt_raster from a text HEXWKB representation
734 *
735 * @param hexwkb : an hex-encoded stream
736 * @param hexwkbsize : size (in bytes) of the hexwkb stream
737 *
738 * @return an rt_raster or 0 on error (out of memory or
739 *         malformed WKB).
740 *
741 */
742rt_raster rt_raster_from_hexwkb(const char* hexwkb,
743                             uint32_t hexwkbsize);
744
745/**
746 * Return this raster in WKB form
747 *
748 * @param raster : the raster
749 * @param wkbsize : will be set to the size of returned wkb form
750 */
751uint8_t *rt_raster_to_wkb(rt_raster raster,
752                                    uint32_t *wkbsize);
753
754/**
755 * Return this raster in HEXWKB form (null-terminated hex)
756 *
757 * @param raster : the raster
758 * @param hexwkbsize : will be set to the size of returned wkb form,
759 *                     not including the null termination
760 */
761char *rt_raster_to_hexwkb(rt_raster raster,
762                                    uint32_t *hexwkbsize);
763
764/**
765 * Release memory associated to a raster
766 *
767 * Note that this will not release data
768 * associated to the band themselves (but only
769 * the one associated with the pointers pointing
770 * at them).
771 *
772
773 * @param raster : the raster to destroy
774 */
775void rt_raster_destroy(rt_raster raster);
776
777/* Get number of bands */
778int rt_raster_get_num_bands(rt_raster raster);
779
780/* Return Nth band, or 0 if unavailable */
781rt_band rt_raster_get_band(rt_raster raster, int bandNum);
782
783/* Get number of rows */
784uint16_t rt_raster_get_width(rt_raster raster);
785
786/* Get number of columns */
787uint16_t rt_raster_get_height(rt_raster raster);
788
789/**
790 * Add band data to a raster.
791 *
792 * @param raster : the raster to add a band to
793 * @param band : the band to add, ownership left to caller.
794 *               Band dimensions are required to match with raster ones.
795 * @param index : the position where to insert the new band (0 based)
796 *
797 * @return identifier (position) for the just-added raster, or -1 on error
798 */
799int32_t rt_raster_add_band(rt_raster raster, rt_band band, int index);
800
801/**
802 * Generate a new inline band and add it to a raster.
803 *
804 * @param raster : the raster to add a band to
805 * @param pixtype: the pixel type for the new band
806 * @param initialvalue: initial value for pixels
807 * @param hasnodata: indicates if the band has a nodata value
808 * @param nodatavalue: nodata value for the new band
809 * @param index: position to add the new band in the raster
810 *
811 * @return identifier (position) for the just-added raster, or -1 on error
812 */
813int32_t rt_raster_generate_new_band(rt_raster raster, rt_pixtype pixtype,
814        double initialvalue, uint32_t hasnodata, double nodatavalue, int index);
815
816/**
817 * Set scale in projection units
818 *
819 * @param raster : the raster to set georeference of
820 * @param scaleX : scale X in projection units
821 * @param scaleY : scale Y height in projection units
822 *
823 * NOTE: doesn't recompute offsets
824 */
825void rt_raster_set_scale(rt_raster raster,
826                               double scaleX, double scaleY);
827
828/**
829 * Get scale X in projection units
830 *
831 * @param raster : the raster to get georeference of
832 *
833 * @return scale X in projection units
834 */
835double rt_raster_get_x_scale(rt_raster raster);
836
837/**
838 * Get scale Y in projection units
839 *
840 * @param raster : the raster to get georeference of
841 *
842 * @return scale Y in projection units
843 */
844double rt_raster_get_y_scale(rt_raster raster);
845
846/**
847 * Set insertion points in projection units
848 *
849 * @param raster : the raster to set georeference of
850 * @param x : x ordinate of the upper-left corner of upper-left pixel,
851 *            in projection units
852 * @param y : y ordinate of the upper-left corner of upper-left pixel,
853 *            in projection units
854 */
855void rt_raster_set_offsets(rt_raster raster,
856                           double x, double y);
857
858/**
859 * Get raster x offset, in projection units
860 *
861 * @param raster : the raster to get georeference of
862 *
863 * @return  x ordinate of the upper-left corner of upper-left pixel,
864 *          in projection units
865 */
866double rt_raster_get_x_offset(rt_raster raster);
867
868/**
869 * Get raster y offset, in projection units
870 *
871 * @param raster : the raster to get georeference of
872 *
873 * @return  y ordinate of the upper-left corner of upper-left pixel,
874 *          in projection units
875 */
876double rt_raster_get_y_offset(rt_raster raster);
877
878/**
879 * Set skews about the X and Y axis
880 *
881 * @param raster : the raster to set georeference of
882 * @param skewX : skew about the x axis
883 * @param skewY : skew about the y axis
884 */
885void rt_raster_set_skews(rt_raster raster,
886                             double skewX, double skewY);
887
888/**
889 * Get skew about the X axis
890 *
891 * @param raster : the raster to set georeference of
892 * @return skew about the Y axis
893 */
894double rt_raster_get_x_skew(rt_raster raster);
895
896/**
897 * Get skew about the Y axis
898 *
899 * @param raster : the raster to set georeference of
900 * @return skew about the Y axis
901 */
902double rt_raster_get_y_skew(rt_raster raster);
903
904/**
905* Calculates and returns the physically significant descriptors embodied
906* in the geotransform attached to the provided raster.
907*
908* @param rast the raster containing the geotransform of interest
909* @param i_mag size of a pixel along the transformed i axis
910* @param j_mag size of a pixel along the transformed j axis
911* @param theta_i angle by which the raster is rotated (radians positive clockwise)
912* @param theta_ij angle from transformed i axis to transformed j axis
913* (radians positive counterclockwise)
914*
915*/
916void rt_raster_get_phys_params(rt_raster rast,
917        double *i_mag, double *j_mag, double *theta_i, double *theta_ij) ;
918
919/**
920* Calculates the geotransform coefficients and applies them to the
921* supplied raster. The coefficients will not be applied if there was an
922* error during the calculation.
923*
924* This method affects only the scale and skew coefficients. The offset
925* parameters are not changed.
926*
927* @param rast the raster in which the geotransform will be stored.
928* @param i_mag size of a pixel along the transformed i axis
929* @param j_mag size of a pixel along the transformed j axis
930* @param theta_i angle by which the raster is rotated (radians positive clockwise)
931* @param theta_ij angle from transformed i axis to transformed j axis
932* (radians positive counterclockwise)
933*/
934void rt_raster_set_phys_params(rt_raster rast,
935        double i_mag, double j_mag, double theta_i, double theta_ij) ;
936
937
938/**
939* Calculates the physically significant descriptors embodied in an
940* arbitrary geotransform. Always succeeds unless one or more of the
941* output pointers is set to NULL.
942*
943* @param xscale geotransform coefficient o_11
944* @param xskew geotransform coefficient o_12
945* @param yskew geotransform coefficient o_21
946* @param yscale geotransform coefficient o_22
947* @param i_mag size of a pixel along the transformed i axis
948* @param j_mag size of a pixel along the transformed j axis
949* @param theta_i angle by which the raster is rotated (radians positive clockwise)
950* @param theta_ij angle from transformed i axis to transformed j axis
951* (radians positive counterclockwise)
952*/
953void rt_raster_calc_phys_params(double xscale,
954        double xskew, double yskew, double yscale,
955        double *i_mag, double *j_mag, double *theta_i, double *theta_ij) ;
956
957
958/**
959* Calculates the coefficients of a geotransform given the physically
960* significant parameters describing the transform. Will fail if any of the
961* result pointers is NULL, or if theta_ij has an illegal value (0 or PI).
962*
963* @param i_mag size of a pixel along the transformed i axis
964* @param j_mag size of a pixel along the transformed j axis
965* @param theta_i angle by which the raster is rotated (radians positive clockwise)
966* @param theta_ij angle from transformed i axis to transformed j axis
967* (radians positive counterclockwise)
968* @param xscale geotransform coefficient o_11
969* @param xskew geotransform coefficient o_12
970* @param yskew geotransform coefficient o_21
971* @param yscale geotransform coefficient o_22
972* @return 1 if the calculation succeeded, 0 if error.
973*/
974int rt_raster_calc_gt_coeff(double i_mag,
975        double j_mag, double theta_i, double theta_ij,
976        double *xscale, double *xskew, double *yskew, double *yscale) ;
977
978/**
979 * Set raster's SRID
980 *
981 * @param raster : the raster to set SRID of
982 * @param srid : the SRID to set for the raster
983 */
984void rt_raster_set_srid(rt_raster raster, int32_t srid);
985
986/**
987 * Get raster's SRID
988 * @param raster : the raster to set SRID of
989 *
990 * @return the raster's SRID
991 */
992int32_t rt_raster_get_srid(rt_raster raster);
993
994/**
995 * Get 6-element array of raster geotransform matrix
996 *
997 * @param raster : the raster to get matrix of
998 * @param gt : output parameter, 6-element geotransform matrix
999 *
1000 */
1001void rt_raster_get_geotransform_matrix(rt_raster raster,
1002        double *gt);
1003
1004/**
1005 * Set raster's geotransform using 6-element array
1006 *
1007 * @param raster : the raster to set matrix of
1008 * @param gt : intput parameter, 6-element geotransform matrix
1009 *
1010 */
1011void rt_raster_set_geotransform_matrix(rt_raster raster,
1012        double *gt);
1013
1014/**
1015 * Convert an xr, yr raster point to an xw, yw point on map
1016 *
1017 * @param raster : the raster to get info from
1018 * @param xr : the pixel's column
1019 * @param yr : the pixel's row
1020 * @param xw : output parameter, X ordinate of the geographical point
1021 * @param yw : output parameter, Y ordinate of the geographical point
1022 * @param gt : input/output parameter, 3x2 geotransform matrix
1023 *
1024 * @return if zero, error occurred in function
1025 */
1026int rt_raster_cell_to_geopoint(rt_raster raster,
1027        double xr, double yr,
1028        double* xw, double* yw,
1029        double *gt);
1030
1031/**
1032 * Convert an xw, yw map point to a xr, yr raster point
1033 *
1034 * @param raster : the raster to get info from
1035 * @param xw : X ordinate of the geographical point
1036 * @param yw : Y ordinate of the geographical point
1037 * @param xr : output parameter, the pixel's column
1038 * @param yr : output parameter, the pixel's row
1039 * @param igt : input/output parameter, inverse geotransform matrix
1040 *
1041 * @return if zero, error occurred in function
1042 */
1043int rt_raster_geopoint_to_cell(rt_raster raster,
1044        double xw, double yw,
1045        double *xr, double *yr,
1046        double *igt);
1047
1048/**
1049 * Get raster's polygon convex hull.
1050 *
1051 * The convex hull is a 4 vertices (5 to be closed) single
1052 * ring polygon bearing the raster's rotation
1053 * and using projection coordinates
1054 *
1055 * @param raster : the raster to get info from
1056 *
1057 * @return the convex hull, or NULL on error.
1058 *
1059 */
1060LWPOLY* rt_raster_get_convex_hull(rt_raster raster);
1061
1062/**
1063 * Get raster's envelope.
1064 *
1065 * The envelope is the minimum bounding rectangle of the raster
1066 *
1067 * @param raster: the raster to get envelope of
1068 * @param env: pointer to rt_envelope
1069 *
1070 * @return 0 on error, 1 on success
1071 */
1072int rt_raster_get_envelope(
1073        rt_raster raster,
1074        rt_envelope *env
1075);
1076
1077/*
1078 * Compute skewed extent that covers unskewed extent.
1079 *
1080 * @param envelope: unskewed extent of type rt_envelope
1081 * @param skew: pointer to 2-element array (x, y) of skew
1082 * @param scale: pointer to 2-element array (x, y) of scale
1083 * @param tolerance: value between 0 and 1 where the smaller the tolerance
1084 *                   results in an extent approaching the "minimum" skewed
1085 *                   extent.  If value <= 0, tolerance = 0.1.
1086 *                   If value > 1, tolerance = 1.
1087 *
1088 * @return skewed raster who's extent covers unskewed extent, NULL on error
1089 */
1090rt_raster
1091rt_raster_compute_skewed_raster(
1092        rt_envelope extent,
1093        double *skew,
1094        double *scale,
1095        double tolerance
1096);
1097
1098/**
1099 * Get a raster pixel as a polygon.
1100 *
1101 * The pixel shape is a 4 vertices (5 to be closed) single
1102 * ring polygon bearing the raster's rotation
1103 * and using projection coordinates
1104 *
1105 * @param raster : the raster to get pixel from
1106 * @param x : the column number
1107 * @param y : the row number
1108 *
1109 * @return the pixel polygon, or NULL on error.
1110 *
1111 */
1112LWPOLY* rt_raster_pixel_as_polygon(rt_raster raster, int x, int y);
1113
1114/**
1115 * Returns a set of "geomval" value, one for each group of pixel
1116 * sharing the same value for the provided band.
1117 *
1118 * A "geomval" value is a complex type composed of a geometry
1119 * in LWPOLY representation (one for each group of pixel sharing
1120 * the same value) and the value associated with this geometry.
1121 *
1122 * @param raster: the raster to get info from.
1123 * @param nband: the band to polygonize. 0-based
1124 *
1125 * @return A set of "geomval" values, one for each group of pixels
1126 * sharing the same value for the provided band. The returned values are
1127 * LWPOLY geometries.
1128 */
1129rt_geomval
1130rt_raster_gdal_polygonize(
1131        rt_raster raster, int nband,
1132        int * pnElements
1133);
1134
1135/**
1136 * Return this raster in serialized form.
1137 *
1138 * Serialized form is documented in doc/RFC1-SerializedFormat.
1139 *
1140 */
1141void* rt_raster_serialize(rt_raster raster);
1142
1143/**
1144 * Return a raster from a serialized form.
1145 *
1146 * Serialized form is documented in doc/RFC1-SerializedFormat.
1147 *
1148 * NOTE: the raster will contain pointer to the serialized
1149 *       form, which must be kept alive.
1150 */
1151rt_raster rt_raster_deserialize(void* serialized, int header_only);
1152
1153
1154/**
1155 * Return TRUE if the raster is empty. i.e. is NULL, width = 0 or height = 0
1156 *
1157 * @param raster: the raster to get info from
1158 *
1159 * @return TRUE if the raster is empty, FALSE otherwise
1160 */
1161int rt_raster_is_empty(rt_raster raster);
1162
1163/**
1164 * Return TRUE if the raster do not have a band of this number.
1165 *
1166 * @param raster: the raster to get info from
1167 * @param nband: the band number. 0-based
1168 *
1169 * @return TRUE if the raster do not have a band of this number, FALSE otherwise
1170 */
1171int rt_raster_has_no_band(rt_raster raster, int nband);
1172
1173/**
1174 * Copy one band from one raster to another.  Bands are duplicated from
1175 * fromrast to torast using rt_band_duplicate.  The caller will need
1176 * to ensure that the copied band's data or path remains allocated
1177 * for the lifetime of the copied bands.
1178 *
1179 * @param torast: raster to copy band to
1180 * @param fromrast: raster to copy band from
1181 * @param fromindex: index of band in source raster, 0-based
1182 * @param toindex: index of new band in destination raster, 0-based
1183 *
1184 * @return The band index of the second raster where the new band is copied.
1185 */
1186int32_t rt_raster_copy_band(
1187        rt_raster torast, rt_raster fromrast,
1188        int fromindex, int toindex
1189);
1190
1191/**
1192 * Construct a new rt_raster from an existing rt_raster and an array
1193 * of band numbers
1194 *
1195 * @param raster : the source raster
1196 * @param bandNums : array of band numbers to extract from source raster
1197 *                   and add to the new raster (0 based)
1198 * @param count : number of elements in bandNums
1199 *
1200 * @return a new rt_raster or 0 on error
1201 */
1202rt_raster rt_raster_from_band(rt_raster raster, uint32_t *bandNums,
1203        int count);
1204
1205/**
1206 * Replace band at provided index with new band
1207 *
1208 * @param raster: raster of band to be replaced
1209 * @param band : new band to add to raster
1210 * @param index : index of band to replace (0-based)
1211 *
1212 * @return 0 on error or replaced band
1213 */
1214rt_band rt_raster_replace_band(rt_raster raster, rt_band band,
1215        int index);
1216
1217/**
1218 * Return formatted GDAL raster from raster
1219 *
1220 * @param raster : the raster to convert
1221 * @param srs : the raster's coordinate system in OGC WKT
1222 * @param format : format to convert to. GDAL driver short name
1223 * @param options : list of format creation options. array of strings
1224 * @param gdalsize : will be set to the size of returned bytea
1225 *
1226 * @return formatted GDAL raster.  the calling function is responsible
1227 *   for freeing the returned data using CPLFree()
1228 */
1229uint8_t *rt_raster_to_gdal(rt_raster raster, const char *srs,
1230        char *format, char **options, uint64_t *gdalsize);
1231
1232/**
1233 * Returns a set of available GDAL drivers
1234 *
1235 * @param drv_count : number of GDAL drivers available
1236 * @param cancc : if non-zero, filter drivers to only those
1237 *   with support for CreateCopy and VirtualIO
1238 *
1239 * @return set of "gdaldriver" values of available GDAL drivers
1240 */
1241rt_gdaldriver rt_raster_gdal_drivers(uint32_t *drv_count, uint8_t cancc);
1242
1243/**
1244 * Return GDAL dataset using GDAL MEM driver from raster
1245 *
1246 * @param raster : raster to convert to GDAL MEM
1247 * @param srs : the raster's coordinate system in OGC WKT
1248 * @param bandNums : array of band numbers to extract from raster
1249 *                   and include in the GDAL dataset (0 based)
1250 * @param count : number of elements in bandNums
1251 * @param rtn_drv : is set to the GDAL driver object
1252 *
1253 * @return GDAL dataset using GDAL MEM driver
1254 */
1255GDALDatasetH rt_raster_to_gdal_mem(rt_raster raster, const char *srs,
1256        uint32_t *bandNums, int count, GDALDriverH *rtn_drv);
1257
1258/**
1259 * Return a raster from a GDAL dataset
1260 *
1261 * @param ds : the GDAL dataset to convert to a raster
1262 *
1263 * @return raster
1264 */
1265rt_raster rt_raster_from_gdal_dataset(GDALDatasetH ds);
1266
1267/**
1268 * Return a warped raster using GDAL Warp API
1269 *
1270 * @param raster : raster to transform
1271 * @param src_srs : the raster's coordinate system in OGC WKT
1272 * @param dst_srs : the warped raster's coordinate system in OGC WKT
1273 * @param scale_x : the x size of pixels of the warped raster's pixels in
1274 *   units of dst_srs
1275 * @param scale_y : the y size of pixels of the warped raster's pixels in
1276 *   units of dst_srs
1277 * @param width : the number of columns of the warped raster.  note that
1278 *   width/height CANNOT be used with scale_x/scale_y
1279 * @param height : the number of rows of the warped raster.  note that
1280 *   width/height CANNOT be used with scale_x/scale_y
1281 * @param ul_xw : the X value of upper-left corner of the warped raster in
1282 *   units of dst_srs
1283 * @param ul_yw : the Y value of upper-left corner of the warped raster in
1284 *   units of dst_srs
1285 * @param grid_xw : the X value of point on a grid to align warped raster
1286 *   to in units of dst_srs
1287 * @param grid_yw : the Y value of point on a grid to align warped raster
1288 *   to in units of dst_srs
1289 * @param skew_x : the X skew of the warped raster in units of dst_srs
1290 * @param skew_y : the Y skew of the warped raster in units of dst_srs
1291 * @param resample_alg : the resampling algorithm
1292 * @param max_err : maximum error measured in input pixels permitted
1293 *   (0.0 for exact calculations)
1294 *
1295 * @return the warped raster
1296 */
1297rt_raster rt_raster_gdal_warp(rt_raster raster, const char *src_srs,
1298        const char *dst_srs,
1299        double *scale_x, double *scale_y,
1300        int *width, int *height,
1301        double *ul_xw, double *ul_yw,
1302        double *grid_xw, double *grid_yw,
1303        double *skew_x, double *skew_y,
1304        GDALResampleAlg resample_alg, double max_err);
1305
1306/**
1307 * Return a raster of the provided geometry
1308 *
1309 * @param wkb : WKB representation of the geometry to convert
1310 * @param wkb_len : length of the WKB representation of the geometry
1311 * @param srs : the geometry's coordinate system in OGC WKT
1312 * @param num_bands: number of bands in the output raster
1313 * @param pixtype: data type of each band
1314 * @param init: array of values to initialize each band with
1315 * @param value: array of values for pixels of geometry
1316 * @param nodata: array of nodata values for each band
1317 * @param hasnodata: array flagging the presence of nodata for each band
1318 * @param width : the number of columns of the raster
1319 * @param height : the number of rows of the raster
1320 * @param scale_x : the pixel width of the raster
1321 * @param scale_y : the pixel height of the raster
1322 * @param ul_xw : the X value of upper-left corner of the raster
1323 * @param ul_yw : the Y value of upper-left corner of the raster
1324 * @param grid_xw : the X value of point on grid to align raster to
1325 * @param grid_yw : the Y value of point on grid to align raster to
1326 * @param skew_x : the X skew of the raster
1327 * @param skew_y : the Y skew of the raster
1328 * @param options : array of options.  only option is "ALL_TOUCHED"
1329 *
1330 * @return the raster of the provided geometry
1331 */
1332rt_raster rt_raster_gdal_rasterize(const unsigned char *wkb,
1333        uint32_t wkb_len, const char *srs,
1334        uint32_t num_bands, rt_pixtype *pixtype,
1335        double *init, double *value,
1336        double *nodata, uint8_t *hasnodata,
1337        int *width, int *height,
1338        double *scale_x, double *scale_y,
1339        double *ul_xw, double *ul_yw,
1340        double *grid_xw, double *grid_yw,
1341        double *skew_x, double *skew_y,
1342        char **options
1343);
1344
1345/**
1346 * Return zero if error occurred in function.
1347 * Parameter intersects returns non-zero if two rasters intersect
1348 *
1349 * @param rast1 : the first raster whose band will be tested
1350 * @param nband1 : the 0-based band of raster rast1 to use
1351 *   if value is less than zero, bands are ignored.
1352 *   if nband1 gte zero, nband2 must be gte zero
1353 * @param rast2 : the second raster whose band will be tested
1354 * @param nband2 : the 0-based band of raster rast2 to use
1355 *   if value is less than zero, bands are ignored
1356 *   if nband2 gte zero, nband1 must be gte zero
1357 * @param intersects : non-zero value if the two rasters' bands intersects
1358 *
1359 * @return if zero, an error occurred in function
1360 */
1361int rt_raster_intersects(
1362        rt_raster rast1, int nband1,
1363        rt_raster rast2, int nband2,
1364        int *intersects
1365);
1366
1367/*
1368 * Return zero if error occurred in function.
1369 * Paramter aligned returns non-zero if two rasters are aligned
1370 *
1371 * @param rast1 : the first raster for alignment test
1372 * @param rast2 : the second raster for alignment test
1373 * @param aligned : non-zero value if the two rasters are aligned
1374 *
1375 * @return if zero, an error occurred in function
1376 */
1377int rt_raster_same_alignment(
1378        rt_raster rast1,
1379        rt_raster rast2,
1380        int *aligned
1381);
1382
1383/*
1384 * Return raster of computed extent specified extenttype applied
1385 * on two input rasters.  The raster returned should be freed by
1386 * the caller
1387 *
1388 * @param rast1 : the first raster
1389 * @param rast2 : the second raster
1390 * @param extenttype : type of extent for the output raster
1391 * @param err : if 0, error occurred
1392 * @param offset : 4-element array indicating the X,Y offsets
1393 * for each raster. 0,1 for rast1 X,Y. 2,3 for rast2 X,Y.
1394 *
1395 * @return raster object if success, NULL otherwise
1396 */
1397rt_raster
1398rt_raster_from_two_rasters(
1399        rt_raster rast1, rt_raster rast2,
1400        rt_extenttype extenttype,
1401        int *err, double *offset
1402);
1403
1404/*- utilities -------------------------------------------------------*/
1405
1406/*
1407 * rt_core memory functions
1408 */
1409extern void *rtalloc(size_t size);
1410extern void *rtrealloc(void *mem, size_t size);
1411extern void rtdealloc(void *mem);
1412
1413
1414
1415/* Set of functions to clamp double to int of different size
1416 */
1417
1418#if !defined(POSTGIS_RASTER_WARN_ON_TRUNCATION)
1419#define POSTGIS_RASTER_WARN_ON_TRUNCATION 0
1420#endif
1421
1422#define POSTGIS_RT_1BBMAX 1
1423#define POSTGIS_RT_2BUIMAX 3
1424#define POSTGIS_RT_4BUIMAX 15
1425
1426uint8_t
1427rt_util_clamp_to_1BB(double value);
1428
1429uint8_t
1430rt_util_clamp_to_2BUI(double value);
1431
1432uint8_t
1433rt_util_clamp_to_4BUI(double value);
1434
1435int8_t
1436rt_util_clamp_to_8BSI(double value);
1437
1438uint8_t
1439rt_util_clamp_to_8BUI(double value);
1440
1441int16_t
1442rt_util_clamp_to_16BSI(double value);
1443
1444uint16_t
1445rt_util_clamp_to_16BUI(double value);
1446
1447int32_t
1448rt_util_clamp_to_32BSI(double value);
1449
1450uint32_t
1451rt_util_clamp_to_32BUI(double value);
1452
1453float
1454rt_util_clamp_to_32F(double value);
1455
1456int
1457rt_util_dbl_trunc_warning(
1458        double initialvalue,
1459        int32_t checkvalint, uint32_t checkvaluint,
1460        float checkvalfloat, double checkvaldouble,
1461        rt_pixtype pixtype
1462);
1463
1464/**
1465 * Convert cstring name to GDAL Resample Algorithm
1466 *
1467 * @param algname: cstring name to convert
1468 *
1469 * @return valid GDAL resampling algorithm
1470 */
1471GDALResampleAlg
1472rt_util_gdal_resample_alg(const char *algname);
1473
1474/**
1475 * Convert rt_pixtype to GDALDataType
1476 *
1477 * @param pt: pixeltype to convert
1478 *
1479 * @return valid GDALDataType
1480 */
1481GDALDataType
1482rt_util_pixtype_to_gdal_datatype(rt_pixtype pt);
1483
1484/**
1485 * Convert GDALDataType to rt_pixtype
1486 *
1487 * @param gdt: GDAL datatype to convert
1488 *
1489 * @return valid rt_pixtype
1490 */
1491rt_pixtype
1492rt_util_gdal_datatype_to_pixtype(GDALDataType gdt);
1493
1494/*
1495        get GDAL runtime version information
1496*/
1497const char*
1498rt_util_gdal_version(const char *request);
1499
1500/*
1501        computed extent type from c string
1502*/
1503rt_extenttype
1504rt_util_extent_type(const char *name);
1505
1506char*
1507rt_util_gdal_convert_sr(const char *srs, int proj4);
1508
1509int
1510rt_util_gdal_driver_registered(const char *drv);
1511
1512void
1513rt_util_from_ogr_envelope(
1514        OGREnvelope     env,
1515        rt_envelope *ext
1516);
1517
1518void
1519rt_util_to_ogr_envelope(
1520        rt_envelope ext,
1521        OGREnvelope     *env
1522);
1523
1524LWPOLY *
1525rt_util_envelope_to_lwpoly(
1526        rt_envelope ext
1527);
1528
1529/*
1530        helper macros for consistent floating point equality checks
1531*/
1532#define FLT_NEQ(x, y) (fabs(x - y) > FLT_EPSILON)
1533#define FLT_EQ(x, y) (!FLT_NEQ(x, y))
1534#define DBL_NEQ(x, y) (fabs(x - y) > DBL_EPSILON)
1535#define DBL_EQ(x, y) (!DBL_NEQ(x, y))
1536
1537/*
1538        helper macro for symmetrical rounding
1539*/
1540#define ROUND(x, y) (((x > 0.0) ? floor((x * pow(10, y) + 0.5)) : ceil((x * pow(10, y) - 0.5))) / pow(10, y))
1541
1542/**
1543 * Struct definitions
1544 *
1545 * These structs are defined here as they are needed elsewhere
1546 * including rt_pg/rt_pg.c and reduce duplicative declarations
1547 *
1548 */
1549struct rt_raster_serialized_t {
1550    /*---[ 8 byte boundary ]---{ */
1551    uint32_t size; /* required by postgresql: 4 bytes */
1552    uint16_t version; /* format version (this is version 0): 2 bytes */
1553    uint16_t numBands; /* Number of bands: 2 bytes */
1554
1555    /* }---[ 8 byte boundary ]---{ */
1556    double scaleX; /* pixel width: 8 bytes */
1557
1558    /* }---[ 8 byte boundary ]---{ */
1559    double scaleY; /* pixel height: 8 bytes */
1560
1561    /* }---[ 8 byte boundary ]---{ */
1562    double ipX; /* insertion point X: 8 bytes */
1563
1564    /* }---[ 8 byte boundary ]---{ */
1565    double ipY; /* insertion point Y: 8 bytes */
1566
1567    /* }---[ 8 byte boundary ]---{ */
1568    double skewX; /* skew about the X axis: 8 bytes */
1569
1570    /* }---[ 8 byte boundary ]---{ */
1571    double skewY; /* skew about the Y axis: 8 bytes */
1572
1573    /* }---[ 8 byte boundary ]--- */
1574    int32_t srid; /* Spatial reference id: 4 bytes */
1575    uint16_t width; /* pixel columns: 2 bytes */
1576    uint16_t height; /* pixel rows: 2 bytes */
1577};
1578
1579/* NOTE: the initial part of this structure matches the layout
1580 *       of data in the serialized form version 0, starting
1581 *       from the numBands element
1582 */
1583struct rt_raster_t {
1584    uint32_t size;
1585    uint16_t version;
1586
1587    /* Number of bands, all share the same dimension
1588     * and georeference */
1589    uint16_t numBands;
1590
1591    /* Georeference (in projection units) */
1592    double scaleX; /* pixel width */
1593    double scaleY; /* pixel height */
1594    double ipX; /* geo x ordinate of the corner of upper-left pixel */
1595    double ipY; /* geo y ordinate of the corner of bottom-right pixel */
1596    double skewX; /* skew about the X axis*/
1597    double skewY; /* skew about the Y axis */
1598
1599    int32_t srid; /* spatial reference id */
1600    uint16_t width; /* pixel columns - max 65535 */
1601    uint16_t height; /* pixel rows - max 65535 */
1602    rt_band *bands; /* actual bands */
1603
1604};
1605
1606struct rt_extband_t {
1607    uint8_t bandNum; /* 0-based */
1608    char* path; /* externally owned ? */
1609                void *mem; /* loaded external band data, internally owned */
1610};
1611
1612struct rt_band_t {
1613    rt_pixtype pixtype;
1614    int32_t offline;
1615    uint16_t width;
1616    uint16_t height;
1617    int32_t hasnodata; /* a flag indicating if this band contains nodata values */
1618    int32_t isnodata;   /* a flag indicating if this band is filled only with
1619                           nodata values */
1620    double nodataval; /* int will be converted ... */
1621    int32_t ownsData; /* XXX mloskot: its behaviour needs to be documented */
1622
1623                rt_raster raster; /* reference to parent raster */
1624
1625    union {
1626        void* mem; /* actual data, externally owned */
1627        struct rt_extband_t offline;
1628    } data;
1629
1630};
1631
1632/* polygon as LWPOLY with associated value */
1633struct rt_geomval_t {
1634        LWPOLY *geom;
1635        double val;
1636};
1637
1638/* summary stats of specified band */
1639struct rt_bandstats_t {
1640        double sample;
1641        uint32_t count;
1642
1643        double min;
1644        double max;
1645        double sum;
1646        double mean;
1647        double stddev;
1648
1649        double *values;
1650        int sorted; /* flag indicating that values is sorted ascending by value */
1651};
1652
1653/* histogram bin(s) of specified band */
1654struct rt_histogram_t {
1655        uint32_t count;
1656        double percent;
1657
1658        double min;
1659        double max;
1660
1661        int inc_min;
1662        int inc_max;
1663};
1664
1665/* quantile(s) of the specified band */
1666struct rt_quantile_t {
1667        double quantile;
1668        double value;
1669        uint32_t has_value;
1670};
1671
1672/* listed-list structures for rt_band_get_quantiles_stream */
1673struct quantile_llist {
1674        uint8_t algeq; /* AL-GEQ (1) or AL-GT (0) */
1675        double quantile;
1676        uint64_t tau; /* position in sequence */
1677
1678        struct quantile_llist_element *head; /* H index 0 */
1679        struct quantile_llist_element *tail; /* H index last */
1680        uint32_t count; /* # of elements in H */
1681
1682        /* faster access to elements at specific intervals */
1683        struct quantile_llist_index *index;
1684        uint32_t index_max; /* max # of elements in index */
1685
1686        uint64_t sum1; /* N1H */
1687        uint64_t sum2; /* N2H */
1688};
1689
1690struct quantile_llist_element {
1691        double value;
1692        uint32_t count;
1693
1694        struct quantile_llist_element *prev;
1695        struct quantile_llist_element *next;
1696};
1697
1698struct quantile_llist_index {
1699        struct quantile_llist_element *element;
1700        uint32_t index;
1701};
1702
1703/* number of times a value occurs */
1704struct rt_valuecount_t {
1705        double value;
1706        uint32_t count;
1707        double percent;
1708};
1709
1710/* reclassification expression */
1711struct rt_reclassexpr_t {
1712        struct rt_reclassrange {
1713                double min;
1714                double max;
1715                int inc_min; /* include min */
1716                int inc_max; /* include max */
1717                int exc_min; /* exceed min */
1718                int exc_max; /* exceed max */
1719        } src, dst;
1720};
1721
1722/* gdal driver information */
1723struct rt_gdaldriver_t {
1724        int idx;
1725        char *short_name;
1726        char *long_name;
1727        char *create_options;
1728};
1729
1730#endif /* RT_API_H_INCLUDED */
Note: See TracBrowser for help on using the repository browser.