1 /** 2 * @file clipping.h 3 * @brief Structs and interfaces for cell clipping 4 * 5 * @copyright Copyright (C) 2013 Moritz Hanke <hanke@dkrz.de> 6 * Rene Redler <rene.redler@mpimet.mpg.de> 7 * 8 * @version 1.0 9 * @author Moritz Hanke <hanke@dkrz.de> 10 * Rene Redler <rene.redler@mpimet.mpg.de> 11 */ 12 /* 13 * Keywords: 14 * Maintainer: Moritz Hanke <hanke@dkrz.de> 15 * Rene Redler <rene.redler@mpimet.mpg.de> 16 * URL: https://dkrz-sw.gitlab-pages.dkrz.de/yac/ 17 * 18 * This file is part of YAC. 19 * 20 * Redistribution and use in source and binary forms, with or without 21 * modification, are permitted provided that the following conditions are 22 * met: 23 * 24 * Redistributions of source code must retain the above copyright notice, 25 * this list of conditions and the following disclaimer. 26 * 27 * Redistributions in binary form must reproduce the above copyright 28 * notice, this list of conditions and the following disclaimer in the 29 * documentation and/or other materials provided with the distribution. 30 * 31 * Neither the name of the DKRZ GmbH nor the names of its contributors 32 * may be used to endorse or promote products derived from this software 33 * without specific prior written permission. 34 * 35 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 36 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 37 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 38 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 39 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 40 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 41 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 42 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 43 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 44 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 45 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 46 */ 47 48 #ifndef CLIPPING_H 49 #define CLIPPING_H 50 51 #include "grid_cell.h" 52 53 /** \example test_clipping.c 54 * This contains some examples on how to use the \ref yac_cell_clipping 55 * routine. 56 */ 57 /** \example test_lat_clipping.c 58 * This contains some examples on how to use the yac_cell_lat_clipping 59 * routine. 60 */ 61 62 /** 63 * \brief cell clipping to get the cells describing the intersections 64 * 65 * The routine takes (a list of) source cells and a target cell. It sets the 66 * target cell data and does some further initialisation. Thus it needs to be 67 * called for each new target cell intersection calculation 68 * 69 * The vertices of source and target cells can be either provided in a clockwise 70 * or anticlockwise sense. However, the same sense must be used for source and 71 * target cells. 72 * 73 * @param[in] N number of source cells 74 * @param[in] source_cell list of source cells 75 * @param[in] target_cell target cell 76 * @param[in] overlap_buffer buffer for the overlaps between the target and 77 * the source cells 78 * 79 * \remark source and target cells have to be convex 80 * \remark cells in overlap_buffer can be concave 81 * \remark overlap_buffer must contain valid grid_cells (have to be initialised 82 * using \ref yac_init_grid_cell; initialisation have to be done only once, 83 * in consecutive calls, the cells can be reused with have to be 84 * reinitialised) 85 * 86 **/ 87 void yac_cell_clipping (size_t N, 88 struct grid_cell * source_cell, 89 struct grid_cell target_cell, 90 struct grid_cell * overlap_buffer); 91 92 /** 93 * \brief cell clipping to get the cells describing the intersections 94 * 95 * The routine takes (a list of) cells and two latitude bounds. 96 * 97 * @param[in] N number of cells 98 * @param[in] cells list of cells 99 * @param[in] lat_bounds latitude bounds in radiant 100 * @param[in] overlap_buffer buffer for the overlaps between the cells and 101 * latitude band 102 * 103 * \remark cells in overlap_buffer can be concave 104 * \remark overlap_buffer must contain valid grid_cells (have to be initialised 105 * using \ref yac_init_grid_cell; initialisation have to be done only once, 106 * in consecutive calls, the cells can be reused with have to be 107 * reinitialised) 108 * \remark this routine is currently not being used within YAC but potentially 109 * used within the CDOs 110 * 111 **/ 112 void yac_cell_lat_clipping (size_t N, 113 struct grid_cell * cells, 114 double lat_bounds[2], 115 struct grid_cell * overlap_buffer); 116 117 /** \example test_partial_areas.c 118 * This contains examples on how to use \ref yac_compute_overlap_areas. 119 */ 120 121 /** \example test_compute_overlap_area.c 122 * This contains examples on how to use \ref yac_compute_overlap_areas. 123 */ 124 125 /** 126 * \brief calculates partial areas for all overlapping parts of the source 127 * cells with triangular target cells. This is required for 128 * conservative remapping 129 * 130 * Some of the underlying concepts can be found in 131 * 132 * See e.g. Joseph O'Rourke, Computational Geometry in C, 2nd Ed., 1998 133 * Sec. 7.6 Intersections of Convex Polygons, page 253. 134 * 135 * The routine takes (a list of) source cells and a convex target cell. As 136 * a triangle is always convex we recommend to use this routine only for 137 * triangular target cells. It determines the 138 * clipping points of the intersection between a source and the target cells using 139 * cell_clipping internally. In a second step areas are calculated for each 140 * intersection described in the overlap cells. If a target cell is fully 141 * covered by N source cells the N partial areas should add up to the area of 142 * the target cell. 143 * 144 * @param[in] N number of source cells 145 * @param[in] source_cell list of source cells 146 * @param[in] target_cell target cell 147 * @param[out] partial_areas list of N partial weights, one weight for each 148 * source-target intersection 149 * 150 * \remark source and target cell have to be convex 151 * 152 **/ 153 void yac_compute_overlap_areas (size_t N, 154 struct grid_cell * source_cell, 155 struct grid_cell target_cell, 156 double * partial_areas); 157 158 /** 159 * \brief calculates partial areas for all overlapping parts of the source 160 * cells with arbitrary target cells, this is required for conservative 161 * remapping. 162 * 163 * Some of the underlying concepts can be found in 164 * 165 * See e.g. Joseph O'Rourke, Computational Geometry in C, 2nd Ed., 1998 166 * Sec. 7.6 Intersections of Convex Polygons, page 253. 167 * 168 * The routine takes (a list of) source cells and a target cell. It determines the 169 * clipping points of the intersection between a source and the target cells using 170 * cell_clipping internally. In a second step areas are calculated for each 171 * intersection described in the overlap cells. If a target cell is fully 172 * covered by N source cells the N partial areas should add up to the area of 173 * the target cell. 174 * 175 * @param[in] N number of source cells 176 * @param[in] source_cell list of source cells 177 * @param[in] target_cell target cell 178 * @param[in] target_node_xyz cartesian coordinate of target cell node or 179 * center point 180 * @param[out] partial_areas list of N partial weights, one weight for each 181 * source-target intersection 182 * 183 * \remark source and target cell have to be convex 184 * 185 **/ 186 void yac_compute_concave_overlap_areas (size_t N, 187 struct grid_cell * source_cell, 188 struct grid_cell target_cell, 189 double target_node_xyz[3], 190 double * partial_areas); 191 192 /** 193 * \brief calculates partial areas for all overlapping parts of the source 194 * cells with arbitrary target cells, this is required for conservative 195 * remapping. In addition, the barycenter of each overlap is calculated. 196 * 197 * Some of the underlying concepts can be found in 198 * 199 * See e.g. Joseph O'Rourke, Computational Geometry in C, 2nd Ed., 1998 200 * Sec. 7.6 Intersections of Convex Polygons, page 253. 201 * 202 * The routine takes (a list of) source cells and a target cell. It determines the 203 * clipping points of the intersection between a source and the target cells using 204 * cell_clipping internally. In a second step areas are calculated for each 205 * intersection described in the overlap cells. If a target cell is fully 206 * covered by N source cells the N partial areas should add up to the area of 207 * the target cell. 208 * 209 * @param[in] N number of source cells 210 * @param[in] source_cell list of source cells 211 * @param[in] target_cell target cell 212 * @param[in] target_node_xyz cartesian coordinate of target cell node or 213 * center point 214 * @param[out] overlap_areas list of N partial weights, one weight for 215 * each source-target intersection 216 * @param[out] overlap_barycenters coordinates of the barycenters of the 217 * overlap cell 218 * 219 * \remark source and target cell have to be convex 220 * 221 **/ 222 void yac_compute_concave_overlap_info (size_t N, 223 struct grid_cell * source_cell, 224 struct grid_cell target_cell, 225 double target_node_xyz[3], 226 double * overlap_areas, 227 double (*overlap_barycenters)[3]); 228 /** 229 * \brief correct interpolation weights 230 * 231 * Returns weights with a sum close to 1.0 232 * 233 * @param[in] N number of source cells 234 * @param[out] weight list of N partial weights 235 * 236 **/ 237 void yac_correct_weights (size_t N, double * weight); 238 239 #endif // CLIPPING_H 240 241