documentation (#44)

* add doc image

* add data cube example

* add package workflow to readme

* correct image path

* remove spaces in docs folder name

* reorganize images

* rearrange docs images folder

* rearrange docs images folder

* update schame with private functions

* rearrange docs images folder

* fix bug in plotting dataset without specifying the band

* update cleopatra

* fix bug in passing ot not passing band index in case of multi band rasters

* change the bounds in to_dataset method to total_bounds tp get the bbox of the whole geometries in the gdf

* convert longitude to range between -180 and 180

* update cleopatra

* add convert_longitude to scheme

* add convert_longitude example notebook

* correct the dataset dimensions in the str method

* add convert_longitude documentations

* update

* update example notebooks

* update methods

* update check list files

HISTORY.rst

@@ -72,3 +72,10 @@ History
 * restructure the no_data_value related functions.
 * plot function can plot rgb imagr for multi-band rasters.
 * to_file detect the driver type from the extension in the path.
+
+0.4.2 (2023-04-27)
+------------------
+* fix bug in plotting dataset without specifying the band
+* fix bug in passing ot not passing band index in case of multi band rasters
+* change the bounds in to_dataset method to total_bounds tp get the bbox of the whole geometries in the gdf
+* add convert_longitude method to convert longitude to range between -180 and 180

README.md

@@ -13,7 +13,8 @@
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/5e3aa4d0acc843d1a91caf33545ecf03)](https://www.codacy.com/gh/Serapieum-of-alex/pyramids/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Serapieum-of-alex/pyramids&utm_campaign=Badge_Grade)
 
 
-![GitHub commits since latest release (by SemVer including pre-releases)](https://img.shields.io/github/commits-since/mafarrag/pyramids/0.4.1?include_prereleases&style=plastic)
+![GitHub commits since latest release (by SemVer including pre-releases)](https://img.shields.
+io/github/commits-since/mafarrag/pyramids/0.4.2?include_prereleases&style=plastic)
 ![GitHub last commit](https://img.shields.io/github/last-commit/mafarrag/pyramids)
 
 Current release info
@@ -29,6 +30,8 @@ pyramids - GIS utility package
 
 pyramids
 
+![1](/docs/images/package-work-flow/overall.png)
+
 Main Features
 -------------
   - GIS modules to enable the modeler to fully prepare the meteorological inputs and do all the preprocessing
@@ -48,7 +51,7 @@ Installing pyramids
 Installing `pyramids` from the `conda-forge` channel can be achieved by:
 
 ```
-conda install -c conda-forge pyramids=0.4.1
+conda install -c conda-forge pyramids=0.4.2
 ```
 
 It is possible to list all of the versions of `pyramids` available on your platform with:
@@ -66,7 +69,7 @@ pip install git+https://github.com/Serapieum-of-alex/pyramids
 ## pip
 to install the last release you can easly use pip
 ```
-pip install pyramids-gis==0.4.1
+pip install pyramids-gis==0.4.2
 ```
 
 Quick start

docs/dataset.rst

@@ -27,13 +27,13 @@ Dataset
 - The main purpose of the `Dataset` object is to deal with raster objects, single or multibands, has variables/subsets
     like netcdf file or has one variable like most GeoTIFF files.
 
-.. image:: /images/dataset.png
+.. image:: /images/dataset/dataset.png
    :width: 200pt
    :align: center
 
 - The `Dataset` object data model is as following
 
-.. image:: /images/dataset-alone.png
+.. image:: /images/schemes/dataset-alone.png
    :width: 700pt
    :alt: Dataset object scheme
    :align: center
@@ -57,7 +57,7 @@ read_file
     dataset.plot(title="Rhine river basin", ticks_spacing=500,cmap="terrain", color_scale=1, vmin=0,
              cbar_label="Elevation (m)")
 
-.. image:: /images/rhine_dem.png
+.. image:: /images/dataset/rhine_dem.png
    :width: 700pt
    :alt: Rhine river basin
    :align: center
@@ -92,7 +92,7 @@ Dataset objest attributes
 - The Dataset object has  the following attributes, which enables you to access all the stored data in you raster
     file (GeoTIFF/NetCDF/ASCII)
 
-.. image:: /images/dataset-arrributes.png
+.. image:: /images/schemes/dataset-arrributes.png
    :width: 150pt
    :alt: dataset attributes
    :align: center
@@ -190,7 +190,7 @@ bounds
 
     dataset.bounds.plot()
 
-.. image:: /images/bounds.png
+.. image:: /images/dataset/bounds.png
    :width: 300pt
    :alt: dataset attributes
    :align: center
@@ -354,7 +354,7 @@ driver_type
 Create Dataset object
 =====================
 
-.. image:: /images/create-object.png
+.. image:: /images/schemes/create-object.png
    :width: 150pt
    :alt: Dataset object scheme
    :align: center
@@ -395,7 +395,7 @@ Returns
     Map.plot(src, title="Flow Accumulation")
 
 
-.. image:: /images/flow_accumulation.png
+.. image:: /images/dataset/flow_accumulation.png
    :width: 500pt
 
 dataset_like
@@ -444,14 +444,14 @@ Returns
     Map.plot(dst, title="Flow Accumulation", color_scale=1)
 
 
-.. image:: /images/raster_like.png
+.. image:: /images/dataset/raster_like.png
    :width: 500pt
 
 
 Access data methods
 ===================
 
-.. image:: /images/access-data.png
+.. image:: /images/schemes/access-data.png
    :width: 150pt
    :alt: Dataset object scheme
    :align: center
@@ -522,7 +522,7 @@ Write raster to disk
 to wtite the dataset object to disk using any of the raster formats (GeoTIFF/NetCDF/ASCII), you can use the `to_file`
 method.
 
-.. image:: /images/write-to-disk.png
+.. image:: /images/schemes/write-to-disk.png
    :width: 350pt
    :alt: Dataset object scheme
    :align: center
@@ -588,11 +588,56 @@ NetCDF
 Spatial properties
 ==================
 
-.. image:: /images/spatial-operation.png
+.. image:: /images/schemes/spatial-operation.png
    :width: 150pt
    :alt: Dataset object scheme
    :align: center
 
+convert_longitude
+-----------------
+- some files (espicially netcdf files) uses longitude values from 0 degrees to 360 degrees, instead of the usual,
+GIS-standard, arrangement of -180 degrees to 180 degrees for longitude centered on the Prime Meridian, and -90 degrees
+to 90 degrees for latitude centered on the Equator. the `convert_longitude` method corrects such behavior.
+
+.. image:: /images/dataset/0-360-longitude-withbase-map.png
+   :width: 600pt
+   :alt: Dataset object scheme
+   :align: center
+
+- read the raster files using the `read_file` and plot it with the `plot` method.
+
+.. code:: py
+
+    dataset = Dataset.read_file(path)
+    fig, ax = dataset.plot(
+        band=0, figsize=(10, 5), title="Noah daily Precipitation 1979-01-01", cbar_label="Raindall mm/day", vmax=30,
+        cbar_length=0.85
+    )
+
+- You cas see how the most left of the map lies the african continent instead of north and south america.
+
+.. image:: /images/dataset/0-360-longitude.png
+   :width: 600pt
+   :alt: Dataset object scheme
+   :align: center
+
+- To correct the values of the longitude you can use the `convert_longitude` as follows.
+
+
+.. code:: py
+
+    new_dataset = dataset.convert_longitude()
+    new_dataset.plot(
+        band=0, figsize=(10, 5), title="Noah daily Precipitation 1979-01-01", cbar_label="Raindall mm/day", vmax=30,
+        cbar_length=0.85
+    )
+
+.. image:: /images/dataset/negative-180-to-180-longitude.png
+   :width: 600pt
+   :alt: Dataset object scheme
+   :align: center
+
+
 resample
 --------
 
@@ -632,7 +677,7 @@ Returns
     New cell size is 100.0
 
 
-.. image:: /images/resample.png
+.. image:: /images/dataset/resample.png
    :width: 500pt
 
 to_crs
@@ -732,7 +777,7 @@ Returns
         ticks_spacing=0.01,
     )
 
-.. image:: /images/before_cropping.png
+.. image:: /images/dataset/before_cropping.png
    :width: 500pt
 
 
@@ -747,7 +792,7 @@ Returns
         ticks_spacing=0.01,
     )
 
-.. image:: /images/cropped_array.png
+.. image:: /images/dataset/cropped_array.png
    :width: 500pt
 
 Crop raster using another raster while preserving the alignment
@@ -762,7 +807,7 @@ Crop raster using another raster while preserving the alignment
     Map.plot(dst_cropped, title="Cropped raster", color_scale=1, ticks_spacing=0.01)
 
 
-.. image:: /images/cropped_aligned_raster.png
+.. image:: /images/dataset/cropped_aligned_raster.png
    :width: 500pt
 
 
@@ -813,7 +858,7 @@ Returns
     Raster EPSG = 32618
     Raster Geotransform = (432968.1206170588, 4000.0, 0.0, 520007.787999178, 0.0, -4000.0)
 
-.. image:: /images/raster_tobe_cropped.png
+.. image:: /images/dataset/raster_tobe_cropped.png
    :width: 500pt
 
 
@@ -831,7 +876,7 @@ Returns
     resulted EPSG = 32618
     resulted Geotransform = (432968.1206170588, 4000.0, 0.0, 520007.787999178, 0.0, -4000.0)
 
-.. image:: /images/cropped_raster.png
+.. image:: /images/dataset/cropped_raster.png
    :width: 500pt
 
 
@@ -867,7 +912,7 @@ Returns
     Before alignment EPSG = 3116
     Before alignment Geotransform = (830606.744300001, 30.0, 0.0, 1011325.7178760837, 0.0, -30.0)
 
-.. image:: /images/soil_map.png
+.. image:: /images/dataset/soil_map.png
    :width: 500pt
 
 
@@ -882,7 +927,7 @@ Returns
     After alignment EPSG = 32618
     After alignment Geotransform = (432968.1206170588, 4000.0, 0.0, 520007.787999178, 0.0, -4000.0)
 
-.. image:: /images/soil_map_aligned.png
+.. image:: /images/dataset/soil_map_aligned.png
    :width: 500pt
 
 
@@ -1000,7 +1045,7 @@ To extract the
 Mathmatical operations
 ======================
 
-.. image:: /images/math-operations.png
+.. image:: /images/schemes/math-operations.png
    :width: 150pt
    :alt: Dataset object scheme
    :align: center
@@ -1042,7 +1087,7 @@ Returns
     dst = Raster.mapAlgebra(src, classify)
     Map.plot(dst, title="Classes", color_scale=4, ticks_spacing=1)
 
-.. image:: /images/map_algebra.png
+.. image:: /images/dataset/map_algebra.png
    :width: 500pt
 
 
@@ -1075,7 +1120,7 @@ Returns
     dst = gdal.Open(path)
     Map.plot(dst, title="Flow Accumulation")
 
-.. image:: /images/raster_fill.png
+.. image:: /images/dataset/raster_fill.png
    :width: 500pt
 
 nearestNeighbour

docs/pyramids.drawio

@@ -1,6 +1,6 @@
-<mxfile host="Electron" modified="2023-04-23T10:17:43.600Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/21.2.1 Chrome/112.0.5615.87 Electron/24.1.2 Safari/537.36" etag="7qx0_KqDHR3rgN7cpdo5" version="21.2.1" type="device" pages="3">
+<mxfile host="Electron" modified="2023-04-26T22:36:00.760Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/21.2.1 Chrome/112.0.5615.87 Electron/24.1.2 Safari/537.36" etag="NcFZObVhQTmZ4yOnu4uv" version="21.2.1" type="device" pages="3">
   <diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">
-    <mxGraphModel dx="3563" dy="1850" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+    <mxGraphModel dx="2618" dy="1270" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
         <mxCell id="WIyWlLk6GJQsqaUBKTNV-0" />
         <mxCell id="WIyWlLk6GJQsqaUBKTNV-1" parent="WIyWlLk6GJQsqaUBKTNV-0" />
@@ -1198,7 +1198,7 @@
           </mxGeometry>
         </mxCell>
         <mxCell id="UqiNyKsmV0SrrWY506cY-38" value="Spatial operations" style="swimlane;fontStyle=0;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeLast=0;collapsible=1;marginBottom=0;rounded=0;shadow=0;strokeWidth=1;" parent="1" vertex="1">
-          <mxGeometry x="437" y="386" width="150" height="298" as="geometry">
+          <mxGeometry x="437" y="386" width="150" height="332" as="geometry">
             <mxRectangle x="340" y="380" width="170" height="26" as="alternateBounds" />
           </mxGeometry>
         </mxCell>
@@ -1226,6 +1226,9 @@
         <mxCell id="5GOtPY5bVLfZRYv8W9gN-30" value="footprint" style="text;align=left;verticalAlign=top;spacingLeft=4;spacingRight=4;overflow=hidden;rotatable=0;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;" parent="UqiNyKsmV0SrrWY506cY-38" vertex="1">
           <mxGeometry y="264" width="150" height="34" as="geometry" />
         </mxCell>
+        <mxCell id="AaWs2XlB7xaZG02dwTga-1" value="convert_longitude" style="text;align=left;verticalAlign=top;spacingLeft=4;spacingRight=4;overflow=hidden;rotatable=0;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;" vertex="1" parent="UqiNyKsmV0SrrWY506cY-38">
+          <mxGeometry y="298" width="150" height="34" as="geometry" />
+        </mxCell>
         <mxCell id="UqiNyKsmV0SrrWY506cY-45" value="" style="endArrow=block;endSize=10;endFill=0;shadow=0;strokeWidth=1;rounded=0;edgeStyle=elbowEdgeStyle;elbow=vertical;" parent="1" source="UqiNyKsmV0SrrWY506cY-38" target="UqiNyKsmV0SrrWY506cY-1" edge="1">
           <mxGeometry width="160" relative="1" as="geometry">
             <mxPoint x="120" y="234" as="sourcePoint" />

environment-optional-packages.yml

@@ -10,7 +10,7 @@ dependencies:
   - geopandas >=0.12.2
   - Shapely >=1.8.4,<2
   - pyproj >=3.4.0
-  - cleopatra >=0.3.2
+  - cleopatra >=0.3.4
   - PyYAML >=6.0
   - loguru >=0.6.0
   - pytest >=7.2.0

examples/data-cube-examples.py

@@ -0,0 +1,13 @@
+import matplotlib
+
+matplotlib.use("TkAgg")
+import numpy as np
+from pyramids.dataset import Datacube
+
+path = "tests/data/raster-folder-coello"
+#%%
+cube = Datacube.read_separate_files(path)
+cube.read_dataset()
+# arr = cube.data
+# np.save(f"{path}/coello.npy",arr)
+cube.plot()