[Breaking] Maintain a closed environment of GDAL-compatible types

.JuliaFormatter.toml

@@ -0,0 +1,8 @@
+# Configuration file for JuliaFormatter.jl
+# For more information, see: https://domluna.github.io/JuliaFormatter.jl/stable/config/
+
+always_for_in = true
+always_use_return = true
+margin = 80
+remove_extra_newlines = true
+short_to_long_function_def = true

.github/workflows/format_check.yml

@@ -0,0 +1,31 @@
+name: format-check
+on:
+  push:
+    branches:
+      - master
+      - release-*
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - uses: actions/checkout@v1
+      - name: Format check
+        shell: julia --color=yes {0}
+        run: |
+          using Pkg
+          # If you update the version, also update the style guide docs.
+          Pkg.add(PackageSpec(name="JuliaFormatter", version="0.13.10"))
+          using JuliaFormatter
+          format("src", verbose=true)
+          out = String(read(Cmd(`git diff`)))
+          if isempty(out)
+              exit(0)
+          end
+          @error "Some files have not been formatted !!!"
+          write(stdout, out)
+          exit(1)

.github/workflows/format_pr.yml

@@ -0,0 +1,30 @@
+name: format-pr
+on:
+  schedule:
+    - cron: '0 0 * * *'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install JuliaFormatter and format
+        run: |
+          julia  -e 'import Pkg; Pkg.add("JuliaFormatter")'
+          julia  -e 'using JuliaFormatter; format(".")'
+
+      # https://github.com/marketplace/actions/create-pull-request
+      # https://github.com/peter-evans/create-pull-request#reference-example
+      - name: Create Pull Request
+        id: cpr
+        uses: peter-evans/create-pull-request@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: Format .jl files
+          title: 'Automatic JuliaFormatter.jl run'
+          branch: auto-juliaformatter-pr
+          delete-branch: true
+          labels: formatting, automated pr, no changelog
+      - name: Check outputs
+        run: |
+          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
+          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

.gitignore

@@ -12,3 +12,5 @@ test/gdalworkshop/
 test/ospy/
 test/pyrasterio/
 test/spatialite/
+.DS_Store
+Manifest.toml

Project.toml

@@ -6,11 +6,13 @@ desc = "A high level API for GDAL - Geospatial Data Abstraction Library"
 version = "0.6.0"
 
 [deps]
+ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 DiskArrays = "3c3547ce-8d99-4f5e-a174-61eb10b00ae3"
 GDAL = "add2ef01-049f-52c4-9ee2-e494f65e021a"
 GeoFormatTypes = "68eda718-8dee-11e9-39e7-89f7f65f511f"
 GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
+ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 
 [compat]
@@ -23,9 +25,11 @@ julia = "1.3"
 
 [extras]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+SHA = "ea8e919c-243c-51af-8825-aaa63cd721ce"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Dates", "Pkg", "Statistics", "Test"]
+test = ["Dates", "Downloads", "Pkg", "Statistics", "SHA", "Test"]

README.md

