1Metadata-Version: 2.1 2Name: pyrsgis 3Version: 0.4.1 4Summary: A package to read, process and export GeoTIFFs. 5Home-page: https://github.com/PratyushTripathy/pyrsgis 6Author: Pratyush Tripathy 7Author-email: pratkrt@gmail.com 8License: UNKNOWN 9Description: # Python-for-Remote-Sensing-and-GIS 10 [![PyPI version](https://badge.fury.io/py/pyrsgis.svg)](https://pypi.org/project/pyrsgis/) 11 [![Anaconda-Server Badge](https://anaconda.org/pratyusht/pyrsgis/badges/version.svg)](https://anaconda.org/pratyusht/pyrsgis) 12 [![Anaconda-Server Badge](https://anaconda.org/pratyusht/pyrsgis/badges/latest_release_date.svg)](https://github.com/PratyushTripathy/pyrsgis) 13 [![Documentation Status](https://readthedocs.org/projects/pyrsgis/badge/?version=master)](https://pyrsgis.readthedocs.io/en/master/?badge=master) 14 [![Downloads](https://pepy.tech/badge/pyrsgis)](https://pepy.tech/project/pyrsgis) 15 16 *pyrsgis* enables the user to read, process and export GeoTIFFs. The module is built on the GDAL library but is much more convenient when it comes to reading and exporting GeoTIFs. There are several other functions available in this package that ease raster pre-processing. Please check the [documentation page](https://pyrsgis.readthedocs.io/) for a list of functions that pyrsgis offers along with the sample code.<br/> 17 18 Feedback and doubts from users are most welcome. Since this is an open-source volunatry project, I always look forward to contributors. You can write to me at [pratkrt@gmail.com](mailto:pratkrt@gmail.com). 19 20 pyrsgis is available on both, PyPI and Anaconda. Please check the [installation page](https://pyrsgis.readthedocs.io/en/master/installation.html) for details. 21 22 **Recommended citation:**<br/> 23 Tripathy, P. pyrsgis: A Python package for remote sensing and GIS data processing. V0.4. Available at https://github.com/PratyushTripathy/pyrsgis. 24 25 # Sample code (click to expand) 26 <details><summary><b>1. Reading .tif extension file</b></summary> 27 <p> 28 Import the module and define the input file path.<br/> 29 30 ```Python 31 from pyrsgis import raster 32 33 file_path = r'D:/your_file_name.tif' 34 ``` 35 36 * To read all the bands of a stacked satellite image:<br/> 37 ```Python 38 ds, arr = raster.read(file_path, bands='all') 39 ``` 40 where, `ds` is the data source similar to GDAL and `arr` is the numpy array that contains all the bands of the input raster. The `arr` can be 2D or 3D depending on the input data. One can check the shape of the array using the `print(arr.shape)` command. The `bands` argument in the `raster.read` function defaults to `'all'`.<br/> 41 42 * To read a list of bands of a stacked satellite image:<br/> 43 ```Python 44 ds, arr = raster.read(file_path, bands=[2, 3, 4]) 45 ``` 46 Passing the band numbers in a list returns bands 2, 3 & 4 as three-dimensional numpy array.<br/> 47 48 * To read a specific band from stacked satellite image:<br/> 49 ```Python 50 ds, arr = raster.read(file_path, bands=2) 51 ``` 52 Passing a single band number returns that particular band as two-dimensional numpy array.<br/> 53 54 * To read a single band TIF file:<br/> 55 ```Python 56 ds, arr = raster.read(file_path) 57 ``` 58 Since the `bands` argument defaults to `'all'`, this will read all the bands in the input file, here, one band only.<br/> 59 </p> 60 </details> 61 62 <details><summary><b>2. Exporting .tif extension file</b></summary> 63 <p> 64 In all the below examples, it is assumed that the number of rows and columns, and the cell size of the input and output rasters are the same. All these are stored in the `ds` variable, please see details here: link.<br/> 65 66 * To export all bands of a 3D array:<br/> 67 ```Python 68 out_file_path = r'D:/sample_file_all_bands.tif' 69 raster.export(arr, ds, out_file_path, dtype='int', bands='all') 70 ``` 71 The `dtype` argument in the above function by default is set to `'default'`, which is `'int'`--16-bit integer. If the data type in the provided `ds` is not `int` and the paramter is set to `default`, then the data type of the `ds` will be used. If there is a disagreement and the `dtype` argument is explicitly specified, it will override the data type of `ds`. Please be careful to change this while exporting arrays with large values. Similarly, to export float type array (eg. NDVI), use `dtype = 'float'`. Data type of high pixel-depth, e.g. Integer32, Integer64, or float type uses more space on hard drive, so the default has been set to integer. To export any float datatype, the argument should be passed explicitly.<br/> 72 These are the options for the `dtype` argument: `byte`, `cfloat32`, `cfloat64`, `cint16`, `cint32`, `float32`, `float64`, `int16`, `int32`, `uint8`, `uint16`, `uint32`.<br/> 73 The NoData value can be explicitly defined using the `nodata` parameter, this defaults to `-9999`. 74 75 * To export a list of bands of a 3D array:<br/> 76 ```Python 77 out_file_path = r'D:/sample_file_bands_234.tif' 78 raster.export(arr, ds, out_file_path, bands=[2, 3, 4]) 79 ``` 80 81 * To export any one band of a 3D array:<br/> 82 ```Python 83 out_file_path = r'D:/sample_file_band_3.tif' 84 raster.export(arr, ds, out_file_path, bands=3) 85 ``` 86 87 * To export a single band array:<br/> 88 ```Python 89 out_file_path = r'D:/sample_file.tif' 90 raster.export(arr, ds, out_file_path) 91 ``` 92 where, `arr` should be a 2D array.<br/> 93 94 * Export the raster with compression:<br/> 95 Compression type can also be defined while exporting the raster by using the `compress` parameter. `LZW`. `DEFLATE`, etc. are a couple of options. Defaults to `None`.<br/> 96 97 * Example with all default parameters:<br/> 98 ```Python 99 out_file_path = r'D:/sample_file.tif' 100 raster.export(band, ds, filename='pyrsgis_outFile.tif', dtype='int', bands=1, nodata=-9999, compress=None) 101 ``` 102 </p> 103 </details> 104 105 <details><summary><b>3. Converting TIF to CSV</b></summary> 106 <p> 107 GeoTIFF files can be converted to CSV files using *pyrsgis*. Every band is flattened to a single-dimensional array, and converted to CSV. These are very useful for statistical analysis.<br/> 108 Import the function:<br/> 109 110 ```Python 111 from pyrsgis.convert import rastertocsv 112 ``` 113 114 To convert all the bands present in a folder: 115 ```Python 116 your_dir = r"D:/your_raster_directory" 117 out_file_path = r"D:/yourFilename.csv" 118 119 rastertocsv(your_dir, filename=out_file_path) 120 ``` 121 122 Generally the NoData or NULL values in the raster become random negative values, negatives can be removed using the `negative` argument:<br/> 123 ```Python 124 rastertocsv(your_dir, filename=out_file_path, negative=False) 125 ``` 126 127 At times the NoData or NULL values in raster become '127' or '65536', they can also be removed by declaring explicitly.<br/> 128 ```Python 129 rastertocsv(your_dir, filename=out_file_path, remove=[127, 65536]) 130 ``` 131 This is a trial and check process, please check the generated CSV file for such issues and handle as required.<br/> 132 133 Similarly, there are bad rows in the CSV file, representing zero value in all the bands. This takes a lot of unnecessary space on drive, it can be eliminated using:<br/> 134 ```Python 135 rastertocsv(your_dir, filename=out_file_path, badrows=False) 136 ``` 137 </p> 138 </details> 139 140 <details><summary><b>4. Creating northing and easting using a reference raster</b></summary> 141 <p> 142 143 pyrsgis allows to quickly create the northing and easting rasters using a reference raster, as shown below:<br/> 144 <img src="https://raw.githubusercontent.com/PratyushTripathy/pyrsgis/master/media/northing_easting.png" height="225" width="640"> 145 146 The cell value in the generated rasters are the row and column number of the cell. To generate these GeoTIFF files, start by importing the function: 147 148 ```Python 149 from pyrsgis.raster import northing, easting 150 151 reference_file_path = r'D:/your_reference_raster.tif' 152 153 northing(reference_file_path, outFile= r'D:/pyrsgis_northing.tif', flip=True) 154 easting(reference_file_path, outFile= r'D:/pyrsgis_easting.tif', flip=False) 155 ``` 156 As the name suggests, the `flip` argument flips the resulting rasters.<br/> 157 The `value` argument defaults to `number`. It can be changed to `normalised` to get a normalised layer. The other option for `value` argument is `coordinates`, which produces the raster layer with cell centroids. Please note that if the `value` argument is set to `normalised`, it will automatically adjust the flip value, i.e. False, both in easting and northing functions. Similarly, the `dtype` parameter auto-adjusts with the data type, but can be changed to a higher pixel depth when `value` argument is `number`. Example with all parameters:<br/> 158 159 160 ```Python 161 northing(reference_file_path, outFile='pyrsgis_northing.tif', flip=True, value='number', dtype='int16') 162 easting(reference_file_path, outFile='pyrsgis_easting.tif', flip=False, value='number', dtype='int16') 163 ``` 164 </p> 165 </details> 166 167 <details><summary><b>5. Shifting raster layers</b></summary> 168 <p> 169 You can shift the raster layers using either the 'shift' or 'shift_file' function. The 'shift' function allows to shift the raster in the backend, whereas, the 'shift_file' directly shifts the GeoTIF file and stores another file.<br/> 170 171 To shift in the backend:<br/> 172 ```Python 173 from pyrsgis import raster 174 175 # Define the path to the input file and get the data source 176 infile = r"D:/path_to_your_file/input.tif" 177 ds, arr = raster.read(infile) 178 179 # Define the amount of shift required 180 delta_x = 15 181 delta_y = 11.7 182 183 # shift the raster 184 shifted_ds = raster.shift(ds, x=delta_x, y=delta_y, shift_type) 185 186 # if you wish to export 187 raster.export(arr, ds, out_file, dtype='int', bands=1, nodata=-9999) 188 ``` 189 Here, 'ds' is the data source object that is created when the raster is read using 'raster.read' command. 'x' and 'y' are the distance for shifting the raster. The 'shift_type' command let's you move the raster either by the raster units or number of cells, the valid options are 'unit' and 'cell'. By default, the 'shift_type' is 'unit'.<br/> 190 191 To shift a GeoTIFF file:<br/> 192 ```Python 193 from pyrsgis import raster 194 195 # Define the path to the input and output file 196 infile = r"D:/path_to_your_file/input.tif" 197 outfile = r"D:/path_to_your_file/shifted_output.tif" 198 199 # Define the amount of shift required 200 delta_x = 15 201 delta_y = 11.7 202 203 # shift the raster 204 raster.shift_file(infile, x=delta_x, y=delta_y, outfile=outfile, shift_type='unit', dtype='uint16') 205 ``` 206 Most of the parameters are same as the 'shift' function. The 'dtype' parameter is same as used in the 'raster.export' function.<br/> 207 </p> 208 </details> 209 210 <details><summary><b>6. Create image chips for Convolutional Neural Network (CNN)</b></summary> 211 <p> 212 CNNs require image chips for training and prediction. Remote sensing images are large sized two or three-dimesional images, this module enables creating image chips directly from TIF files or arrays. The input data and size of image chips are required.<br/> 213 214 To create image chips from array:<br/> 215 ```Python 216 from pyrsgis import raster 217 from pyrsgis.ml import imageChipsFromArray 218 219 # read the TIF file(s) (both are of different sizes - for demonstration) 220 single_band_file = r'path/to/single_band.tif' 221 multi_band_file = r'path/to/multi_band.tif' # this is a Landsat 5 TM image (7 bands stacked) 222 223 # read the files as array using pyrsgis raster.read module 224 _, single_band_array = raster.read(single_band_file) 225 _, multi_band_array = raster.read(multi_band_file) 226 227 # create image chips 228 single_band_chips = imageChipsFromArray(single_band_array, x_size=5, y_size=5)) 229 multi_band_chips = imageChipsFromArray(multi_band_array, x_size=5, y_size=5)) 230 231 print(single_band_chips.shape) 232 print(multi_band_chips.shape) 233 ``` 234 The output:<br/> 235 ``` 236 (91125, 5, 5) 237 (987552, 5, 5, 7) 238 ``` 239 240 Image chips can also be generated directly from TIF files using following:<br/> 241 ```Python 242 from pyrsgis.ml import imageChipsFromFile 243 244 # read the TIF file(s) (both are of different sizes - for demonstration) 245 single_band_file = r'path/to/single_band.tif' 246 multi_band_file = r'path/to/multi_band.tif' # this is a Landsat 5 TM image (7 bands stacked) 247 248 # create image chips 249 single_band_chips = imageChipsFromFile(single_band_file, x_size=5, y_size=5)) 250 multi_band_chips = imageChipsFromFile(multi_band_file, x_size=5, y_size=5)) 251 252 print(single_band_chips.shape) 253 print(multi_band_chips.shape) 254 ``` 255 This will result in the same output as the one above.<br/> 256 </p> 257 </details> 258 259 <details><summary><b>7. Reading directly from .tar.gz files (beta)</b></summary> 260 <p> 261 262 Currently, only Landsat data is supported.<br/> 263 ```Python 264 import pyrsgis 265 266 file_path = r'D:/your_file_name.tar.gz' 267 your_data = pyrsgis.readtar(file_path) 268 ``` 269 The above code reads the data and stores in the `your_data` variable.<br/> 270 271 Various properties of the raster can be assessed using the following code:<br/> 272 ```Python 273 print(your_data.rows) 274 print(your_data.cols) 275 ``` 276 This will display the number of rows and columns of the input data.<br/> 277 278 Similarly, the number of bands can be checked using:<br/> 279 ```Python 280 print(your_data.nbands) 281 ``` 282 283 On reading the .tar.gz files directly, pyrsgis determines the satellite sensor. This can be checked using:<br/> 284 ```Python 285 print(your_data.satellite) 286 ``` 287 This will display the satellite sensor, for instance, Landsat-5, Landsat-8, etc.<br/> 288 289 If the above code shows the correct satellite sensor, then the list of band names of the sensor (in order) can easily be checked using:<br/> 290 ```Python 291 print(your_data.bandIndex) 292 ``` 293 294 Any particular band can be extarcted using:<br/> 295 ```Python 296 band_number = 1 297 your_band = your_data.getband(band_number) 298 ``` 299 The above code returns the band as array which can be visualised using:<br/> 300 301 ```Python 302 display(your_band, maptitle='Title of your image', cmap='PRGn') 303 ``` 304 or, directly using: 305 ```Python 306 band_number = 1 307 display(your_data.getband(band_number), maptitle='Title of your image', cmap='PRGn') 308 ``` 309 The generated map can directly be saved as an image.<br/> 310 311 The extracted band can be exported using:<br/> 312 ```Python 313 out_file_path = r'D:/sample_output.tif' 314 your_data.export(your_band, out_file_path) 315 ``` 316 This saves the extracted band to the same directory.<br/> 317 318 To export the float type raster, please define the `datatype` explicitly, default is 'int':<br/> 319 ```Python 320 your_data.export(your_band, out_file_path, datatype='float') 321 ``` 322 323 The NDVI (Normalised Difference Vegetaton Index) can be computed easily.<br/> 324 ```Python 325 your_ndvi = your_data.ndvi() 326 ``` 327 328 Normalised difference index between any two bands can be computed using:<br/> 329 ```Python 330 norm_diff = your_data.nordif(bandNumber2, bandNumber1) 331 ``` 332 This computes (band2-band1)/(band2+band1) in the back end and returns a numpy array. The resulting array can be exported using:<br/> 333 ```Python 334 out_file_path = r'D:/your_ndvi.tif' 335 your_data.export(your_ndvi, out_file_path, datatype='float') 336 ``` 337 Be careful with the float type of NDVI.<br/> 338 </p> 339 </details> 340 341Platform: UNKNOWN 342Classifier: Development Status :: 5 - Production/Stable 343Classifier: Programming Language :: Python :: 3 344Classifier: License :: OSI Approved :: MIT License 345Classifier: Operating System :: OS Independent 346Description-Content-Type: text/markdown 347