From 0164606188fee8c4afd014fbc335bf40c44daf5a Mon Sep 17 00:00:00 2001 From: adigitoleo Date: Mon, 17 Jan 2022 23:47:55 +1100 Subject: [PATCH 1/2] refactor: Rework parametric types for more flexibility First step for #806. Example use case: `mat2grid(transpose([1 2 3; 4 5 6]))` Also added docstrings to the types which can later be automatically included into the documentation[1]. [1]: https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@docs-block --- src/blendimg.jl | 2 +- src/gmt_main.jl | 211 ++++++++++++++++++++++++++++++---------- src/precompile_GMT_i.jl | 10 +- 3 files changed, 166 insertions(+), 57 deletions(-) diff --git a/src/blendimg.jl b/src/blendimg.jl index 63c8288a64..787c22cc6e 100644 --- a/src/blendimg.jl +++ b/src/blendimg.jl @@ -20,7 +20,7 @@ Blend two 2D UInt8 or 2 RGB images using transparency. ### Returns A GMT intensity Image """ -function blendimg!(color::GMTimage{UInt8, 3}, shade::GMTimage{UInt8, 2}; new=false) +function blendimg!(color::GMTimage{AbstractArray{UInt8, 3}}, shade::GMTimage{AbstractArray{UInt8, 2}}; new=false) blend = (new) ? Array{UInt8,3}(undef, size(shade,1), size(shade,2), 3) : color.image diff --git a/src/gmt_main.jl b/src/gmt_main.jl index 6cbb5f569b..18b5d67864 100644 --- a/src/gmt_main.jl +++ b/src/gmt_main.jl @@ -1,4 +1,36 @@ -Base.@kwdef mutable struct GMTgrid{T<:Real,N} <: AbstractArray{T,N} +""" + GMTgrid(fields...) + +Construct a GMT grid from data using optional header information. + +# Fields + +- `proj4::String` Projection string in PROJ4 syntax (Optional) +- `wkt::String` Projection string in WKT syntax (Optional) +- `epsg::Int` EPSG code +- `range::Array{Float64,1}` 1x6[8] vector with [x_min, x_max, y_min, y_max, z_min, z_max [, v_min, v_max]] +- `inc::Array{Float64,1}` 1x2[3] vector with [x_inc, y_inc [,v_inc]] +- `registration::Int` Registration type: 0 -> Grid registration; 1 -> Pixel registration +- `nodata::Float64` The value of nodata +- `title::String` Title (Optional) +- `comment::String` Remark (Optional) +- `command::String` Command used to create the grid (Optional) +- `names::Vector{String}` To use whith multi-layered and when layers have names (Optional) +- `x::Array{Float64,1}` [1 x n_columns] vector with XX coordinates +- `y::Array{Float64,1}` [1 x n_rows] vector with YY coordinates +- `v::Array{Float64,1}` [v x n_bands] vector with VV (vertical for 3D grids) coordinates +- `z::Array{Float32,2}` [n_rows x n_columns] grid array +- `x_units::String` Units of XX axis (Optional) +- `y_units::String` Units of YY axis (Optional) +- `v_units::String` Units of Vertical axis (Optional) +- `z_units::String` Units of z vlues (Optional) +- `layout::String` A three character string describing the grid memory layout +- `scale::Union{Float64,Float32}` When saving in file apply `z = z * scale + offset` +- `offset::Union{Float64,Float32}` +- `pad::Int` When != 0 means that the array is placed in a padded array of PAD rows/cols + +""" +Base.@kwdef mutable struct GMTgrid{T<:AbstractArray} proj4::String wkt::String epsg::Int @@ -13,7 +45,7 @@ Base.@kwdef mutable struct GMTgrid{T<:Real,N} <: AbstractArray{T,N} x::Array{Float64,1} y::Array{Float64,1} v::Union{Vector{<:Real}, Vector{String}} - z::Array{T,N} + z::T x_unit::String y_unit::String v_unit::String @@ -24,14 +56,14 @@ Base.@kwdef mutable struct GMTgrid{T<:Real,N} <: AbstractArray{T,N} pad::Int=0 end Base.size(G::GMTgrid) = size(G.z) -Base.getindex(G::GMTgrid{T,N}, inds::Vararg{Int,N}) where {T,N} = G.z[inds...] -Base.setindex!(G::GMTgrid{T,N}, val, inds::Vararg{Int,N}) where {T,N} = G.z[inds...] = val +Base.getindex(G::GMTgrid, inds::Vararg{Int,N}) where N = G.z[inds...] +Base.setindex!(G::GMTgrid, val, inds::Vararg{Int,N}) where N = G.z[inds...] = val -Base.BroadcastStyle(::Type{<:GMTgrid}) = Broadcast.ArrayStyle{GMTgrid}() -function Base.similar(bc::Broadcast.Broadcasted{Broadcast.ArrayStyle{GMTgrid}}, ::Type{ElType}) where ElType - G = find4similar(bc.args) # Scan the inputs for the GMTgrid: - GMTgrid(G.proj4, G.wkt, G.epsg, G.range, G.inc, G.registration, G.nodata, G.title, G.remark, G.command, G.names, G.x, G.y, G.v, similar(Array{ElType}, axes(bc)), G.x_unit, G.y_unit, G.v_unit, G.z_unit, G.layout, 1f0, 0f0, G.pad) -end +#Base.BroadcastStyle(::Type{<:GMTgrid}) = Broadcast.ArrayStyle{GMTgrid}() +#function Base.similar(bc::Broadcast.Broadcasted{Broadcast.ArrayStyle{GMTgrid}}, ::Type{ElType}) where ElType +# G = find4similar(bc.args) # Scan the inputs for the GMTgrid: +# GMTgrid(G.proj4, G.wkt, G.epsg, G.range, G.inc, G.registration, G.nodata, G.title, G.remark, G.command, G.names, G.x, G.y, G.v, similar(Array{ElType}, axes(bc)), G.x_unit, G.y_unit, G.v_unit, G.z_unit, G.layout, 1f0, 0f0, G.pad) +#end find4similar(bc::Base.Broadcast.Broadcasted) = find4similar(bc.args) find4similar(args::Tuple) = find4similar(find4similar(args[1]), Base.tail(args)) @@ -40,7 +72,35 @@ find4similar(::Tuple{}) = nothing find4similar(G::GMTgrid, rest) = G find4similar(::Any, rest) = find4similar(rest) -mutable struct GMTimage{T<:Unsigned, N} <: AbstractArray{T,N} +""" + GMTimage(fields...) + +Construct a GMT image from data using optional header information. + +# Fields + + +- `proj4::String` Projection string in PROJ4 syntax (Optional) +- `wkt::String` Projection string in WKT syntax (Optional) +- `epsg::Int` EPSG code +- `range::Array{Float64,1}` 1x6 vector with [x_min x_max y_min y_max z_min z_max] +- `inc::Array{Float64,1}` 1x2 vector with [x_inc y_inc] +- `registration::Int` Registration type: 0 -> Grid registration; 1 -> Pixel registration +- `nodata::Unsigned` The value of nodata +- `color_interp::String` If equal to "Gray" an indexed image with no cmap will get a gray cmap +- `metadata::Vector{String}` To store any metadata that can eventually be passed to GDAL (Optional) +- `names::Vector{String}` To use whith multi-band and when bands have names (Optional) +- `x::Array{Float64,1}` [1 x n_columns] vector with XX coordinates +- `y::Array{Float64,1}` [1 x n_rows] vector with YY coordinates +- `v::Array{Float64,1}` [v x n_bands] vector with vertical coords or wavelengths in hypercubes (Optional) +- `image::Array{T,N}` [n_rows x n_columns x n_bands] image array +- `colormap::Array{Int32,1}` +- `alpha::Array{UInt8,2}` A [n_rows x n_columns] alpha array +- `layout::String` A four character string describing the image memory layout +- `pad::Int` When != 0 means that the array is placed in a padded array of PAD rows/cols + +""" +mutable struct GMTimage{T<:AbstractArray{T1} where T1 <: Unsigned} proj4::String wkt::String epsg::Int @@ -54,7 +114,7 @@ mutable struct GMTimage{T<:Unsigned, N} <: AbstractArray{T,N} x::Array{Float64,1} y::Array{Float64,1} v::Array{Float64,1} - image::Array{T,N} + image::T colormap::Array{Int32,1} n_colors::Int alpha::Array{UInt8,2} @@ -62,46 +122,95 @@ mutable struct GMTimage{T<:Unsigned, N} <: AbstractArray{T,N} pad::Int end Base.size(I::GMTimage) = size(I.image) -Base.getindex(I::GMTimage{T,N}, inds::Vararg{Int,N}) where {T,N} = I.image[inds...] -Base.setindex!(I::GMTimage{T,N}, val, inds::Vararg{Int,N}) where {T,N} = I.image[inds...] = val - -Base.BroadcastStyle(::Type{<:GMTimage}) = Broadcast.ArrayStyle{GMTimage}() -function Base.similar(bc::Broadcast.Broadcasted{Broadcast.ArrayStyle{GMTimage}}, ::Type{ElType}) where ElType - I = find4similar(bc.args) # Scan the inputs for the GMTimage: - GMTimage(I.proj4, I.wkt, I.epsg, I.range, I.inc, I.registration, I.nodata, I.color_interp, I.metadata, I.names, I.x, I.y, I.v, similar(Array{ElType}, axes(bc)), I.colormap, I.n_colors, I.alpha, I.layout, I.pad) -end +Base.getindex(I::GMTimage, inds::Vararg{Int,N}) where N = I.image[inds...] +Base.setindex!(I::GMTimage, val, inds::Vararg{Int,N}) where N = I.image[inds...] = val + +#Base.BroadcastStyle(::Type{<:GMTimage}) = Broadcast.ArrayStyle{GMTimage}() +#function Base.similar(bc::Broadcast.Broadcasted{Broadcast.ArrayStyle{GMTimage}}, ::Type{ElType}) where ElType +# I = find4similar(bc.args) # Scan the inputs for the GMTimage: +# GMTimage(I.proj4, I.wkt, I.epsg, I.range, I.inc, I.registration, I.nodata, I.color_interp, I.metadata, I.names, I.x, I.y, I.v, similar(Array{ElType}, axes(bc)), I.colormap, I.n_colors, I.alpha, I.layout, I.pad) +#end find4similar(I::GMTimage, rest) = I +""" + GMTcpt(fields...) + +Construct a GMT [CPT] from data using optional header information. +- `colormap::Array{Float64,2}` Mx3 matrix equal to the first three columns of cpt +- `alpha::Array{Float64,1}` Vector of alpha values. One for each color. +- `range::Array{Float64,2}` Mx2 matrix with z range for each slice +- `minmax::Array{Float64,1}` Two elements Vector with zmin,zmax +- `bfn::Array{Float64,2}` A 3x3(4?) matrix with BFN colors (one per row) in [0 1] interval +- `depth::Cint` Color depth 24, 8, 1 +- `hinge::Cdouble` Z-value at discontinuous color break, or NaN +- `cpt::Array{Float64,2}` Mx6 matrix with r1 g1 b1 r2 g2 b2 for z1 z2 of each slice +- `label::Vector{String}` Labels of a Categorical CPT +- `key::Vector{String}` Keys of a Categorical CPT +- `model::String` String with color model rgb, hsv, or cmyk [rgb] +- `comment::Array{String,1}` Cell array with any comments + +[CPT]: https://docs.generic-mapping-tools.org/latest/cookbook/cpts.html + +""" mutable struct GMTcpt - colormap::Array{Float64,2} # Mx3 matrix equal to the first three columns of cpt - alpha::Array{Float64,1} # Vector of alpha values. One for each color. - range::Array{Float64,2} # Mx2 matrix with z range for each slice - minmax::Array{Float64,1} # Two elements Vector with zmin,zmax - bfn::Array{Float64,2} # A 3x3(4?) matrix with BFN colors (one per row) in [0 1] interval - depth::Cint # Color depth 24, 8, 1 - hinge::Cdouble # Z-value at discontinuous color break, or NaN - cpt::Array{Float64,2} # Mx6 matrix with r1 g1 b1 r2 g2 b2 for z1 z2 of each slice - label::Vector{String} # Labels of a Categorical CPT - key::Vector{String} # Keys of a Categorical CPT - model::String # String with color model rgb, hsv, or cmyk [rgb] - comment::Array{String,1} # Cell array with any comments + colormap::Array{Float64,2} + alpha::Array{Float64,1} + range::Array{Float64,2} + minmax::Array{Float64,1} + bfn::Array{Float64,2} + depth::Cint + hinge::Cdouble + cpt::Array{Float64,2} + label::Vector{String} + key::Vector{String} + model::String + comment::Array{String,1} end GMTcpt() = GMTcpt(Array{Float64,2}(undef,0,0), Vector{Float64}(undef,0), Array{Float64,2}(undef,0,0), Vector{Float64}(undef,0), Array{Float64,2}(undef,0,0), 0, 0.0, Array{Float64,2}(undef,0,0), String[], String[], string(), String[]) Base.size(C::GMTcpt) = size(C.range, 1) Base.isempty(C::GMTcpt) = (size(C) == 0) +""" + GMTps(postscript::String, length::Int, mode::Int, comment::Arrray{String,1}) + +Construct a GMT postscript plot container. + +- `postscript` Actual PS plot (text string) +- `length` Byte length of postscript +- `mode` 1 = Has header, 2 = Has trailer, 3 = Has both +- `comment` Cell array with any comments + +""" mutable struct GMTps - postscript::String # Actual PS plot (text string) - length::Int # Byte length of postscript - mode::Int # 1 = Has header, 2 = Has trailer, 3 = Has both - comment::Array{String,1} # Cell array with any comments + postscript::String + length::Int + mode::Int + comment::Array{String,1} end GMTps() = GMTps(string(), 0, 0, String[]) Base.size(P::GMTps) = P.length Base.isempty(P::GMTps) = (P.length == 0) -mutable struct GMTdataset{T<:Real, N} <: AbstractArray{T,N} - data::Array{T,N} +""" + GMTdataset(fields...) + +Construct a GMT dataset from data using optional header information. + +- `data::Array{T,N}` Mx2 Matrix with segment data +- `ds_bbox::Vector{Float64}` Global BoundingBox (for when there are many segments) +- `bbox::Vector{Float64}` Segment BoundingBox +- `attrib::Dict{String,String}` Dictionary with attributes/values (optional) +- `colnames::Vector{String}` Column names. Antecipate using this with a future Tables inerface +- `text::Vector{String}` Array with text after data coordinates (mandatory only when plotting Text) +- `header::String` String with segment header (Optional but sometimes very useful) +- `comment::Vector{String}` Array with any dataset comments [empty after first segment] +- `proj4::String` Projection string in PROJ4 syntax (Optional) +- `wkt::String` Projection string in WKT syntax (Optional) +- `geom::Integer` Geometry type. One of the GDAL's enum (wkbPoint, wkbPolygon, etc...) + +""" +mutable struct GMTdataset{T<:AbstractArray{T1} where T1 <: Real} + data::T ds_bbox::Vector{Float64} bbox::Vector{Float64} attrib::Dict{String, String} @@ -114,22 +223,22 @@ mutable struct GMTdataset{T<:Real, N} <: AbstractArray{T,N} geom::Int end Base.size(D::GMTdataset) = size(D.data) -Base.getindex(D::GMTdataset{T,N}, inds::Vararg{Int,N}) where {T,N} = D.data[inds...] -Base.setindex!(D::GMTdataset{T,N}, val, inds::Vararg{Int,N}) where {T,N} = D.data[inds...] = val - -Base.BroadcastStyle(::Type{<:GMTdataset}) = Broadcast.ArrayStyle{GMTdataset}() -function Base.similar(bc::Broadcast.Broadcasted{Broadcast.ArrayStyle{GMTdataset}}, ::Type{ElType}) where ElType - D = find4similar(bc.args) # Scan the inputs for the GMTdataset: - GMTdataset(D.data, D.ds_bbox, D.bbox, D.attrib, D.colnames, D.text, D.header, D.comment, D.proj4, D.wkt, D.geom) -end +Base.getindex(D::GMTdataset, inds::Vararg{Int,N}) where N = D.data[inds...] +Base.setindex!(D::GMTdataset, val, inds::Vararg{Int,N}) where N = D.data[inds...] = val + +#Base.BroadcastStyle(::Type{<:GMTdataset}) = Broadcast.ArrayStyle{GMTdataset}() +#function Base.similar(bc::Broadcast.Broadcasted{Broadcast.ArrayStyle{GMTdataset}}, ::Type{ElType}) where ElType +# D = find4similar(bc.args) # Scan the inputs for the GMTdataset: +# GMTdataset(D.data, D.ds_bbox, D.bbox, D.attrib, D.colnames, D.text, D.header, D.comment, D.proj4, D.wkt, D.geom) +#end find4similar(D::GMTdataset, rest) = D -GMTdataset(data::Array{Float64,2}, text::Vector{String}) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], text, "", String[], "", "", 0) -GMTdataset(data::Array{Float64,2}, text::String) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], [text], "", String[], "", "", 0) -GMTdataset(data::Array{Float64,2}) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], String[], "", String[], "", "", 0) -GMTdataset(data::Array{Float32,2}, text::Vector{String}) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], text, "", String[], "", "", 0) -GMTdataset(data::Array{Float32,2}, text::String) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], [text], "", String[], "", "", 0) -GMTdataset(data::Array{Float32,2}) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], String[], "", String[], "", "", 0) +GMTdataset(data::AbstractArray{Float64,2}, text::Vector{String}) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], text, "", String[], "", "", 0) +GMTdataset(data::AbstractArray{Float64,2}, text::String) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], [text], "", String[], "", "", 0) +GMTdataset(data::AbstractArray{Float64,2}) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], String[], "", String[], "", "", 0) +GMTdataset(data::AbstractArray{Float32,2}, text::Vector{String}) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], text, "", String[], "", "", 0) +GMTdataset(data::AbstractArray{Float32,2}, text::String) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], [text], "", String[], "", "", 0) +GMTdataset(data::AbstractArray{Float32,2}) = GMTdataset(data, Float64[], Float64[], Dict{String, String}(), String[], String[], "", String[], "", "", 0) GMTdataset() = GMTdataset(Array{Float64,2}(undef,0,0), Float64[], Float64[], Dict{String, String}(), String[], String[], "", String[], "", "", 0) struct WrapperPluto fname::String end diff --git a/src/precompile_GMT_i.jl b/src/precompile_GMT_i.jl index 4f511c082b..ce2502203a 100644 --- a/src/precompile_GMT_i.jl +++ b/src/precompile_GMT_i.jl @@ -9,9 +9,9 @@ function _precompile_() @assert Base.precompile(Tuple{typeof(put_in_legend_bag),Dict{Symbol, Any},Vector{String},Matrix{Float64}}) # time: 0.0101455 @assert Base.precompile(Tuple{typeof(add_opt_module),Dict{Symbol, Any}}) # time: 0.365098 - @assert Base.precompile(Tuple{typeof(imshow),GMTgrid{Float32, 2}}) # time: 12.84012 - @assert Base.precompile(Tuple{typeof(finish_PS_module),Dict{Symbol, Any},Vector{String},String,Bool,Bool,Bool,GMTgrid{Float32, 2},Vararg{Any, N} where N}) # time: 0.1452611 - @assert Base.precompile(Tuple{Core.kwftype(typeof(grdimage)),NamedTuple{(:show,), Tuple{Bool}},typeof(grdimage),String,GMTgrid{Float32, 2}}) # time: 0.043773 - @assert Base.precompile(Tuple{typeof(common_get_R_cpt),Dict{Symbol, Any},String,String,String,Int64,GMTgrid{Float32, 2},Nothing,Nothing,String}) # time: 0.0355232 - @assert Base.precompile(Tuple{typeof(common_shade),Dict{Symbol, Any},String,GMTgrid{Float32, 2},GMTcpt,Nothing,Nothing,String}) # time: 0.0226077 + @assert Base.precompile(Tuple{typeof(imshow),GMTgrid{Array{Float32, 2}}}) # time: 12.84012 + @assert Base.precompile(Tuple{typeof(finish_PS_module),Dict{Symbol, Any},Vector{String},String,Bool,Bool,Bool,GMTgrid{Array{Float32, 2}},Vararg{Any, N} where N}) # time: 0.1452611 + @assert Base.precompile(Tuple{Core.kwftype(typeof(grdimage)),NamedTuple{(:show,), Tuple{Bool}},typeof(grdimage),String,GMTgrid{Array{Float32, 2}}}) # time: 0.043773 + @assert Base.precompile(Tuple{typeof(common_get_R_cpt),Dict{Symbol, Any},String,String,String,Int64,GMTgrid{Array{Float32, 2}},Nothing,Nothing,String}) # time: 0.0355232 + @assert Base.precompile(Tuple{typeof(common_shade),Dict{Symbol, Any},String,GMTgrid{Array{Float32, 2}},GMTcpt,Nothing,Nothing,String}) # time: 0.0226077 end From 8699804706c9979b804e20ad82be0787f98cd972 Mon Sep 17 00:00:00 2001 From: adigitoleo Date: Tue, 18 Jan 2022 00:01:31 +1100 Subject: [PATCH 2/2] docs: Remove duplicate type docstrings and fix links Link breakage due to commit 0164606. Might not have caught all of them, I can't get documenter to work offline. --- docs/Project.toml | 4 +- docs/make.jl | 4 ++ docs/src/modules.md | 4 +- docs/src/quick_learn.md | 6 +-- docs/src/types.md | 103 +++------------------------------------- docs/src/usage.md | 14 +++--- 6 files changed, 24 insertions(+), 111 deletions(-) diff --git a/docs/Project.toml b/docs/Project.toml index 7797965558..7b40a89e48 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,5 +1,3 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" - -#[compat] -#Documenter = "~0.25" +GMT = "5752ebe1-31b9-557e-87aa-f909b540aa54" diff --git a/docs/make.jl b/docs/make.jl index 4da2d77723..f31d4502ed 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,3 +1,7 @@ +using Pkg +Pkg.activate("$(@__DIR__)") +Pkg.update() + using Documenter, GMT, GMT.Drawing, GMT.Gdal makedocs( diff --git a/docs/src/modules.md b/docs/src/modules.md index db1d9ed245..07ef1b5707 100644 --- a/docs/src/modules.md +++ b/docs/src/modules.md @@ -183,7 +183,7 @@ The issue with this solution, that could be implemented internally without user currently only works on Windows. Another alternative to a file format is the option to create RGB images with *psconvert* and -return it to Julia as a [Image type](@ref) type. +return it to Julia as a [`GMTimage`](@ref) type. I = psconvert(in_memory=true, adjust=true) @@ -194,7 +194,7 @@ image with the [`Images.jl`](https://github.com/JuliaImages/Images.jl) package. As referred in the [Monolithic](@ref) section, we have two programs to do read and writing. Their module names are *gmtread* and *gmtwrite*. These modules allow to import and export any of the GMT -data types to and from external files. For instance, to save the grid *G* stored into a GMTgrid type +data types to and from external files. For instance, to save the grid *G* stored into a [`GMTgrid`](@ref) type into the file *relief.nc* we run gmtwrite("relief.nc", G) diff --git a/docs/src/quick_learn.md b/docs/src/quick_learn.md index 275a6c3a7f..49959e19a8 100644 --- a/docs/src/quick_learn.md +++ b/docs/src/quick_learn.md @@ -38,9 +38,9 @@ be achieved by previously reading the grid file. Though not particularly useful nor memory more efficient to read the grid first this example illustrates typical usage. That is, use GMT to process and map/plot data resident in Julia memory. GMT modules know -how to manipulate import/create data stored in `GMTgrid`[Grid type](@ref), `GMTimage`[Image type](@ref), -`GMTdataset`[Dataset type](@ref), `GMTcpt`[CPT type](@ref) and `GMTps`[Postscript type](@ref) objects. -The helper functions `mat2grid`, `mat2img` and `mat2ds` exist to allow creating those objects from 2D arrays +how to manipulate import/create data stored in [`GMTgrid`](@ref), [`GMTimage`](@ref), +[`GMTdataset`](@ref), [`GMTcpt`](@ref) and [`GMTps`](@ref) objects. +The helper functions [`mat2grid`](@ref), [`mat2img`](@ref) and [`mat2ds`](@ref) exist to allow creating those objects from 2D arrays of floats, uint8, uint16 and MxN matrices respectively. Example: create three grids with random data, compute their average and display it diff --git a/docs/src/types.md b/docs/src/types.md index e70a8c6c6e..000fec91e8 100644 --- a/docs/src/types.md +++ b/docs/src/types.md @@ -1,99 +1,10 @@ # The GMT.jl types -Grid type ---------- +```@docs +GMTgrid +GMTimage +GMTdataset +GMTcpt +GMTps +``` - type GMTgrid{T<:Real,N} <: AbstractArray{T,N} # The type holding a local header and data of a GMT grid - proj4::String # Projection string in PROJ4 syntax (Optional) - wkt::String # Projection string in WKT syntax (Optional) - epsg::Int # EPSG code - range::Array{Float64,1} # 1x6[8] vector with [x_min, x_max, y_min, y_max, z_min, z_max [, v_min, v_max]] - inc::Array{Float64,1} # 1x2[3] vector with [x_inc, y_inc [,v_inc]] - registration::Int # Registration type: 0 -> Grid registration; 1 -> Pixel registration - nodata::Float64 # The value of nodata - title::String # Title (Optional) - comment::String # Remark (Optional) - command::String # Command used to create the grid (Optional) - names::Vector{String} # To use whith multi-layered and when layers have names (Optional) - x::Array{Float64,1} # [1 x n_columns] vector with XX coordinates - y::Array{Float64,1} # [1 x n_rows] vector with YY coordinates - v::Array{Float64,1} # [v x n_bands] vector with VV (vertical for 3D grids) coordinates - z::Array{Float32,2} # [n_rows x n_columns] grid array - x_units::String # Units of XX axis (Optional) - y_units::String # Units of YY axis (Optional) - v_units::String # Units of Vertical axis (Optional) - z_units::String # Units of z vlues (Optional) - layout::String # A three character string describing the grid memory layout - scale::Union{Float64, Float32} # When saving in file apply `z = z * scale + offset` - offset::Union{Float64, Float32} - pad::Int # When != 0 means that the array is placed in a padded array of PAD rows/cols - end - -Image type ----------- - - type GMTimage{T<:Unsigned, N} <: AbstractArray{T,N} # The type holding a local header and data of a GMT image - proj4::String # Projection string in PROJ4 syntax (Optional) - wkt::String # Projection string in WKT syntax (Optional) - epsg::Int # EPSG code - range::Array{Float64,1} # 1x6 vector with [x_min x_max y_min y_max z_min z_max] - inc::Array{Float64,1} # 1x2 vector with [x_inc y_inc] - registration::Int # Registration type: 0 -> Grid registration; 1 -> Pixel registration - nodata::Unsigned # The value of nodata - color_interp::String # If equal to "Gray" an indexed image with no cmap will get a gray cmap - metadata::Vector{String} # To store any metadata that can eventually be passed to GDAL (Optional) - names::Vector{String} # To use whith multi-band and when bands have names (Optional) - x::Array{Float64,1} # [1 x n_columns] vector with XX coordinates - y::Array{Float64,1} # [1 x n_rows] vector with YY coordinates - v::Array{Float64,1} # [v x n_bands] vector with vertical coords or wavelengths in hypercubes (Optional) - image::Array{T,N} # [n_rows x n_columns x n_bands] image array - colormap::Array{Int32,1} # - alpha::Array{UInt8,2} # A [n_rows x n_columns] alpha array - layout::String # A four character string describing the image memory layout - pad::Int # When != 0 means that the array is placed in a padded array of PAD rows/cols - end - -Dataset type ------------- - - type GMTdataset{T<:Real, N} <: AbstractArray{T,N} - data::Array{T,N} # Mx2 Matrix with segment data - ds_bbox::Vector{Float64} # Global BoundingBox (for when there are many segments) - bbox::Vector{Float64} # Segment BoundingBox - attrib::Dict{String, String} # Dictionary with attributes/values (optional) - colnames::Vector{String} # Column names. Antecipate using this with a future Tables inerface - text::Vector{String} # Array with text after data coordinates (mandatory only when plotting Text) - header::String # String with segment header (Optional but sometimes very useful) - comment::Vector{String} # Array with any dataset comments [empty after first segment] - proj4::String # Projection string in PROJ4 syntax (Optional) - wkt::String # Projection string in WKT syntax (Optional) - geom::Integer # Geometry type. One of the GDAL's enum (wkbPoint, wkbPolygon, etc...) - end - -CPT type --------- - - type GMTcpt - colormap::Array{Float64,2} - alpha::Array{Float64,1} - range::Array{Float64,2} - minmax::Array{Float64,1} - bfn::Array{Float64,2} - depth::Cint - hinge::Cdouble - cpt::Array{Float64,2} - label::Vector{String} # Labels of a Categorical CPT - key::Vector{String} # Keys of a Categorical CPT - model::String - comment::Array{Any,1} # Cell array with any comments - end - -Postscript type ---------------- - - type GMTps - postscript::String # Actual PS plot (text string) - length::Int # Byte length of postscript - mode::Int # 1 = Has header, 2 = Has trailer, 3 = Has both - comment::Array{Any,1} # Cell array with any comments - end diff --git a/docs/src/usage.md b/docs/src/usage.md index 9c218e0fbe..158818ac3b 100644 --- a/docs/src/usage.md +++ b/docs/src/usage.md @@ -13,22 +13,22 @@ between the GMT structures and native Julia structures, which are: - **Grids**: Many tools consider equidistant grids a particular data type and numerous file formats exist for saving such data. Because GMT relies on GDAL we are able to read and write almost all such formats in addition to a native netCDF4 format that complies with both the COARDS - and CF netCDF conventions. We have designed a native Julia grid structure [Grid type](@ref) + and CF netCDF conventions. We have designed a native Julia grid structure [`GMTgrid`](@ref) that holds header information from the GMT grid as well as the data matrix representing the gridded values. These structures may be passed to GMT modules that expect grids and are - returned from GMT modules that produce such grids. In addition, we supply the function [mat2grid](@ref) + returned from GMT modules that produce such grids. In addition, we supply the function [`mat2grid`](@ref) to convert a matrix and some metadata into a grid structure. - **Images**: The raster image shares many characteristics with the grid structure except the bytes representing each node reflect gray shade, color bands (1, 3, or 4 for indexed, RGB and RGBA, respectively), and possibly transparency values. We therefore represent images in another - native structure [Image type](@ref) that among other items contains three components: The image + native structure [`GMTimage`](@ref) that among other items contains three components: The image matrix, a color map (present for indexed images only), and an alpha matrix (for images specifying - transparency on a per-pixel level). As for grids, the wrapper function [mat2img](@ref) for creating + transparency on a per-pixel level). As for grids, the wrapper function [`mat2img`](@ref) for creating the correct structure is available. - **Segments**: GMT considers point, line, and polygon data to be organized in one or more segments - in a data table. Modules that return segments uses a native Julia segment structure [Dataset type](@ref) + in a data table. Modules that return segments uses a native Julia segment structure [`GMTdataset`](@ref) that holds the segment data, which may be either numerical, text, or both; it also holds a segment header string which GMT uses to pass metadata. Thus, GMT modules returning segments will typically produce arrays of segments and you may pass these to any other module expecting points, lines, or @@ -39,13 +39,13 @@ between the GMT structures and native Julia structures, which are: - **Color palettes**: GMT uses its flexible Color Palette Table (CPT) format to describe how the color (or pattern) of symbols, lines, polygons or grids should vary as a function of a state variable. - In Julia, this information is provided in another structure [CPT type](@ref) that holds the color + In Julia, this information is provided in another structure [`GMTcpt`](@ref) that holds the color map as well as an optional alpha array for transparency values. Like grids, these structures may be passed to GMT modules that expect CPTs and will be returned from GMT modules that normally would produce CPT files. - **PostScript**: While most users of the GMT.jl wrapper are unlikely to manipulate PostScript - directly, it allows for the passing of PostScript via another data structure [Postscript type](@ref). + directly, it allows for the passing of PostScript via another data structure [`GMTps`](@ref). Given this design the Julia wrapper is designed to work in two distinct ways.