GRASS GIS 8 Programmer's Manual  8.2.2dev(2023)-3d2c704037
raster/window.c
Go to the documentation of this file.
1 /*!
2  * \file lib/raster/window.c
3  *
4  * \brief Raster Library - Window functions.
5  *
6  * (C) 2001-2009 by the GRASS Development Team
7  *
8  * This program is free software under the GNU General Public License
9  * (>=v2). Read the file COPYING that comes with GRASS for details.
10  *
11  * \author Original author CERL
12  */
13 
14 #include <grass/gis.h>
15 #include <grass/raster.h>
16 #include <grass/glocale.h>
17 
18 #include "R.h"
19 
20 /*!
21  * \brief Read the current window
22  *
23  * \param window pointer to Cell_head
24  */
25 
26 void Rast_get_window(struct Cell_head *window)
27 {
29 
30  if (R__.split_window)
31  G_fatal_error(_("Internal error: Rast_get_window() called with split window."
32  " Use Rast_get_input_window() or Rast_get_output_window() instead."));
33 
34  *window = R__.wr_window;
35 }
36 
37 /*!
38  * \brief Read the current input window
39  *
40  * \param window pointer to Cell_head
41  */
42 
43 void Rast_get_input_window(struct Cell_head *window)
44 {
46 
47  *window = R__.rd_window;
48 }
49 
50 /*!
51  * \brief Read the current output window
52  *
53  * \param window pointer to Cell_head
54  */
55 
56 void Rast_get_output_window(struct Cell_head *window)
57 {
59 
60  *window = R__.wr_window;
61 }
62 
63 /*!
64  * \brief Number of rows in active window.
65  *
66  * This routine returns the number of rows in the active module window.
67  * Before raster files can be read or written, it is necessary to
68  * known how many rows are in the active window. For example:
69  \code
70 int nrows, cols;
71 int row, col;
72 
73 nrows = Rast_window_rows();
74 ncols = Rast_window_cols();
75 for (row = 0; row < nrows; row++) {
76  // read row ...
77  for (col = 0; col < ncols; col++) {
78  // process col ...
79  }
80 }
81  \endcode
82  *
83  * \return number of rows
84  */
86 {
88 
89  if (R__.split_window)
90  G_fatal_error(_("Internal error: Rast_window_rows() called with split window."
91  " Use Rast_input_window_rows() or Rast_output_window_rows() instead."));
92 
93  return R__.wr_window.rows;
94 }
95 
96 /*!
97  * \brief Number of columns in active window.
98  *
99  * These routines return the number of rows and columns (respectively)
100  * in the active module region. Before raster maps can be read or
101  * written, it is necessary to known how many rows and columns are in
102  * the active region. For example:
103  *
104  \code
105 int nrows, cols;
106 int row, col;
107 
108 nrows = Rast_window_rows();
109 ncols = Rast_window_cols();
110 for (row = 0; row < nrows; row++) {
111  // read row ...
112  for (col = 0; col < ncols; col++) {
113  // process col ...
114  }
115 }
116  \endcode
117  *
118  * \return number of columns
119  */
121 {
123 
124  if (R__.split_window)
125  G_fatal_error(_("Internal error: Rast_window_cols() called with split window."
126  " Use Rast_input_window_cols() or Rast_output_window_cols() instead."));
127 
128  return R__.wr_window.cols;
129 }
130 
131 /*!
132  * \brief Number of rows in active input window.
133  *
134  * This routine returns the number of rows in the active input window.
135  *
136  * \return number of rows
137  */
139 {
141 
142  return R__.rd_window.rows;
143 }
144 
145 /*!
146  * \brief Number of columns in active input window.
147  *
148  * This routine returns the number of columns in the active input window.
149  *
150  * \return number of columns
151  */
153 {
155 
156  return R__.rd_window.cols;
157 }
158 
159 /*!
160  * \brief Number of rows in active output window.
161  *
162  * This routine returns the number of rows in the active output window.
163  *
164  * \return number of rows
165  */
167 {
169 
170  return R__.wr_window.rows;
171 }
172 
173 /*!
174  * \brief Number of columns in active output window.
175  *
176  * This routine returns the number of columns in the active output window.
177  *
178  * \return number of columns
179  */
181 {
183 
184  return R__.wr_window.cols;
185 }
186 
187 /*!
188  * \brief Northing to row.
189  *
190  * Converts a <i>north</i>ing relative to a <i>window</i> to a row.
191 
192  * <b>Note:</b> The result is a double. Casting it to an integer will
193  * give the row number.
194  *
195  * \param north northing value
196  * \param window pointer to Cell_head
197  *
198  * \return row number
199  */
200 
201 double Rast_northing_to_row(double north, const struct Cell_head *window)
202 {
203  return (window->north - north) / window->ns_res;
204 }
205 
206 
207 /*!
208  * \brief Easting to column.
209  *
210  * Converts <i>east</i> relative to a <i>window</i> to a column.
211 
212  * <b>Note:</b> The result is a <i>double</i>. Casting it to an
213  * <i>int</i> will give the column number.
214  *
215  * \param east east coordinate
216  * \param window pointer to Cell_head
217  *
218  * \return column number
219  */
220 
221 double Rast_easting_to_col(double east, const struct Cell_head *window)
222 {
223  east = G_adjust_easting(east, window);
224 
225  return (east - window->west) / window->ew_res;
226 }
227 
228 /*!
229  * \brief Row to northing.
230  *
231  * Converts a <i>row</i> relative to a <i>window</i> to a
232  * northing.
233 
234  * <b>Note:</b> row is a double:
235  * - row+0.0 will return the northing for the northern edge of the row.
236  * - row+0.5 will return the northing for the center of the row.
237  * - row+1.0 will return the northing for the southern edge of the row.
238  *
239  * \param row row number
240  * \param[in] window pointer to Cell_head
241  *
242  * \return north coordinate
243  */
244 double Rast_row_to_northing(double row, const struct Cell_head *window)
245 {
246  return window->north - row * window->ns_res;
247 }
248 
249 /*!
250  * \brief Column to easting.
251  *
252  * Converts a <i>col</i> relative to a <i>window</i> to an easting.
253  *
254  * <b>Note:</b> <i>col</i> is a <i>double</i>:
255  * - col+0.0 will return the easting for the western edge of the column.
256  * - col+0.5 will return the easting for the center of the column.
257  * - col+1.0 will return the easting for the eastern edge of the column.
258  *
259  * \param col column number
260  * \param[in] window pointer to Cell_head
261  *
262  * \return east coordinate
263  */
264 double Rast_col_to_easting(double col, const struct Cell_head *window)
265 {
266  return window->west + col * window->ew_res;
267 }
268 
struct Cell_head rd_window
Definition: R.h:99
void void void void G_fatal_error(const char *,...) __attribute__((format(printf
Definition: R.h:88
2D/3D raster map header (used also for region)
Definition: gis.h:423
double west
Extent coordinates (west)
Definition: gis.h:475
double Rast_col_to_easting(double col, const struct Cell_head *window)
Column to easting.
int Rast_window_rows(void)
Number of rows in active window.
Definition: raster/window.c:85
void Rast__init_window(void)
struct Cell_head wr_window
Definition: R.h:100
double north
Extent coordinates (north)
Definition: gis.h:469
void Rast_get_input_window(struct Cell_head *window)
Read the current input window.
Definition: raster/window.c:43
void Rast_get_output_window(struct Cell_head *window)
Read the current output window.
Definition: raster/window.c:56
int Rast_window_cols(void)
Number of columns in active window.
void Rast_get_window(struct Cell_head *window)
Read the current window.
Definition: raster/window.c:26
int Rast_input_window_rows(void)
Number of rows in active input window.
double Rast_row_to_northing(double row, const struct Cell_head *window)
Row to northing.
double G_adjust_easting(double, const struct Cell_head *)
Returns east not smaller than west.
int cols
Number of columns for 2D data.
Definition: gis.h:442
double Rast_northing_to_row(double north, const struct Cell_head *window)
Northing to row.
double ns_res
Resolution - north to south cell size for 2D data.
Definition: gis.h:463
double east
Extent coordinates (east)
Definition: gis.h:473
#define _(str)
Definition: glocale.h:10
int Rast_output_window_rows(void)
Number of rows in active output window.
double Rast_easting_to_col(double east, const struct Cell_head *window)
Easting to column.
double ew_res
Resolution - east to west cell size for 2D data.
Definition: gis.h:459
int split_window
Definition: R.h:98
int rows
Number of rows for 2D data.
Definition: gis.h:438
int Rast_output_window_cols(void)
Number of columns in active output window.
int Rast_input_window_cols(void)
Number of columns in active input window.