@@ -3,10 +3,11 @@
 [![Coverage Status](https://coveralls.io/repos/github/yeesian/ArchGDAL.jl/badge.svg?branch=master)](https://coveralls.io/github/yeesian/ArchGDAL.jl?branch=master)
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://yeesian.com/ArchGDAL.jl/stable)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://yeesian.com/ArchGDAL.jl/dev)
+[![ColPrac: Contributor's Guide](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 
 [GDAL](http://gdal.org/) is a translator library for raster and vector geospatial data formats that is released under an [X/MIT](https://trac.osgeo.org/gdal/wiki/FAQGeneral#WhatlicensedoesGDALOGRuse) license by the [Open Source Geospatial Foundation](http://www.osgeo.org/). As a library, it presents an abstract data model to drivers for various [raster](http://www.gdal.org/formats_list.html) and [vector](http://www.gdal.org/ogr_formats.html) formats.
 
-This package aims to be a complete solution for working with GDAL in Julia, similar in scope to [the SWIG bindings for Python](https://pypi.python.org/pypi/GDAL/). It builds on top of [GDAL.jl](https://github.com/JuliaGeo/GDAL.jl), and provides a high level API for GDAL, espousing the following principles.
+This package aims to be a complete solution for working with GDAL in Julia, similar in scope to [the SWIG bindings for Python](https://pypi.python.org/pypi/GDAL/) and the user-friendliness of [Fiona](https://github.com/Toblerity/Fiona) and [Rasterio](https://github.com/mapbox/rasterio). It builds on top of [GDAL.jl](https://github.com/JuliaGeo/GDAL.jl), and provides a high level API for GDAL, espousing the following principles.
 
 ## Principles (The Arch Way)
 (adapted from: https://wiki.archlinux.org/index.php/Arch_Linux#Principles)
@@ -29,3 +30,64 @@ To test if it is installed correctly,
 ```julia
 pkg> test ArchGDAL
 ```
+
+## Getting Involved
+
+### Community
+
+This package will not be possible without https://julialang.org/, https://github.com/OSGeo/gdal and https://github.com/JuliaGeo/GDAL.jl. They are maintained by https://julialang.org/community/, https://www.osgeo.org/ and https://juliageo.org/. In case of any contention for support and involvement, we encourage participation and contributions to those projects and communities over this package.
+
+### Style Guide
+
+ArchGDAL.jl uses [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl) as
+an autoformatting tool, and uses the options in [`.JuliaFormatter.toml`](https://github.com/yeesian/ArchGDAL.jl/blob/master/.JuliaFormatter.toml).
+
+To format code, `cd` to the ArchGDAL.jl directory, then run:
+```julia
+] add [email protected]
+using JuliaFormatter
+format("src")
+```
+
+A continuous integration check verifies that all PRs made to ArchGDAL.jl have passed the formatter.
+
+### Dependencies
+To manage the dependencies of this package, we work with [environments](https://pkgdocs.julialang.org/v1.6/environments/):
+
+1. Navigate to the directory corresponding to the package:
+
+```julia
+shell> cd /Users/yeesian/.julia/dev/ArchGDAL
+/Users/yeesian/.julia/dev/ArchGDAL
+```
+
+2. Activate the environment corresponding to `Project.toml`):
+
+```julia
+(@v1.6) pkg> activate .
+  Activating environment at `~/.julia/environments/v1.6/Project.toml`
+```
+
+3. Manage the dependencies using Pkg in https://pkgdocs.julialang.org/v1.6/managing-packages/, e.g.
+
+```julia
+(ArchGDAL) pkg> st
+     Project ArchGDAL v0.6.0
+      Status `~/.julia/dev/ArchGDAL/Project.toml`
+  [3c3547ce] DiskArrays
+  [add2ef01] GDAL
+  [68eda718] GeoFormatTypes
+  [cf35fbd7] GeoInterface
+  [bd369af6] Tables
+  [ade2ca70] Dates
+
+(ArchGDAL) pkg> add CEnum
+   Resolving package versions...
+    Updating `~/.julia/dev/ArchGDAL/Project.toml`
+  [fa961155] + CEnum v0.4.1
+  [3c3547ce] + DiskArrays v0.2.7
+  [add2ef01] + GDAL v1.2.1
+  [68eda718] + GeoFormatTypes v0.3.0
+  [cf35fbd7] + GeoInterface v0.5.5
+  [bd369af6] + Tables v1.4.2
+```

docs/README.md

@@ -0,0 +1,9 @@
+# ArchGDAL.jl documentation
+
+The latest stable version of the documentation can be viewed at https://yeesian.com/ArchGDAL.jl/stable/. To build a local version of the documentation, navigate to this directory and run the following command:
+
+```shell
+$ julia make.jl
+```
+
+It should create files in a subdirectory named `build/`. If it builds successfully, you should be able to preview the documentation in a browser by opening `build/index.html` in a browser.

docs/make.jl

@@ -17,6 +17,7 @@ makedocs(
         "GDAL Datasets" => "datasets.md",
         "Feature Data" => "features.md",
         "Raster Data" => "rasters.md",
+        "Working with Images" => "images.md",
         "Tables Interface" => "tables.md",
         "Geometric Operations" => "geometries.md",
         "Spatial Projections" => "projections.md",
@@ -25,7 +26,7 @@ makedocs(
         "Design Considerations" => "considerations.md",
         "API Reference" => "reference.md",
         # "Naming Conventions" => "conventions.md", # table between GDAL, GDAL.jl, and ArchGDAL.jl
-    ]
+    ],
 )
 
 deploydocs(; repo = "github.com/yeesian/ArchGDAL.jl.git")

docs/src/images.md

@@ -0,0 +1,53 @@
+# Images
+
+```@setup rasters
+using ArchGDAL
+const AG = ArchGDAL
+```
+
+In this section, we revisit the [`gdalworkshop/world.tif`](https://github.com/yeesian/ArchGDALDatasets/blob/307f8f0e584a39a050c042849004e6a2bd674f99/gdalworkshop/world.tif) dataset.
+```@example rasters
+dataset = AG.read("gdalworkshop/world.tif")
+```
+A description of the display is available in [Raster Datasets](@ref).
+
+## Reading from Datasets
+We can construct an image from it in the following way:
+```@example rasters
+AG.imread(dataset)
+```
+
+## Reading from Files
+We can read the file as an image instead:
+```@example rasters
+AG.imread("gdalworkshop/world.tif")
+```
+
+## Reading from Rasterbands
+We can also read from individual raster bands:
+```@example rasters
+AG.imread(AG.getband(dataset, 1))
+```
+Or equivalently,
+```@example rasters
+AG.imread(dataset, 1)
+```
+It will interpret the color channel (for RGB) correctly there is one. E.g.
+```@example rasters
+AG.imread(dataset, 2)
+```
+and
+```@example rasters
+AG.imread(dataset, 3)
+```
+
+## Working with Colors
+Operations on colors behave as you think they might:
+```@example rasters
+AG.imread(dataset, 2) + AG.imread(dataset, 3)
+```
+and
+```@example rasters
+0.5 * AG.imread(dataset, 1) + AG.imread(dataset, 3)
+```
+See [Colors.jl](http://juliagraphics.github.io/Colors.jl/stable/) for more on what you can do.

docs/src/memory.md

@@ -41,14 +41,14 @@ end
 under the hood (see `src/context.jl`). Therefore, the objects themselves do not have a finalizer registered:
 ```julia
 mutable struct RasterBand <: AbstractRasterBand
-    ptr::GDALRasterBand
+    ptr::GDAL.GDALRasterBandH
 end
 
 unsafe_getband(dataset::AbstractDataset, i::Integer) =
     RasterBand(GDAL.getrasterband(dataset.ptr, i))
 
 function destroy(rb::AbstractRasterBand)
-    rb.ptr = GDALRasterBand(C_NULL)
+    rb.ptr = C_NULL
 end
 ```
 
@@ -65,11 +65,11 @@ rasterband = ArchGDAL.getband(dataset, i)
 returns an interactive rasterband that has `destroy()` registered with its finalizer.
 ```julia
 mutable struct IRasterBand <: AbstractRasterBand
-    ptr::GDALRasterBand
+    ptr::GDAL.GDALRasterBandH
     ownedby::AbstractDataset
 
     function IRasterBand(
-            ptr::GDALRasterBand = GDALRasterBand(C_NULL);
+            ptr::GDAL.GDALRasterBandH = C_NULL;
             ownedby::AbstractDataset = Dataset()
         )
         rasterband = new(ptr, ownedby)
@@ -82,7 +82,7 @@ getband(dataset::AbstractDataset, i::Integer) =
     IRasterBand(GDAL.getrasterband(dataset.ptr, i), ownedby = dataset)
 
 function destroy(rasterband::IRasterBand)
-    rasterband.ptr = GDALRasterBand(C_NULL)
+    rasterband.ptr = C_NULL
     rasterband.ownedby = Dataset()
     return rasterband
 end

docs/src/reference.md

@@ -4,7 +4,7 @@
 
 ```@autodocs
 Modules = [ArchGDAL]
-Pages   = ["ArchGDAL.jl", "display.jl", "iterators.jl", "gcp.jl", "types.jl", "utils.jl"]
+Pages   = ["ArchGDAL.jl", "display.jl", "iterators.jl", "types.jl", "utils.jl"]
 ```
 
 ## [GDAL Datasets](@id API-GDAL-Datasets)
@@ -34,13 +34,20 @@ Modules = [ArchGDAL]
 Pages   = ["array.jl", "colortable.jl", "rasterattributetable.jl", "rasterband.jl", "rasterio.jl"]
 ```
 
-## [Spatial projections](@id API-Spatial-projections)
+## [Spatial Projections](@id API-Spatial-Projections)
 
 ```@autodocs
 Modules = [ArchGDAL]
 Pages   = ["spatialref.jl"]
 ```
 
+## [Geo Transformations](@id API-GeoTransforms)
+
+```@autodocs
+Modules = [ArchGDAL]
+Pages   = ["geotransform.jl"]
+```
+
 ## [Utilities](@id API-Utilities)
 
 ```@autodocs

docs/src/tables.md

@@ -28,21 +28,7 @@ The [`ArchGDAL.Table`](@ref) method accepts an `ArchGDAL.FeatureLayer`.
 table = ArchGDAL.Table(layer)
 ```
 
-Individual rows can be retrieved using the `Base.getindex(t::ArchGDAL.Table, idx::Int)` method or simply `table[idx]`.
-
-```@example tables
-row = table[1]
-```
-
-Layers are retrievable!
-One can get back the layer that a Table is made up of.
-```@example tables
-lyr = ArchGDAL.getlayer(table)
-```
-
-The Tables interface also support multiple geometries per layer.
-
-Here, we visit the
+Finally layers can be converted to DataFrames to perform miscellaneous spatial operations. Here, we visit the
 [`data/multi_geom.csv`](https://github.com/yeesian/ArchGDALDatasets/blob/master/data/multi_geom.csv)
 dataset.
 
@@ -51,22 +37,7 @@ dataset1 = ArchGDAL.read("data/multi_geom.csv", options = ["GEOM_POSSIBLE_NAMES=
 
 layer = ArchGDAL.getlayer(dataset, 0)
 table = ArchGDAL.Table(layer)
-```
-
-Exatracting a row from the table, we see that the row/feature is made up of two geometries
-viz. `point` and `linestring`.
-```@example tables
-row = table[1]
-```
-
-Finally layers can be converted to DataFrames to perform miscellaneous spatial operations.
-```@example tables
 df = DataFrame(table)
 ```
-In some cases the `nextfeature` might become a bit tedious to use. In which case the `ArchGDAL.nextnamedtuple()` method comes in handy. Though built upon `nextfeature`, simply calling it, yields the `feature` as a `NamedTuple`. Though one might have to use `ArchGDAL.resetreading!(layer)` method to reset the layer reading to the start.
 
-```@example tables
-ArchGDAL.resetreading!(layer)
-feat1 = ArchGDAL.nextnamedtuple(layer)
-feat2 = ArchGDAL.nextnamedtuple(layer)
-```
+The Tables interface also supports multiple geometries per layer.