| 2919 | |
| 2920 | |
| 2921 | ---- |
| 2922 | == '''Objective FV.06 - Being able to do some base raster operations.''' - Partially == |
| 2923 | |
| 2924 | |
| 2925 | '''ST_ValueCount(raster, value) -> integer'''[[BR]] |
| 2926 | |
| 2927 | ST_ValueCount provides the ability to count the number of times that a user-provided value is present in a raster. To handle floating point values, a rounding argument is provided. |
| 2928 | |
| 2929 | A set of functions for one or more search values: |
| 2930 | |
| 2931 | ''If NULL is passed for "searchvalues" to any of the ST_ValueCount variations with "searchvalues", the function returns the counts for all unique values'' |
| 2932 | |
| 2933 | 1. ST_ValueCount(rast raster, nband integer, exclude_nodata_value boolean, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, count) |
| 2934 | |
| 2935 | returns the number of times that each value in searchvalues is present in the raster |
| 2936 | |
| 2937 | exclude_nodata_value: if FALSE, nodata values in band are considered in the count. if TRUE, nodata values are not considered |
| 2938 | |
| 2939 | searchvalues: the set of values to count in the raster |
| 2940 | |
| 2941 | roundto: the decimal position to round a pixel value to. Originally intended for use with 32BF and 64BF pixel types, it can also be used with integers when round to the tens, hundreds or higher place. |
| 2942 | |
| 2943 | examples are... |
| 2944 | |
| 2945 | {{{ |
| 2946 | roundto < 0: no rounding |
| 2947 | |
| 2948 | 0: no rounding |
| 2949 | |
| 2950 | 0.1: round to the tenths place |
| 2951 | |
| 2952 | 0.01: round to the hundredths place |
| 2953 | |
| 2954 | 0.001: round to the thousandths place |
| 2955 | |
| 2956 | 1: round to the ones place |
| 2957 | |
| 2958 | 10: round to the tens place |
| 2959 | |
| 2960 | 100: round to the hundreds place |
| 2961 | }}} |
| 2962 | |
| 2963 | {{{ |
| 2964 | ST_ValueCount(rast, 1, TRUE, ARRAY[23], 0) |
| 2965 | |
| 2966 | ST_ValueCount(rast, 5, FALSE, ARRAY[3.14], 0.01) |
| 2967 | |
| 2968 | ST_ValueCount(rast, 2, TRUE, ARRAY[100], 100) |
| 2969 | |
| 2970 | ST_ValueCount(rast, 1, FALSE, ARRAY[-9999, 0], 1) |
| 2971 | |
| 2972 | ST_ValueCount(rast, 1, FALSE, NULL::double precision[], 1) |
| 2973 | }}} |
| 2974 | |
| 2975 | 2. ST_ValueCount(rast raster, nband integer, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, count) |
| 2976 | |
| 2977 | exclude_nodata_value is assumed to be TRUE |
| 2978 | |
| 2979 | {{{ |
| 2980 | ST_ValueCount(rast, 5, ARRAY[3.14], 0.01) |
| 2981 | |
| 2982 | ST_ValueCount(rast, 2, NULL::double precision[], 100) |
| 2983 | }}} |
| 2984 | |
| 2985 | 3. ST_ValueCount(rast raster, nband integer, searchvalues double precision[]) -> setof record (searchvalue, count) |
| 2986 | |
| 2987 | roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE |
| 2988 | |
| 2989 | {{{ |
| 2990 | ST_ValueCount(rast, 1, ARRAY[-9999]) |
| 2991 | |
| 2992 | ST_ValueCount(rast, 1, NULL::double precision[]) |
| 2993 | }}} |
| 2994 | |
| 2995 | 4. ST_ValueCount(rast raster, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, count) |
| 2996 | |
| 2997 | nband is assumed to be 1. exclude_nodata_value is assumed to be TRUE. |
| 2998 | |
| 2999 | 5. ST_ValueCount(rast raster, searchvalues double precision[]) -> setof record (searchvalue, count) |
| 3000 | |
| 3001 | nband is assumed to be 1. roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE. |
| 3002 | |
| 3003 | A set of functions for a single search value: |
| 3004 | |
| 3005 | 1. ST_ValueCount(rast raster, nband integer, exclude_nodata_value boolean, searchvalue double precision, roundto double precision) -> integer |
| 3006 | |
| 3007 | returns the number of times that searchvalue is present in the raster |
| 3008 | |
| 3009 | searchvalue: the value to count in the raster |
| 3010 | |
| 3011 | {{{ |
| 3012 | ST_ValueCount(rast, 1, TRUE, 23, 0) |
| 3013 | |
| 3014 | ST_ValueCount(rast, 5, FALSE, 3.14, 0.01) |
| 3015 | |
| 3016 | ST_ValueCount(rast, 2, TRUE, 100, 100) |
| 3017 | |
| 3018 | ST_ValueCount(rast, 1, FALSE, -9999, 1) |
| 3019 | }}} |
| 3020 | |
| 3021 | 2. ST_ValueCount(rast raster, nband integer, searchvalue double precision, roundto double precision) -> integer |
| 3022 | |
| 3023 | exclude_nodata_value is assumed to be TRUE |
| 3024 | |
| 3025 | {{{ |
| 3026 | ST_ValueCount(rast, 5, 3.14, 0.01) |
| 3027 | |
| 3028 | ST_ValueCount(rast, 2, 100, 100) |
| 3029 | }}} |
| 3030 | |
| 3031 | 3. ST_ValueCount(rast raster, nband integer, searchvalue double precision) -> integer |
| 3032 | |
| 3033 | roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE |
| 3034 | |
| 3035 | {{{ |
| 3036 | ST_ValueCount(rast, 1, -9999) |
| 3037 | }}} |
| 3038 | |
| 3039 | 4. ST_ValueCount(rast raster, searchvalue double precision, roundto double precision) -> integer |
| 3040 | |
| 3041 | nband is assumed to be 1. exclude_nodata_value is assumed to be TRUE. |
| 3042 | |
| 3043 | 5. ST_ValueCount(rast raster, searchvalue double precision) -> integer |
| 3044 | |
| 3045 | nband is assumed to be 1. roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE. |
| 3046 | |
| 3047 | The set of functions for processing coverages return "bigint" instead of "integer". |
| 3048 | |
| 3049 | A set of functions for one or more search values: |
| 3050 | |
| 3051 | 1. ST_ValueCount(rastertable text, rastercolumn text, nband integer, exclude_nodata_value boolean, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, count) |
| 3052 | |
| 3053 | rastertable: name of the table with a raster column |
| 3054 | |
| 3055 | rastercolumn: name of the raster column |
| 3056 | |
| 3057 | {{{ |
| 3058 | ST_ValueCount('test', 'rast', 1, TRUE, ARRAY[23], 0) |
| 3059 | |
| 3060 | ST_ValueCount('test', 'rast', 5, FALSE, ARRAY[3.14], 0.01) |
| 3061 | |
| 3062 | ST_ValueCount('test', 'rast', 2, TRUE, ARRAY[100], 100) |
| 3063 | |
| 3064 | ST_ValueCount('test', 'rast', 1, FALSE, ARRAY[-9999, 0], 1) |
| 3065 | |
| 3066 | ST_ValueCount('test', 'rast', 1, FALSE, NULL::double precision[], 1) |
| 3067 | }}} |
| 3068 | |
| 3069 | 2. ST_ValueCount(rastertable text, rastercolumn text, nband integer, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, count) |
| 3070 | |
| 3071 | exclude_nodata_value is assumed to be TRUE |
| 3072 | |
| 3073 | {{{ |
| 3074 | ST_ValueCount('test', 'rast', 5, ARRAY[3.14], 0.01) |
| 3075 | |
| 3076 | ST_ValueCount('test', 'rast', 2, NULL::double precision[], 100) |
| 3077 | }}} |
| 3078 | |
| 3079 | 3. ST_ValueCount(rastertable text, rastercolumn text, nband integer, searchvalues double precision[]) -> setof record (searchvalue, count) |
| 3080 | |
| 3081 | roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE |
| 3082 | |
| 3083 | {{{ |
| 3084 | ST_ValueCount('test', 'rast', 1, ARRAY[-9999]) |
| 3085 | |
| 3086 | ST_ValueCount('test', 'rast', 1, NULL::double precision[]) |
| 3087 | }}} |
| 3088 | |
| 3089 | 4. ST_ValueCount(rastertable text, rastercolumn text, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, count) |
| 3090 | |
| 3091 | nband is assumed to be 1. exclude_nodata_value is assumed to be TRUE. |
| 3092 | |
| 3093 | 5. ST_ValueCount(rastertable text, rastercolumn text, searchvalues double precision[]) -> setof record (searchvalue, count) |
| 3094 | |
| 3095 | nband is assumed to be 1. roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE. |
| 3096 | |
| 3097 | A set of functions for a single search value: |
| 3098 | |
| 3099 | 1. ST_ValueCount(rastertable text, rastercolumn text, nband integer, exclude_nodata_value boolean, searchvalue double precision, roundto double precision) -> bigint |
| 3100 | |
| 3101 | searchvalue: the value to count in the raster |
| 3102 | |
| 3103 | {{{ |
| 3104 | ST_ValueCount('test', 'rast', 1, TRUE, 23, 0) |
| 3105 | |
| 3106 | ST_ValueCount('test', 'rast', 5, FALSE, 3.14, 0.01) |
| 3107 | |
| 3108 | ST_ValueCount('test', 'rast', 2, TRUE, 100, 100) |
| 3109 | |
| 3110 | ST_ValueCount('test', 'rast', 1, FALSE, -9999, 1) |
| 3111 | }}} |
| 3112 | |
| 3113 | 2. ST_ValueCount(rastertable text, rastercolumn text, nband integer, searchvalue double precision, roundto double precision) -> bigint |
| 3114 | |
| 3115 | exclude_nodata_value is assumed to be TRUE |
| 3116 | |
| 3117 | {{{ |
| 3118 | ST_ValueCount('test', 'rast', 5, 3.14, 0.01) |
| 3119 | |
| 3120 | ST_ValueCount('test', 'rast', 2, 100, 100) |
| 3121 | }}} |
| 3122 | |
| 3123 | 3. ST_ValueCount(rastertable text, rastercolumn text, nband integer, searchvalue double precision) -> bigint |
| 3124 | |
| 3125 | roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE |
| 3126 | |
| 3127 | {{{ |
| 3128 | ST_ValueCount('test', 'rast', 1, -9999) |
| 3129 | }}} |
| 3130 | |
| 3131 | 4. ST_ValueCount(rastertable text, rastercolumn text, searchvalue double precision, roundto double precision) -> bigint |
| 3132 | |
| 3133 | nband is assumed to be 1. exclude_nodata_value is assumed to be TRUE. |
| 3134 | |
| 3135 | 5. ST_ValueCount(rastertable text, rastercolumn text, searchvalue double precision) -> bigint |
| 3136 | |
| 3137 | nband is assumed to be 1. roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE. |
| 3138 | |
| 3139 | ---- |
| 3140 | |
| 3141 | '''ST_ValuePercent(raster, value) -> double precision'''[[BR]] |
| 3142 | |
| 3143 | ST_ValuePercent is the sibling of ST_ValueCount and returns the percentage of a raster's band that is of a specified value. To handle floating point values, a rounding argument is provided. |
| 3144 | |
| 3145 | A set of functions for one or more search values: |
| 3146 | |
| 3147 | ''If NULL is passed for "searchvalues" to any of the ST_ValuePercent variations with "searchvalues", the function returns the percents for all unique values'' |
| 3148 | |
| 3149 | 1. ST_ValuePercent(rast raster, nband integer, exclude_nodata_value boolean, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, percent) |
| 3150 | |
| 3151 | returns the percentage of a raster's band that each value in searchvalues is found |
| 3152 | |
| 3153 | exclude_nodata_value: if FALSE, nodata values in band are considered in the percents. if TRUE, nodata values are not considered |
| 3154 | |
| 3155 | searchvalues: the set of values to get percents for in the raster |
| 3156 | |
| 3157 | roundto: the decimal position to round a pixel value to. Originally intended for use with 32BF and 64BF pixel types, it can also be used with integers when round to the tens, hundreds or higher place. |
| 3158 | |
| 3159 | examples are... |
| 3160 | |
| 3161 | {{{ |
| 3162 | roundto < 0: no rounding |
| 3163 | |
| 3164 | 0: no rounding |
| 3165 | |
| 3166 | 0.1: round to the tenths place |
| 3167 | |
| 3168 | 0.01: round to the hundredths place |
| 3169 | |
| 3170 | 0.001: round to the thousandths place |
| 3171 | |
| 3172 | 1: round to the ones place |
| 3173 | |
| 3174 | 10: round to the tens place |
| 3175 | |
| 3176 | 100: round to the hundreds place |
| 3177 | }}} |
| 3178 | |
| 3179 | {{{ |
| 3180 | ST_ValuePercent(rast, 1, TRUE, ARRAY[23], 0) |
| 3181 | |
| 3182 | ST_ValuePercent(rast, 5, FALSE, ARRAY[3.14], 0.01) |
| 3183 | |
| 3184 | ST_ValuePercent(rast, 2, TRUE, ARRAY[100], 100) |
| 3185 | |
| 3186 | ST_ValuePercent(rast, 1, FALSE, ARRAY[-9999, 0], 1) |
| 3187 | |
| 3188 | ST_ValuePercent(rast, 1, FALSE, NULL::double precision[], 1) |
| 3189 | }}} |
| 3190 | |
| 3191 | 2. ST_ValuePercent(rast raster, nband integer, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, percent) |
| 3192 | |
| 3193 | exclude_nodata_value is assumed to be TRUE |
| 3194 | |
| 3195 | {{{ |
| 3196 | ST_ValuePercent(rast, 5, ARRAY[3.14], 0.01) |
| 3197 | |
| 3198 | ST_ValuePercent(rast, 2, NULL::double precision[], 100) |
| 3199 | }}} |
| 3200 | |
| 3201 | 3. ST_ValuePercent(rast raster, nband integer, searchvalues double precision[]) -> setof record (searchvalue, percent) |
| 3202 | |
| 3203 | roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE |
| 3204 | |
| 3205 | {{{ |
| 3206 | ST_ValuePercent(rast, 1, ARRAY[-9999]) |
| 3207 | |
| 3208 | ST_ValuePercent(rast, 1, NULL::double precision[]) |
| 3209 | }}} |
| 3210 | |
| 3211 | 4. ST_ValuePercent(rast raster, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, percent) |
| 3212 | |
| 3213 | nband is assumed to be 1. exclude_nodata_value is assumed to be TRUE. |
| 3214 | |
| 3215 | 5. ST_ValuePercent(rast raster, searchvalues double precision[]) -> setof record (searchvalue, percent) |
| 3216 | |
| 3217 | nband is assumed to be 1. roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE. |
| 3218 | |
| 3219 | A set of functions for a single search value: |
| 3220 | |
| 3221 | 1. ST_ValuePercent(rast raster, nband integer, exclude_nodata_value boolean, searchvalue double precision, roundto double precision) -> integer |
| 3222 | |
| 3223 | searchvalue: the value to get a percent for in the raster |
| 3224 | |
| 3225 | {{{ |
| 3226 | ST_ValuePercent(rast, 1, TRUE, 23, 0) |
| 3227 | |
| 3228 | ST_ValuePercent(rast, 5, FALSE, 3.14, 0.01) |
| 3229 | |
| 3230 | ST_ValuePercent(rast, 2, TRUE, 100, 100) |
| 3231 | |
| 3232 | ST_ValuePercent(rast, 1, FALSE, -9999, 1) |
| 3233 | }}} |
| 3234 | |
| 3235 | 2. ST_ValuePercent(rast raster, nband integer, searchvalue double precision, roundto double precision) -> integer |
| 3236 | |
| 3237 | exclude_nodata_value is assumed to be TRUE |
| 3238 | |
| 3239 | {{{ |
| 3240 | ST_ValuePercent(rast, 5, 3.14, 0.01) |
| 3241 | |
| 3242 | ST_ValuePercent(rast, 2, 100, 100) |
| 3243 | }}} |
| 3244 | |
| 3245 | 3. ST_ValuePercent(rast raster, nband integer, searchvalue double precision) -> integer |
| 3246 | |
| 3247 | roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE |
| 3248 | |
| 3249 | {{{ |
| 3250 | ST_ValuePercent(rast, 1, -9999) |
| 3251 | }}} |
| 3252 | |
| 3253 | 4. ST_ValuePercent(rast raster, searchvalue double precision, roundto double precision) -> integer |
| 3254 | |
| 3255 | nband is assumed to be 1. exclude_nodata_value is assumed to be TRUE. |
| 3256 | |
| 3257 | 5. ST_ValuePercent(rast raster, searchvalue double precision) -> integer |
| 3258 | |
| 3259 | nband is assumed to be 1. roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE. |
| 3260 | |
| 3261 | The set of functions for processing coverages return "bigint" instead of "integer". |
| 3262 | |
| 3263 | A set of functions for one or more search values: |
| 3264 | |
| 3265 | 1. ST_ValuePercent(rastertable text, rastercolumn text, nband integer, exclude_nodata_value boolean, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, percent) |
| 3266 | |
| 3267 | rastertable: name of the table with a raster column |
| 3268 | |
| 3269 | rastercolumn: name of the raster column |
| 3270 | |
| 3271 | {{{ |
| 3272 | ST_ValuePercent('test', 'rast', 1, TRUE, ARRAY[23], 0) |
| 3273 | |
| 3274 | ST_ValuePercent('test', 'rast', 5, FALSE, ARRAY[3.14], 0.01) |
| 3275 | |
| 3276 | ST_ValuePercent('test', 'rast', 2, TRUE, ARRAY[100], 100) |
| 3277 | |
| 3278 | ST_ValuePercent('test', 'rast', 1, FALSE, ARRAY[-9999, 0], 1) |
| 3279 | |
| 3280 | ST_ValuePercent('test', 'rast', 1, FALSE, NULL::double precision[], 1) |
| 3281 | }}} |
| 3282 | |
| 3283 | 2. ST_ValuePercent(rastertable text, rastercolumn text, nband integer, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, percent) |
| 3284 | |
| 3285 | exclude_nodata_value is assumed to be TRUE |
| 3286 | |
| 3287 | {{{ |
| 3288 | ST_ValuePercent('test', 'rast', 5, ARRAY[3.14], 0.01) |
| 3289 | |
| 3290 | ST_ValuePercent('test', 'rast', 2, NULL::double precision[], 100) |
| 3291 | }}} |
| 3292 | |
| 3293 | 3. ST_ValuePercent(rastertable text, rastercolumn text, nband integer, searchvalues double precision[]) -> setof record (searchvalue, percent) |
| 3294 | |
| 3295 | roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE |
| 3296 | |
| 3297 | {{{ |
| 3298 | ST_ValuePercent('test', 'rast', 1, ARRAY[-9999]) |
| 3299 | |
| 3300 | ST_ValuePercent('test', 'rast', 1, NULL::double precision[]) |
| 3301 | }}} |
| 3302 | |
| 3303 | 4. ST_ValuePercent(rastertable text, rastercolumn text, searchvalues double precision[], roundto double precision) -> setof record (searchvalue, percent) |
| 3304 | |
| 3305 | nband is assumed to be 1. exclude_nodata_value is assumed to be TRUE. |
| 3306 | |
| 3307 | 5. ST_ValuePercent(rastertable text, rastercolumn text, searchvalues double precision[]) -> setof record (searchvalue, percent) |
| 3308 | |
| 3309 | nband is assumed to be 1. roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE. |
| 3310 | |
| 3311 | A set of functions for a single search value: |
| 3312 | |
| 3313 | 1. ST_ValuePercent(rastertable text, rastercolumn text, nband integer, exclude_nodata_value boolean, searchvalue double precision, roundto double precision) -> bigint |
| 3314 | |
| 3315 | searchvalue: the value to get a percent for in the raster |
| 3316 | |
| 3317 | {{{ |
| 3318 | ST_ValuePercent('test', 'rast', 1, TRUE, 23, 0) |
| 3319 | |
| 3320 | ST_ValuePercent('test', 'rast', 5, FALSE, 3.14, 0.01) |
| 3321 | |
| 3322 | ST_ValuePercent('test', 'rast', 2, TRUE, 100, 100) |
| 3323 | |
| 3324 | ST_ValuePercent('test', 'rast', 1, FALSE, -9999, 1) |
| 3325 | }}} |
| 3326 | |
| 3327 | 2. ST_ValuePercent(rastertable text, rastercolumn text, nband integer, searchvalue double precision, roundto double precision) -> bigint |
| 3328 | |
| 3329 | exclude_nodata_value is assumed to be TRUE |
| 3330 | |
| 3331 | {{{ |
| 3332 | ST_ValuePercent('test', 'rast', 5, 3.14, 0.01) |
| 3333 | |
| 3334 | ST_ValuePercent('test', 'rast', 2, 100, 100) |
| 3335 | }}} |
| 3336 | |
| 3337 | 3. ST_ValuePercent(rastertable text, rastercolumn text, nband integer, searchvalue double precision) -> bigint |
| 3338 | |
| 3339 | roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE |
| 3340 | |
| 3341 | {{{ |
| 3342 | ST_ValuePercent('test', 'rast', 1, -9999) |
| 3343 | }}} |
| 3344 | |
| 3345 | 4. ST_ValuePercent(rastertable text, rastercolumn text, searchvalue double precision, roundto double precision) -> bigint |
| 3346 | |
| 3347 | nband is assumed to be 1. exclude_nodata_value is assumed to be TRUE. |
| 3348 | |
| 3349 | 5. ST_ValuePercent(rastertable text, rastercolumn text, searchvalue double precision) -> bigint |
| 3350 | |
| 3351 | nband is assumed to be 1. roundto is assumed to be 0, so no rounding takes place. exclude_nodata_value is assumed to be TRUE. |