yeesian · yeesian · Jun 24, 2021 · Apr 18, 2021 · Apr 18, 2021 · Apr 18, 2021
diff --git a/.JuliaFormatter.toml b/.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
diff --git a/.github/workflows/format_pr.yml b/.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 }}"
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,6 @@ test/gdalworkshop/
 test/ospy/
 test/pyrasterio/
 test/spatialite/
+.DS_Store
+Manifest.toml
+*.tif
diff --git a/Project.toml b/Project.toml
@@ -6,26 +6,21 @@ 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]
+ColorTypes = "0.10, 0.11"
 DiskArrays = "0.2.4"
 GDAL = "1.1.3"
 GeoFormatTypes = "0.3"
 GeoInterface = "0.4, 0.5"
+ImageCore = "0.8, 0.9"
 Tables = "1"
 julia = "1.3"
-
-[extras]
-Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
-Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
-Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-
-[targets]
-test = ["Dates", "Pkg", "Statistics", "Test"]
diff --git a/README.md b/README.md
@@ -1,12 +1,15 @@
 # ArchGDAL
 [![CI](https://github.com/yeesian/ArchGDAL.jl/workflows/CI/badge.svg)](https://github.com/yeesian/ArchGDAL.jl/actions?query=workflow%3ACI)
 [![Coverage Status](https://coveralls.io/repos/github/yeesian/ArchGDAL.jl/badge.svg?branch=master)](https://coveralls.io/github/yeesian/ArchGDAL.jl?branch=master)
+[![version](https://juliahub.com/docs/ArchGDAL/version.svg)](https://juliahub.com/ui/Packages/ArchGDAL/MCIiB)
 [![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)
+[![deps](https://juliahub.com/docs/ArchGDAL/deps.svg)](https://juliahub.com/ui/Packages/ArchGDAL/MCIiB?t=2)
+[![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 +32,76 @@ To test if it is installed correctly,
 ```julia
 pkg> test ArchGDAL
 ```
+
+## Getting Involved
+
+### Community
+
+This package will not be possible without [JuliaLang](https://julialang.org/), [GDAL](https://github.com/OSGeo/gdal) and [GDAL.jl](https://github.com/JuliaGeo/GDAL.jl). They are maintained by https://julialang.org/community/, https://www.osgeo.org/ and https://juliageo.org/ respectively. 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).
+
+If you wish to format code, `cd` to the ArchGDAL.jl directory, then run:
+```julia
+] add JuliaFormatter
+using JuliaFormatter
+format(".")
+```
+
+### Dependencies
+To manage the dependencies of this package, we work with [environments](https://pkgdocs.julialang.org/v1/environments/):
+
+1. Navigate to the directory corresponding to the package:
+
+```julia
+$ cd /Users/yeesian/.julia/dev/ArchGDAL
+/Users/yeesian/.julia/dev/ArchGDAL
+```
+
+2. Start a session:
+
+```shell
+$ julia --project
+```
+
+3. Activate the environment corresponding to `Project.toml`):
+
+```julia
+(@v1.6) pkg> activate .
+  Activating environment at `~/.julia/environments/v1.6/Project.toml`
+```
+
+4. 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
+```
+
+5. Update the `[compat]` section of `Project.toml` so that julia can resolve the versions, e.g.
+
+```
+[compat]
+...
+CEnum = "0.4"
+```
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -3,6 +3,7 @@ ArchGDAL = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DiskArrays = "3c3547ce-8d99-4f5e-a174-61eb10b00ae3"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GDAL = "add2ef01-049f-52c4-9ee2-e494f65e021a"
 
 [compat]
 Documenter = "0.26.2"
diff --git a/docs/README.md b/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 --project 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.
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,5 +1,12 @@
 using Documenter, ArchGDAL
 
+DocMeta.setdocmeta!(
+    ArchGDAL,
+    :DocTestSetup,
+    :(using ArchGDAL, GDAL);
+    recursive = true,
+)
+
 # make sure you have run the tests before such that the test files are present
 makedocs(
     modules = [ArchGDAL],
@@ -17,15 +24,17 @@ 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",
+        # TODO: Uncomment the following line once we support Spatialite
+        # See https://github.com/JuliaGeo/GDAL.jl/issues/65#issuecomment-493890448.
         # "Working with Spatialite" => "spatialite.md",
         "Interactive versus Scoped Objects" => "memory.md",
         "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")
diff --git a/docs/src/considerations.md b/docs/src/considerations.md
@@ -15,3 +15,84 @@ Here's a collection of references for developers who are interested:
 - [https://github.com/mapbox/rasterio/pull/665](https://github.com/mapbox/rasterio/pull/665)
 - [https://github.com/mapbox/rasterio/issues/875](https://github.com/mapbox/rasterio/issues/875)
 - [https://rasterio.readthedocs.io/en/latest/topics/configuration.html](https://rasterio.readthedocs.io/en/latest/topics/configuration.html)
+
+## GDAL Enum Values
+
+[GDAL.jl](https://github.com/JuliaGeo/GDAL.jl) uses [CEnum.jl](https://github.com/JuliaInterop/CEnum.jl), which is a C-compatible enum, this is the default in [Clang.jl](https://github.com/JuliaInterop/Clang.jl). This is useful when the underlying values are of interest, for example the following snippets from [`src/types.jl`](https://github.com/yeesian/ArchGDAL.jl/blob/master/src/types.jl):
+
+```julia
+import Base.|
+
+for T in (GDALOpenFlag, FieldValidation)
+    eval(quote
+        |(x::$T, y::UInt8) = UInt8(x) | y
+        |(x::UInt8, y::$T) = x | UInt8(y)
+        |(x::$T, y::$T) = UInt8(x) | UInt8(y)
+    end)
+end
+```
+
+and
+
+```julia
+function basetype(gt::OGRwkbGeometryType)::OGRwkbGeometryType
+    wkbGeomType = convert(GDAL.OGRwkbGeometryType, gt)
+    wkbGeomType &= (~0x80000000) # Remove 2.5D flag.
+    wkbGeomType %= 1000 # Normalize Z, M, and ZM types.
+    return GDAL.OGRwkbGeometryType(wkbGeomType)
+end
+```
+
+However, the use of CEnum.jl allows for multiple enums to have the same underlying value, resulting in unintuitive behavior if they are used as keys in a dictionary. For example, in the following code:
+
+```julia
+julia> Dict(GDAL.GCI_YCbCr_CrBand => "a", GDAL.GCI_Max => "b")
+Dict{GDAL.GDALColorInterp, String} with 1 entry:
+  GCI_YCbCr_CrBand => "b"
+```
+
+the entry for `GDAL.GCI_YCbCr_CrBand => "a"` got overwritten by `GDAL.GCI_Max => "b"` because both `GDAL.GCI_YCbCr_CrBand` and `GDAL.GCI_Max` corresponded to the same value.
+
+To avoid such forms of behavior, this package uses [`Base.Enums`](https://docs.julialang.org/en/v1/base/base/#Base.Enums.Enum) instead, so the above example would result in the following behavior:
+
+
+```julia
+julia> Dict(ArchGDAL.GCI_YCbCr_CrBand => "a", ArchGDAL.GCI_Max => "b")
+Dict{ArchGDAL.GDALColorInterp, String} with 2 entries:
+  GCI_YCbCr_CrBand => "a"
+  GCI_Max          => "b"
+```
+
+To maintain parity with GDAL behavior, ArchGDAL.jl provides conversion methods to map from the enums in ArchGDAL to the corresponding cenums from GDAL.jl when calling the corresponding GDAL functions.
+
+## Colors
+
+Rather than encouraging [operations on colortables](https://gdal.org/python/osgeo.gdal.ColorTable-class.html) (with very limited functionality from GDAL), users are better served by arrays of [ColorTypes](https://github.com/JuliaGraphics/ColorTypes.jl) using [Colors.jl](https://github.com/JuliaGraphics/Colors.jl), [for example](http://juliagraphics.github.io/Colors.jl/stable/colormapsandcolorscales/#Generating-a-range-of-colors)
+
+```julia
+range(startcolor, stop=endcolor, length=15)
+```
+
+instead of
+
+```julia
+createcolorramp!(colortable, startindex, startcolor, startindex+15, endcolor)
+```
+
+## Images
+
+To differentiate 2d arrays of colors from 3d arrays with band as the third dimension:
+
+* For 2D arrays (a single rasterband), if they have a color interpretation, we use the color interpretation. If they don't have a color interpretation, ArchGDAL.jl defaults to "Grey".
+* For >2D arrays (multiple rasterbands), if they have a palette interpretation (or combination of color interpretations) that resolves to a valid colortype, ArchGDAL.jl uses the palette interpretation. If they don't have a palette interpretation, we throw an error.
+
+In general, `read()` will return `Array{UInt8}`, and `imread()` will return `Array{<:Colorant}`.
+
+## Tables.jl Interface
+
+The interface is implemented in [`src/tables.jl`](https://github.com/yeesian/ArchGDAL.jl/blob/master/src/tables.jl), and is only for feature and geometries in OGR (and not for images and rasters). The current API from GDAL makes it row-based in the conventions of Tables.jl. Therefore,
+
+* `ArchGDAL.Feature` meets the criteria for an [`AbstractRow`](https://tables.juliadata.org/dev/#Tables.AbstractRow-1) based on https://github.com/yeesian/ArchGDAL.jl/blob/a665f3407930b8221269f8949c246db022c3a85c/src/tables.jl#L31-L58.
+* `ArchGDAL.FeatureLayer` meets the criteria for an `AbstractRow`-iterator based on the previous bullet and meeting the criteria for [`Iteration`](https://docs.julialang.org/en/v1/manual/interfaces/#man-interface-iteration) in [`base/iterators.jl`](https://github.com/yeesian/ArchGDAL.jl/blob/a665f3407930b8221269f8949c246db022c3a85c/src/base/iterators.jl#L1-L18).
+* `ArchGDAL.AbstractDataset` might contain multiple layers, and might correspond to multiple tables. The way to construct tables would be to get the layers before forming the corresponding tables.
+
diff --git a/docs/src/conventions.md b/docs/src/conventions.md
diff --git a/docs/src/geometries.md b/docs/src/geometries.md
@@ -2,7 +2,6 @@
 
 ```@setup geometries
 using ArchGDAL
-const AG = ArchGDAL
 ```
 
 In this section, we consider some of the common kinds of geometries that arises in applications. These include `Point`, `LineString`, `Polygon`, `GeometryCollection`, `MultiPolygon`, `MultiPoint`, and `MultiLineString`. For brevity in the examples, we will use the prefix `const AG = ArchGDAL`.
@@ -11,53 +10,53 @@ In this section, we consider some of the common kinds of geometries that arises
 To create geometries of different types, 
 
 ```@example geometries
-point = AG.createpoint(1.0, 2.0)
-linestring = AG.createlinestring([(i,i+1) for i in 1.0:3.0])
-linearring = AG.createlinearring([(0.,0.), (0.,1.), (1.,1.)])
-simplepolygon = AG.createpolygon([(0.,0.), (0.,1.), (1.,1.)])
-complexpolygon = AG.createpolygon([[(0.,0.), (0.,j), (j,j)] for j in 1.0:-0.1:0.9])
-multipoint = AG.createlinearring([(0.,0.), (0.,1.), (1.,1.)])
-multilinestring = AG.createmultilinestring([[(i,i+1) for i in j:j+3] for j in 1.0:5.0:6.0])
-multipolygon = AG.createmultipolygon([[[(0.,0.), (0.,j), (j,j)]] for j in 1.0:-0.1:0.9])
+point = ArchGDAL.createpoint(1.0, 2.0)
+linestring = ArchGDAL.createlinestring([(i,i+1) for i in 1.0:3.0])
+linearring = ArchGDAL.createlinearring([(0.,0.), (0.,1.), (1.,1.)])
+simplepolygon = ArchGDAL.createpolygon([(0.,0.), (0.,1.), (1.,1.)])
+complexpolygon = ArchGDAL.createpolygon([[(0.,0.), (0.,j), (j,j)] for j in 1.0:-0.1:0.9])
+multipoint = ArchGDAL.createlinearring([(0.,0.), (0.,1.), (1.,1.)])
+multilinestring = ArchGDAL.createmultilinestring([[(i,i+1) for i in j:j+3] for j in 1.0:5.0:6.0])
+multipolygon = ArchGDAL.createmultipolygon([[[(0.,0.), (0.,j), (j,j)]] for j in 1.0:-0.1:0.9])
 ```
 
 Alternatively, they can be assembled from their components.
 ```@example geometries
-point = AG.createpoint()
-AG.addpoint!(point, 1.0, 2.0)
+point = ArchGDAL.createpoint()
+ArchGDAL.addpoint!(point, 1.0, 2.0)
 
-linestring = AG.createlinestring()
+linestring = ArchGDAL.createlinestring()
 for i in 1.0:3.0
-    AG.addpoint!(linestring, i, i+1)
+    ArchGDAL.addpoint!(linestring, i, i+1)
 end
 
-linearring = AG.createlinearring()
+linearring = ArchGDAL.createlinearring()
 for i in 1.0:3.0
-    AG.addpoint!(linearring, i, i+1)
+    ArchGDAL.addpoint!(linearring, i, i+1)
 end
 
-polygon = AG.createpolygon()
+polygon = ArchGDAL.createpolygon()
 for j in 1.0:-0.1:0.9
-    ring = AG.createlinearring([(0.,0.), (0.,j), (j,j)])
-    AG.addgeom!(polygon, ring)
+    ring = ArchGDAL.createlinearring([(0.,0.), (0.,j), (j,j)])
+    ArchGDAL.addgeom!(polygon, ring)
 end
 
-multipoint = AG.createmultipoint()
+multipoint = ArchGDAL.createmultipoint()
 for i in 1.0:3.0
-    pt = AG.createpoint(i, i+1)
-    AG.addgeom!(multipoint, pt)
+    pt = ArchGDAL.createpoint(i, i+1)
+    ArchGDAL.addgeom!(multipoint, pt)
 end
 
-multilinestring = AG.createmultilinestring()
+multilinestring = ArchGDAL.createmultilinestring()
 for j in 1.0:5.0:6.0
-    line = AG.createlinestring([(i,i+1) for i in j:j+3])
-    AG.addgeom!(multilinestring, line)
+    line = ArchGDAL.createlinestring([(i,i+1) for i in j:j+3])
+    ArchGDAL.addgeom!(multilinestring, line)
 end
 
-multipolygon = AG.createmultipolygon()
+multipolygon = ArchGDAL.createmultipolygon()
 for j in 1.0:-0.1:0.9
-    poly = AG.createpolygon([(0.,0.), (0.,j), (j,j)])
-    AG.addgeom!(multipolygon, poly)
+    poly = ArchGDAL.createpolygon([(0.,0.), (0.,j), (j,j)])
+    ArchGDAL.addgeom!(multipolygon, poly)
 end
 ```