API Reference

arecompatible(dtype::OGRFieldType, subtype::OGRFieldSubType)

Return if type and subtype are compatible.

References

• https://gdal.org/development/rfc/rfc50ogrfield_subtype.html

asyncstatustype(name::AbstractString)

Get AsyncStatusType by symbolic name.

colorinterp(name::AbstractString)

Get color interpretation corresponding to the given symbolic name.

getname(dtype::GDALAsyncStatusType)

Get name of AsyncStatus data type.

getname(obj::GDALColorInterp)

Return name (string) corresponding to color interpretation.

getname(obj::GDALPaletteInterp)

Get name of palette interpretation.

getname(obj::OGRFieldSubType)

Fetch human readable name for a field subtype.

References

• https://gdal.org/development/rfc/rfc50ogrfield_subtype.html

getname(obj::OGRFieldType)

Fetch human readable name for a field type.

gettype(name::AbstractString)

Returns GDAL data type by symbolic name.

iscomplex(dtype::GDALDataType)

true if dtype is one of GDT_{CInt16|CInt32|CFloat32|CFloat64}.

Fetch the pixel data type for this band.

typename(dt::GDALDataType)

name (string) corresponding to GDAL data type.

typesize(dt::GDALDataType)

Get the number of bits or zero if it is not recognised.

typeunion(dt1::GDALDataType, dt2::GDALDataType)

Return the smallest data type that can fully express both input data types.

Default progress function, which logs no progress. A progress function should return true to continue, or false to abort.

_progresscallback(dfComplete::Cdouble, pszMessage::Cstring, pProgressArg::Ptr{Cvoid})::Cint

The progress callback function to be passed to GDAL. Users can provide their own progress function by passing a function of the form f(dfComplete::Cdouble, pszMessage::Cstring)::Bool to the progressfunc keyword argument of the functions that implement it, which should be wrapped in a Ref.

In essence, we pass a pointer to the (user-provided) progress function to GDAL, and GDAL passes it back to us, including the progress ratio and message. We then call the user-provided function with these arguments.

Parameters

• dfComplete – completion ratio from 0.0 to 1.0.
• pszMessage – optional message (made available as an argument to the user-defined progress function).
• pProgressArg – callback data argument (i.e. user-defined progress function, see _dummyprogress).

clearconfigoption(option::AbstractString)

This function can be used to clear a setting.

Note: it will not unset an existing environment variable; it will just unset a value previously set by setconfigoption().

clearthreadconfigoption(option::AbstractString)

This function can be used to clear a setting.

Note: it will not unset an existing environment variable; it will just unset a value previously set by setthreadconfigoption().

getconfigoption(option::AbstractString, default = C_NULL)

Get the value of a configuration option.

The value is the value of a (key, value) option set with setconfigoption(). If the given option was not defined with setconfigoption(), it tries to find it in environment variables.

Parameters

• option the key of the option to retrieve
• default a default value if the key does not match existing defined options

Returns

the value associated to the key, or the default value if not found.

getthreadconfigoption(option::AbstractString, default = C_NULL)

Same as getconfigoption() but with settings from setthreadconfigoption().

metadata(obj; domain::AbstractString = "")

Fetch metadata. Note that relatively few formats return any metadata.

metadatadomainlist(obj)

Fetch list of (non-empty) metadata domains.

metadataitem(obj, name::AbstractString, domain::AbstractString)

Fetch single metadata item.

Parameters

• name the name of the metadata item to fetch.
• domain (optional) the domain to fetch for.

Returns

The metadata item on success, or an empty string on failure.

setconfigoption(option::AbstractString, value)

Set a configuration option for GDAL/OGR use.

Those options are defined as a (key, value) couple. The value corresponding to a key can be got later with the getconfigoption() method.

Parameters

• option the key of the option
• value the value of the option, or NULL to clear a setting.

This mechanism is similar to environment variables, but options set with setconfigoption() overrides, for getconfigoption() point of view, values defined in the environment.

If setconfigoption() is called several times with the same key, the value provided during the last call will be used.

setthreadconfigoption(option::AbstractString, value)

Set a configuration option for GDAL/OGR use.

Those options are defined as a (key, value) couple. The value corresponding to a key can be got later with the getconfigoption() method.

Parameters

• option the key of the option
• value the value of the option

This function sets the configuration option that only applies in the current thread, as opposed to setconfigoption() which sets an option that applies on all threads.

@convert(<T1>::<T2>,
    <conversions>
)

Generate convert functions both ways between ArchGDAL Enum of typeids (e.g. ArchGDAL.OGRFieldType) and other types or typeids.

ArchGDAL uses Enum types, listing typeids of various data container used in GDAL/OGR object model. Some of these types are used to implement concrete types in julia through parametric composite types based on those Enum of typeids (e.g. Geometry and IGeometry types with OGRwkbGeometryType)

Other types or typeids can be:

• GDAL CEnum.Cenum typeids (e.g. GDAL.OGRFieldType),
• Base primitive DataType types (e.g. Bool),
• other parametric composite types (e.g. ImageCore.Normed)

Arguments

• (<T1>::<T2>)::Expr: source and target supertypes, where T1<:Enum and T2<:CEnum.Cenum || T2::Type{DataType} || T2::UnionAll}`
• (<stype1>::<stype2>)::Expr: source and target subtypes or type ids with stype1::T1 and
  • stype2::T2 where T2<:CEnum.Cenum or
  • stype2::T2 where T2::Type{DataType} or
  • stype2<:T2where T2<:UnionAll
• ...

Note: In the case where the mapping is not bijective, the last declared typeid of subtype is used. Example:

@convert(
    OGRFieldType::DataType,
    OFTInteger::Bool,
    OFTInteger::Int16,
    OFTInteger::Int32,
)

will generate a convert functions giving:

• Int32 type for OFTInteger and not Ìnt16
• OFTInteger OGRFieldType typeid for both Int16 and Int32

Usage

General case:

@convert(GDALRWFlag::GDAL.GDALRWFlag,
    GF_Read::GDAL.GF_Read,
    GF_Write::GDAL.GF_Write,
)

does the equivalent of

const GDALRWFlag_to_GDALRWFlag_map = ImmutableDict(
    GF_Read => GDAL.GF_Read,
    GF_Write => GDAL.GF_Write
)
Base.convert(::Type{GDAL.GDALRWFlag}, ft::GDALRWFlag) =
    GDALRWFlag_to_GDALRWFlag_map[ft]

const GDALRWFlag_to_GDALRWFlag_map = ImmutableDict(
    GDAL.GF_Read => GF_Read,
    GDAL.GF_Write => GF_Write
)
Base.convert(::Type{GDALRWFlag}, ft::GDAL.GDALRWFlag) =
    GDALRWFlag_to_GDALRWFlag_map[ft]

Case where 1st type <: Enum and 2nd type == DataType or ìsa UnionAll:

@convert(OGRFieldType::DataType,
    OFTInteger::Bool,
    OFTInteger::Int16,
)

does the equivalent of

const OGRFieldType_to_DataType_map = ImmutableDict(
    OFTInteger => Bool,
    OFTInteger => Int16,
)
Base.convert(::Type{DataType}, ft::OGRFieldType) =
    OGRFieldType_to_DataType_map[ft]

Base.convert(::Type{OGRFieldType}, ft::Type{Bool}) = OFTInteger
Base.convert(::Type{OGRFieldType}, ft::Type{Int16}) = OFTInteger

The value of GDALAccess could be different from GDAL.GDALAccess.

It maps correctly to GDAL.GDALAccess if you do e.g.

convert(GDAL.GDALAccess, ArchGDAL.GA_ReadOnly)

The value of GDALAsyncStatusType could be different from GDAL.GDALAsyncStatusType.

It maps correctly to GDAL.GDALAsyncStatusType if you do e.g.

convert(GDAL.GDALAsyncStatusType, ArchGDAL.GARIO_PENDING)

The value of GDALColorInterp could be different from GDAL.GDALColorInterp.

It maps correctly to GDAL.GDALColorInterp if you do e.g.

convert(GDAL.GDALColorInterp, ArchGDAL.GCI_Undefined)

The value of GDALDataType could be different from GDAL.GDALDataType.

It maps correctly to GDAL.GDALDataType if you do e.g.

convert(GDAL.GDALDataType, ArchGDAL.GDT_Unknown)

The value of GDALPaletteInterp could be different from GDAL.GDALPaletteInterp.

It maps correctly to GDAL.GDALPaletteInterp if you do e.g.

convert(GDAL.GDALPaletteInterp, ArchGDAL.GPI_Gray)

The value of GDALRATFieldType could be different from GDAL.GDALRATFieldType.

It maps correctly to GDAL.GDALRATFieldType if you do e.g.

convert(GDAL.GDALRATFieldType, ArchGDAL.GFT_Integer)

The value of GDALRATFieldUsage could be different from GDAL.GDALRATFieldUsage.

It maps correctly to GDAL.GDALRATFieldUsage if you do e.g.

convert(GDAL.GDALRATFieldUsage, ArchGDAL.GFU_Generic)

The value of GDALRWFlag could be different from GDAL.GDALRWFlag.

It maps correctly to GDAL.GDALRWFlag if you do e.g.

convert(GDAL.GDALRWFlag, ArchGDAL.GF_Read)

The value of OGRFieldSubType could be different from GDAL.OGRFieldSubType.

It maps correctly to GDAL.OGRFieldSubType if you do e.g.

convert(GDAL.OGRFieldSubType, ArchGDAL.OFSTNone)

The value of OGRFieldType could be different from GDAL.OGRFieldType.

It maps correctly to GDAL.OGRFieldType if you do e.g.

convert(GDAL.OGRFieldType, ArchGDAL.OFTInteger)

The value of OGRJustification could be different from GDAL.OGRJustification.

It maps correctly to GDAL.OGRJustification if you do e.g.

convert(GDAL.OGRJustification, ArchGDAL.OJUndefined)

The value of OGRSTClassId could be different from GDAL.OGRSTClassId.

It maps correctly to GDAL.OGRSTClassId if you do e.g.

convert(GDAL.OGRSTClassId, ArchGDAL.OGRSTCNone)

The value of OGRSTUnitId could be different from GDAL.OGRSTUnitId.

It maps correctly to GDAL.OGRSTUnitId if you do e.g.

convert(GDAL.OGRSTUnitId, ArchGDAL.OGRSTUGround)

The value of OGRwkbByteOrder could be different from GDAL.OGRwkbByteOrder.

It maps correctly to GDAL.OGRwkbByteOrder if you do e.g.

convert(GDAL.OGRwkbByteOrder, ArchGDAL.wkbXDR)

The value of OGRwkbGeometryType could be different from GDAL.OGRwkbGeometryType.

It maps correctly to GDAL.OGRwkbGeometryType if you do e.g.

convert(GDAL.OGRwkbGeometryType, ArchGDAL.wkbUnknown)

buildoverviews!(dataset::AbstractDataset, overviewlist::Vector{Cint};
    bandlist, resampling="NEAREST", progressfunc)

Build raster overview(s).

If the operation is unsupported for the indicated dataset, then CEFailure is returned, and CPLGetLastErrorNo() will return CPLENotSupported.

Parameters

• overviewlist overview decimation factors to build.

Keyword Parameters

• panBandList list of band numbers. Must be in Cint (default = all)
• sampling one of "NEAREST" (default), "GAUSS","CUBIC","AVERAGE","MODE", "AVERAGE_MAGPHASE" or "NONE" controlling the downsampling method applied.
• progressfunc a function(::Float64, ::String)::Bool to call to report progress

copy(dataset::AbstractDataset; [filename, [driver, [<keyword arguments>]]])

Create a copy of a dataset.

This method will attempt to create a copy of a raster dataset with the indicated filename, and in this drivers format. Band number, size, type, projection, geotransform and so forth are all to be copied from the provided template dataset.

Parameters

• dataset the dataset being duplicated.

Keyword Arguments

• filename the filename for the new dataset. UTF-8 encoded.
• driver the driver to use for creating the new dataset
• strict $true$ if the copy must be strictly equivalent, or more normally $false$ if the copy may adapt as needed for the output format.
• options additional format dependent options controlling creation of the output file. The APPEND_SUBDATASET=YES option can be specified to avoid prior destruction of existing dataset.
• progressfunc a function(::Float64, ::String)::Bool to call to report progress

Example

dataset = ArchGDAL.copy(originaldataset)
# work with dataset from here

or

ArchGDAL.copy(originaldataset) do dataset
    # work with dataset from here
end

Returns

The newly created dataset.

copylayers!(source_dataset, target_dataset; kwargs...)

Copies a (sub)set of layers from source to target dataset. Note that eventual layer options have to conform with the target dataset driver.

Currently working drivers: FlatGeobuf, GeoJSON, GeoJSONSeq, GML, GPKG, JML, KML, MapML, ESRI Shapefile, SQLite

Keyword arguments

• driver: The driver to use, you have to manually select the right driver for the file extension you wish
• options: A vector of strings containing KEY=VALUE pairs for driver-specific creation options
• source_layer_indices: Specifies which layers should be written. Can be e.g. a range, Vector{Int} or tuple.
• layer_options: Driver specific options for layer creation. The options can either be a Vector{String} to provide the same options for each layer, or a Dict(layer_index => Vector{String}) to provide individual options per layer. Note that layer indexing in GDAL starts with 0. The strings have to be KEY=VALUE pairs. An example for two layers: Dict(0 => ["FORMAT=WKT", "LAUNDER=NO"], 1 => ["STRICT=NO"])
• chunksize: Number of features to write in one database transaction. Neglected when use_gdal_copy is true.
• use_gdal_copy: Set this to false (default is true) to achieve higher write speeds at the cost of possible errors. Note that when set to true, no coordinate transformations are possible while writing the features.

copywholeraster(source::AbstractDataset, dest::AbstractDataset;
    options::StringList, progressfunc::Function)

Copy all dataset raster data.

This function copies the complete raster contents of one dataset to another similarly configured dataset. The source and destination dataset must have the same number of bands, and the same width and height. The bands do not have to have the same data type.

Currently the only options supported are : "INTERLEAVE=PIXEL" to force pixel interleaved operation and "COMPRESSED=YES" to force alignment on target dataset block sizes to achieve best compression. More options may be supported in the future.

For progress reporting one can pass progressfunc function(::Float64, ::String)::Bool to call to report progress.

Additional Remarks

This function is primarily intended to support implementation of driver specific createcopy() functions. It implements efficient copying, in particular "chunking" the copy in substantial blocks and, if appropriate, performing the transfer in a pixel interleaved fashion.

create(filename::AbstractString; driver, width, height, nbands, dtype,
    options)

Create a new dataset.

Parameters

• filename the filename for the dataset being created.

Keyword Arguments

• driver the driver to use for creating the new dataset
• options additional format dependent options controlling creation

of the output file. The APPEND_SUBDATASET=YES option can be specified to avoid prior destruction of existing dataset.

• width, height, nbands, dtype: only for raster datasets.

Example

dataset = ArchGDAL.create(filename; ...)
# work with raster dataset from here

or

ArchGDAL.create(filename; ...) do dataset
    # work with vector dataset from here
end

Returns

The newly created dataset.

deletelayer!(dataset::AbstractDataset, i::Integer)

Delete the indicated layer (at index i; between 0 to nlayer()-1)

Returns

OGRERR_NONE on success, or OGRERR_UNSUPPORTED_OPERATION if deleting layers is not supported for this dataset.

filelist(dataset::AbstractDataset)

Fetch files forming dataset.

Returns a list of files believed to be part of this dataset. If it returns an empty list of files it means there is believed to be no local file system files associated with the dataset (for instance a virtual dataset). The returned file list is owned by the caller and should be deallocated with CSLDestroy().

The returned filenames will normally be relative or absolute paths depending on the path used to originally open the dataset. The strings will be UTF-8 encoded

getband(dataset::AbstractDataset, i::Integer)
getband(ds::RasterDataset, i::Integer)

Fetch a band object for a dataset from its index.

getdriver(dataset::AbstractDataset)

Fetch the driver that the dataset was created with

getgeotransform!(dataset::AbstractDataset, transform::Vector{Cdouble})

Fetch the affine transformation coefficients.

Fetches the coefficients for transforming between pixel/line (P,L) raster space, and projection coordinates (Xp,Yp) space.

   Xp = padfTransform[0] + P*padfTransform[1] + L*padfTransform[2];
   Yp = padfTransform[3] + P*padfTransform[4] + L*padfTransform[5];

In a north up image, padfTransform[1] is the pixel width, and padfTransform[5] is the pixel height. The upper left corner of the upper left pixel is at position (padfTransform[0],padfTransform[3]).

The default transform is (0,1,0,0,0,1) and should be returned even when a CE_Failure error is returned, such as for formats that don't support transformation to projection coordinates.

Parameters

• buffer a six double buffer into which the transformation will be placed.

Returns

CE_None on success, or CE_Failure if no transform can be fetched.

getlayer(dataset::AbstractDataset, name::AbstractString)

Fetch the feature layer corresponding to the given name

The returned layer remains owned by the dataset and should not be deleted by the application.

getlayer(dataset::AbstractDataset, i::Integer)

Fetch the layer at index i (between 0 and nlayer(dataset)-1)

The returned layer remains owned by the dataset and should not be deleted by the application.

getlayer(dataset::AbstractDataset)

Fetch the first layer and raise an error if dataset contains more than one layer

The returned layer remains owned by the dataset and should not be deleted by the application.

getproj(dataset::AbstractDataset)

Fetch the projection definition string for this dataset in OpenGIS WKT format.

It should be suitable for use with the OGRSpatialReference class. When a projection definition is not available an empty (but not NULL) string is returned.

height(dataset::AbstractDataset)

Fetch raster height in pixels.

ngcp(dataset::AbstractDataset)

Get number of GCPs for this dataset. Zero if there are none.

nlayer(dataset::AbstractDataset)

Fetch the number of feature layers on this dataset.

nraster(dataset::AbstractDataset)

Fetch the number of raster bands on this dataset.

pixeltype(ds::AbstractDataset)

Tries to determine a common dataset type for all the bands in a raster dataset.

read(filename; flags=OF_READONLY, alloweddrivers, options, siblingfiles)

Open a raster file

Parameters

• filename: the filename of the dataset to be read.

Keyword Arguments

• flags: a combination of OF_* flags (listed below) that may be combined through the logical | operator. It defaults to OF_READONLY.
  • Driver kind: OF_Raster for raster drivers, OF_Vector for vector drivers. If none of the value is specified, both are implied.
  • Access mode: OF_READONLY (exclusive) or OF_UPDATE.
  • Shared mode: OF_Shared. If set, it allows the sharing of handles for a dataset with other callers that have set OF_Shared.
  • Verbose error: OF_VERBOSE_ERROR. If set, a failed attempt to open the file will lead to an error message to be reported.
• options: additional format dependent options.

Example

dataset = ArchGDAL.read("point.shp")
# work with dataset from here

or

ArchGDAL.read("point.shp") do dataset
    # work with dataset from here
end

Returns

The corresponding dataset.

releaseresultset(dataset::AbstractDataset, layer::FeatureLayer)

Release results of ExecuteSQL().

This function should only be used to deallocate OGRLayers resulting from an ExecuteSQL() call on the same Dataset. Failure to deallocate a results set before destroying the Dataset may cause errors.

Parameters

• dataset: the dataset handle.
• layer: the result of a previous ExecuteSQL() call.

setgeotransform!(dataset::AbstractDataset, transform::Vector{Cdouble})

Set the affine transformation coefficients.

setproj!(dataset::AbstractDataset, projstring::AbstractString)

Set the projection reference string for this dataset.

testcapability(dataset::AbstractDataset, capability::AbstractString)

Test if capability is available. true if capability available otherwise false.

One of the following dataset capability names can be passed into this function, and a true or false value will be returned indicating whether or not the capability is available for this object.

• ODsCCreateLayer: True if this datasource can create new layers.
• ODsCDeleteLayer: True if this datasource can delete existing layers.
• ODsCCreateGeomFieldAfterCreateLayer: True if the layers of this datasource support CreateGeomField() just after layer creation.
• ODsCCurveGeometries: True if this datasource supports curve geometries.
• ODsCTransactions: True if this datasource supports (efficient) transactions.
• ODsCEmulatedTransactions: True if this datasource supports transactions through emulation.

The #define macro forms of the capability names should be used in preference to the strings themselves to avoid misspelling.

Parameters

• dataset: the dataset handle.
• capability: the capability to test.

unsafe_copy(dataset::AbstractDataset; [filename, [driver,
    [<keyword arguments>]]])

Create a copy of a dataset.

This method will attempt to create a copy of a raster dataset with the indicated filename, and in this drivers format. Band number, size, type, projection, geotransform and so forth are all to be copied from the provided template dataset.

Parameters

• dataset the dataset being duplicated.

Keyword Arguments

• filename the filename for the new dataset. UTF-8 encoded.
• driver the driver to use for creating the new dataset
• strict $true$ if the copy must be strictly equivalent, or more normally $false$ if the copy may adapt as needed for the output format.
• options additional format dependent options controlling creation of the output file. The APPEND_SUBDATASET=YES option can be specified to avoid prior destruction of existing dataset.
• progressfunc a function(::Float64, ::String)::Bool to call to report progress

Returns

a pointer to the newly created dataset (may be read-only access).

Additional Remarks

Note: many sequential write once formats (such as JPEG and PNG) don't implement the Create() method but do implement this CreateCopy() method. If the driver doesn't implement CreateCopy(), but does implement Create() then the default CreateCopy() mechanism built on calling Create() will be used.

It is intended that CreateCopy() will often be used with a source dataset which is a virtual dataset allowing configuration of band types, and other information without actually duplicating raster data (see the VRT driver). This is what is done by the gdal_translate utility for example.

This function will validate the creation option list passed to the driver with the GDALValidateCreationOptions() method. This check can be disabled by defining the configuration option GDAL_VALIDATE_CREATION_OPTIONS=NO.

After you have finished working with the returned dataset, it is required to close it with GDALClose(). This does not only close the file handle, but also ensures that all the data and metadata has been written to the dataset (GDALFlushCache() is not sufficient for that purpose).

In some situations, the new dataset can be created in another process through the GDAL API Proxy mechanism.

unsafe_create(filename::AbstractString; driver, width, height, nbands,
    dtype, options)

Create a new dataset.

What argument values are legal for particular drivers is driver specific, and there is no way to query in advance to establish legal values.

That function will try to validate the creation option list passed to the driver with the GDALValidateCreationOptions() method. This check can be disabled by defining the configuration option GDALVALIDATECREATION_OPTIONS=NO.

After you have finished working with the returned dataset, it is required to close it with GDALClose(). This does not only close the file handle, but also ensures that all the data and metadata has been written to the dataset (GDALFlushCache() is not sufficient for that purpose).

In some situations, the new dataset can be created in another process through the GDAL API Proxy mechanism.

In GDAL 2, the arguments nXSize, nYSize and nBands can be passed to 0 when creating a vector-only dataset for a compatible driver.

unsafe_executesql(dataset::AbstractDataset, query::AbstractString; dialect,
    spatialfilter)

Execute an SQL statement against the data store.

The result of an SQL query is either NULL for statements that are in error, or that have no results set, or an OGRLayer pointer representing a results set from the query. Note that this OGRLayer is in addition to the layers in the data store and must be destroyed with ReleaseResultSet() before the dataset is closed (destroyed).

For more information on the SQL dialect supported internally by OGR review the OGR SQL document. Some drivers (i.e. Oracle and PostGIS) pass the SQL directly through to the underlying RDBMS.

Starting with OGR 1.10, the SQLITE dialect can also be used.

Parameters

• dataset: the dataset handle.
• query: the SQL statement to execute.
• spatialfilter: geometry which represents a spatial filter. Can be NULL.
• dialect: allows control of the statement dialect. If set to NULL, the OGR SQL engine will be used, except for RDBMS drivers that will use their dedicated SQL engine, unless OGRSQL is explicitly passed as the dialect. Starting with OGR 1.10, the SQLITE dialect can also be used.

Returns

an OGRLayer containing the results of the query. Deallocate with ReleaseResultSet().

unsafe_read(filename; flags=OF_READONLY, alloweddrivers, options,
    siblingfiles)

Open a raster file as a Dataset.

This function will try to open the passed file, or virtual dataset name by invoking the Open method of each registered Driver in turn. The first successful open will result in a returned dataset. If all drivers fail then NULL is returned and an error is issued.

Parameters

• filename the name of the file to access. In the case of exotic drivers

this may not refer to a physical file, but instead contain information for the driver on how to access a dataset. It should be in UTF-8 encoding.

• flags a combination of GDAL_OF_* flags (listed below) that may be combined through the logical | operator.

  • Driver kind: GDALOFRASTER for raster drivers, GDALOFVECTOR for vector drivers. If none of the value is specified, both are implied.
  • Access mode: OF_READONLY (exclusive) or OF_UPDATE.
  • Shared mode: GDAL_OF_SHARED. If set, it allows the sharing of Dataset handles for a dataset with other callers that have set GDALOFSHARED. In particular, GDALOpenEx() will consult its list of currently open and shared Dataset's, and if the GetDescription() name for one exactly matches the pszFilename passed to GDALOpenEx() it will be referenced and returned, if GDALOpenEx() is called from the same thread.
  • Verbose error: GDALOFVERBOSE_ERROR. If set, a failed attempt to open the file will lead to an error message to be reported.

• options: additional format dependent options.

Additional Remarks

Several recommendations:

• If you open a dataset object with GA_Update access, it is not recommended

to open a new dataset on the same underlying file.

• The returned dataset should only be accessed by one thread at a time. To use

it from different threads, you must add all necessary code (mutexes, etc.) to avoid concurrent use of the object. (Some drivers, such as GeoTIFF, maintain internal state variables that are updated each time a new block is read, preventing concurrent use.)

• In order to reduce the need for searches through the operating system file

system machinery, it is possible to give an optional list of files with the papszSiblingFiles parameter. This is the list of all files at the same level in the file system as the target file, including the target file. The filenames must not include any path components, are essentially just the output of VSIReadDir() on the parent directory. If the target object does not have filesystem semantics then the file list should be NULL.

In some situations (dealing with unverified data), the datasets can be opened in another process through the GDAL API Proxy mechanism.

For drivers supporting the VSI virtual file API, it is possible to open a file in a .zip archive (see VSIInstallZipFileHandler()), a .tar/.tar.gz/.tgz archive (see VSIInstallTarFileHandler()), or a HTTP / FTP server (see VSIInstallCurlFileHandler())

width(dataset::AbstractDataset)

Fetch raster width in pixels.

write(dataset::AbstractDataset, filename::AbstractString; kwargs...)

Writes the dataset to the designated filename.

Parameters

• dataset: The dataset to write
• filename: The filename, UTF-8 encoded.

Keyword Arguments

• driver (ArchGDAL.Driver): The driver to use, you have to manually select the right driver via getdriver(drivername) matching the file extension you wish. Otherwise the driver of the source dataset will be used.
• options (Vector{String}): A vector of strings containing KEY=VALUE pairs for driver-specific creation options.
• layers: Specifies which layers should be written. Can be e.g. a range, Vector{Int} or tuple.
• layer_options: Driver specific options for layer creation. The options can either be a Vector{String} to provide the same options for each layer, or a Vector{Vector{String}} to provide individual options per layer, in the order of their appearance in the dataset. The strings have to be KEY=VALUE pairs. If you give less individual options than there are layers, the remaining layers use the default creation options. An example for two layers: Dict(0 => ["FORMAT=WKT", "LAUNDER=NO"], 1 => ["STRICT=NO"])
• use_gdal_copy (Bool): Set this to false (default is true) to achieve higher write speeds at the cost of possible errors. Note that when set to true, no coordinate transformations are possible while writing the features.
• chunksize (Integer): Number of features to write in one database transaction. Neglected when use_gdal_copy is true. Default is 20000.
• strict (Bool): Set this to true if the written dataset should be a 1:1 copy of the source data, default is false, which allows the driver to adapt if necessary.

Returns

`nothing`

writelayers(dataset, filename; kwargs...)

Writes the vector dataset to the designated filename. The options are passed to the newly created dataset and have to be given as a list of strings in KEY=VALUE format. The chunksize controls the number of features written in each database transaction, e.g. for SQLite. This function can also be used to copy datasets on disk.

Currently working drivers: FlatGeobuf, GeoJSON, GeoJSONSeq, GML, GPKG, JML, KML, MapML, ESRI Shapefile, SQLite

Parameters

• dataset The source dataset
• filename The file name to write to

Keyword arguments

• driver: The driver to use, you have to manually select the right driver for the file extension you wish
• options: A vector of strings containing KEY=VALUE pairs for driver-specific creation options
• layer_indices: Specifies which layers should be written. Can be e.g. a range, Vector{Int} or tuple.
• layer_options: Driver specific options for layer creation. The options can either be a Vector{String} to provide the same options for each layer, or a Dict(layer_index => Vector{String}) to provide individual options per layer. Note that layer indexing in GDAL starts with 0. The strings have to be KEY=VALUE pairs. An example for two layers: Dict(0 => ["FORMAT=WKT", "LAUNDER=NO"], 1 => ["STRICT=NO"])
• chunksize: Number of features to write in one database transaction. Neglected when use_gdal_copy is true.
• use_gdal_copy: Set this to false (default is true) to achieve higher write speeds at the cost of possible errors. Note that when set to true, no coordinate transformations are possible while writing the features.

Returns

nothing

asbinary(feature::AbstractFeature, i::Integer)

Fetch field value as binary.

Parameters

• hFeat: handle to the feature that owned the field.
• iField: the field to fetch, from 0 to GetFieldCount()-1.

Returns

the field value. This list is internal, and should not be modified, or freed. Its lifetime may be very brief.

asbool(feature::AbstractFeature, i::Integer)

Fetch field value as a boolean

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

asdatetime(feature::AbstractFeature, i::Integer)

Fetch field value as date and time. Currently this method only works for OFTDate, OFTTime and OFTDateTime fields.

Parameters

• hFeat: handle to the feature that owned the field.
• iField: the field to fetch, from 0 to GetFieldCount()-1.

Returns

true on success or false on failure.

asdouble(feature::AbstractFeature, i::Integer)

Fetch field value as a double.

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

asdoublelist(feature::AbstractFeature, i::Integer)

Fetch field value as a list of doubles.

Parameters

• hFeat: handle to the feature that owned the field.
• iField: the field to fetch, from 0 to GetFieldCount()-1.
• pnCount: an integer to put the list count (number of doubles) into.

Returns

the field value. This list is internal, and should not be modified, or freed. Its lifetime may be very brief. If *pnCount is zero on return the returned pointer may be NULL or non-NULL.

asint(feature::AbstractFeature, i::Integer)

Fetch field value as integer.

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

asint16(feature::AbstractFeature, i::Integer)

Fetch field value as integer 16 bit.

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

asint64(feature::AbstractFeature, i::Integer)

Fetch field value as integer 64 bit.

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

asint64list(feature::AbstractFeature, i::Integer)

Fetch field value as a list of 64 bit integers.

Parameters

• hFeat: handle to the feature that owned the field.
• iField: the field to fetch, from 0 to GetFieldCount()-1.
• pnCount: an integer to put the list count (number of integers) into.

Returns

the field value. This list is internal, and should not be modified, or freed. Its lifetime may be very brief. If *pnCount is zero on return the returned pointer may be NULL or non-NULL.

asintlist(feature::AbstractFeature, i::Integer)

Fetch field value as a list of integers.

Parameters

• hFeat: handle to the feature that owned the field.
• iField: the field to fetch, from 0 to GetFieldCount()-1.
• pnCount: an integer to put the list count (number of integers) into.

Returns

the field value. This list is internal, and should not be modified, or freed. Its lifetime may be very brief. If *pnCount is zero on return the returned pointer may be NULL or non-NULL.

assingle(feature::AbstractFeature, i::Integer)

Fetch field value as a single.

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

asstring(feature::AbstractFeature, i::Integer)

Fetch field value as a string.

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

asstringlist(feature::AbstractFeature, i::Integer)

Fetch field value as a list of strings.

Parameters

• hFeat: handle to the feature that owned the field.
• iField: the field to fetch, from 0 to GetFieldCount()-1.

Returns

the field value. This list is internal, and should not be modified, or freed. Its lifetime may be very brief.

destroy(feature::AbstractFeature)

Destroy the feature passed in.

The feature is deleted, but within the context of the GDAL/OGR heap. This is necessary when higher level applications use GDAL/OGR from a DLL and they want to delete a feature created within the DLL. If the delete is done in the calling application the memory will be freed onto the application heap which is inappropriate.

fillunsetwithdefault!(feature::AbstractFeature; notnull = true,
    options = StringList(C_NULL))

Fill unset fields with default values that might be defined.

Parameters

• feature: handle to the feature.
• notnull: if we should fill only unset fields with a not-null constraint.
• papszOptions: unused currently. Must be set to NULL.

References

• https://gdal.org/development/rfc/rfc53ogrnotnull_default.html

findfieldindex(feature::AbstractFeature, name::Union{AbstractString, Symbol})

Fetch the field index given field name.

Parameters

• feature: the feature on which the field is found.
• name: the name of the field to search for.

Returns

the field index, or nothing if no matching field is found.

Remarks

This is a cover for the OGRFeatureDefn::GetFieldIndex() method.

findgeomindex(feature::AbstractFeature, name::Union{AbstractString, Symbol} = "")

Fetch the geometry field index given geometry field name.

Parameters

• feature: the feature on which the geometry field is found.
• name: the name of the geometry field to search for. (defaults to "")

Returns

the geometry field index, or -1 if no matching geometry field is found.

Remarks

This is a cover for the OGRFeatureDefn::GetGeomFieldIndex() method.

getfid(feature::AbstractFeature)

Get feature identifier.

Returns

feature id or OGRNullFID (-1) if none has been assigned.

getfield(feature, i)

When the field is unset, it will return nothing. When the field is set but null, it will return missing.

References

• https://gdal.org/development/rfc/rfc53ogrnotnull_default.html
• https://gdal.org/development/rfc/rfc67_nullfieldvalues.html

getfielddefn(feature::AbstractFeature, i::Integer)

Fetch definition for this field.

Parameters

• feature: the feature on which the field is found.
• i: the field to fetch, from 0 to GetFieldCount()-1.

Returns

an handle to the field definition (from the FeatureDefn). This is an internal reference, and should not be deleted or modified.

getgeom(feature::AbstractFeature, i::Integer)

Returns a clone of the feature geometry at index i.

Parameters

• feature: the feature to get geometry from.
• i: geometry field to get.

getgeom(feature::AbstractFeature)

Returns a clone of the geometry corresponding to the feature.

getgeomdefn(feature::AbstractFeature, i::Integer)

Fetch definition for this geometry field.

Parameters

• feature: the feature on which the field is found.
• i: the field to fetch, from 0 to GetGeomFieldCount()-1.

Returns

The field definition (from the OGRFeatureDefn). This is an internal reference, and should not be deleted or modified.

getmediatype(feature::AbstractFeature)

Returns the native media type for the feature.

The native media type is the identifier for the format of the native data. It follows the IANA RFC 2045 (see https://en.wikipedia.org/wiki/Media_type), e.g. "application/vnd.geo+json" for JSON.

getnativedata(feature::AbstractFeature)

Returns the native data for the feature.

The native data is the representation in a "natural" form that comes from the driver that created this feature, or that is aimed at an output driver. The native data may be in different format, which is indicated by GetNativeMediaType().

Note that most drivers do not support storing the native data in the feature object, and if they do, generally the NATIVE_DATA open option must be passed at dataset opening.

The "native data" does not imply it is something more performant or powerful than what can be obtained with the rest of the API, but it may be useful in round-tripping scenarios where some characteristics of the underlying format are not captured otherwise by the OGR abstraction.

getstylestring(feature::AbstractFeature)

Fetch style string for this feature.

getstyletable(feature::AbstractFeature)

Fetch style table for this feature.

isfieldnull(feature::AbstractFeature, i::Integer)

Test if a field is null.

Parameters

• feature: the feature that owned the field.
• i: the field to test, from 0 to GetFieldCount()-1.

Returns

true if the field is null, otherwise false.

References

• https://gdal.org/development/rfc/rfc67_nullfieldvalues.html

isfieldset(feature::AbstractFeature, i::Integer)

Test if a field has ever been assigned a value or not.

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

isfieldsetandnotnull(feature::AbstractFeature, i::Integer)

Test if a field is set and not null.

Parameters

• feature: the feature that owned the field.
• i: the field to test, from 0 to GetFieldCount()-1.

Returns

true if the field is set and not null, otherwise false.

References

• https://gdal.org/development/rfc/rfc67_nullfieldvalues.html

nfield(feature::AbstractFeature)

Fetch number of fields on this feature.

This will always be the same as the field count for the OGRFeatureDefn.

ngeom(feature::AbstractFeature)

Fetch number of geometry fields on this feature.

This will always be the same as the geometry field count for OGRFeatureDefn.

setfid!(feature::AbstractFeature, i::Integer)

Set the feature identifier.

Parameters

• feature: handle to the feature to set the feature id to.
• i: the new feature identifier value to assign.

Returns

On success OGRERR_NONE, or on failure some other value.

setfield!(feature::AbstractFeature, i::Integer, value)
setfield!(feature::AbstractFeature, i::Integer, value::DateTime, tzflag::Int = 0)

Set a feature's i-th field to value.

The following types for value are accepted: Int32, Int64, Float64, AbstractString, or a Vector with those in it, as well as Vector{UInt8}. For DateTime values, an additional keyword argument tzflag is accepted (0=unknown, 1=localtime, 100=GMT, see data model for details).

OFTInteger, OFTInteger64 and OFTReal fields will be set directly. OFTString fields will be assigned a string representation of the value, but not necessarily taking into account formatting constraints on this field. Other field types may be unaffected.

Parameters

• feature: handle to the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.
• value: the value to assign.

setfieldnull!(feature::AbstractFeature, i::Integer)

Clear a field, marking it as null.

Parameters

• feature: the feature that owned the field.
• i: the field to set to null, from 0 to GetFieldCount()-1.

References

• https://gdal.org/development/rfc/rfc67_nullfieldvalues.html

setfrom!(feature1::AbstractFeature, feature2::AbstractFeature, forgiving::Bool = false)
setfrom!(feature1::AbstractFeature, feature2::AbstractFeature, indices::Vector{Cint},
    forgiving::Bool = false)

Set one feature from another.

Parameters

• feature1: handle to the feature to set to.
• feature2: handle to the feature from which geometry, and field values will be copied.
• indices: indices of the destination feature's fields stored at the corresponding index of the source feature's fields. A value of -1 should be used to ignore the source's field. The array should not be NULL and be as long as the number of fields in the source feature.
• forgiving: true if the operation should continue despite lacking output fields matching some of the source fields.

Returns

OGRERR_NONE if the operation succeeds, even if some values are not transferred, otherwise an error code.

setgeom!(feature::AbstractFeature, geom::AbstractGeometry)

Set feature geometry.

This method updates the features geometry, and operate exactly as SetGeometryDirectly(), except that this method does not assume ownership of the passed geometry, but instead makes a copy of it.

Parameters

• feature: the feature on which new geometry is applied to.
• geom: the new geometry to apply to feature.

Returns

OGRERR_NONE if successful, or OGR_UNSUPPORTED_GEOMETRY_TYPE if the geometry type is illegal for the OGRFeatureDefn (checking not yet implemented).

setgeom!(feature::AbstractFeature, i::Integer, geom::AbstractGeometry)

Set feature geometry of a specified geometry field.

This function updates the features geometry, and operate exactly as SetGeometryDirectly(), except that this function does not assume ownership of the passed geometry, but instead makes a copy of it.

Parameters

• feature: the feature on which to apply the geometry.
• i: geometry field to set.
• geom: the new geometry to apply to feature.

Returns

OGRERR_NONE if successful, or OGR_UNSUPPORTED_GEOMETRY_TYPE if the geometry type is illegal for the OGRFeatureDefn (checking not yet implemented).

setmediatype!(feature::AbstractFeature, mediatype::AbstractString)

Sets the native media type for the feature.

The native media type is the identifier for the format of the native data. It follows the IANA RFC 2045 (see https://en.wikipedia.org/wiki/Media_type), e.g. "application/vnd.geo+json" for JSON.

setnativedata!(feature::AbstractFeature, data::AbstractString)

Sets the native data for the feature.

The native data is the representation in a "natural" form that comes from the driver that created this feature, or that is aimed at an output driver. The native data may be in different format, which is indicated by GetNativeMediaType().

setstylestring!(feature::AbstractFeature, style::AbstractString)

Set feature style string.

This method operate exactly as setstylestringdirectly!() except that it doesn't assume ownership of the passed string, but makes a copy of it.

setstyletable!(feature::AbstractFeature, styletable::StyleTable)

Set the style table for this feature.

unsafe_clone(feature::AbstractFeature)

Duplicate feature.

The newly created feature is owned by the caller, and will have its own reference to the OGRFeatureDefn.

unsetfield!(feature::AbstractFeature, i::Integer)

Clear a field, marking it as unset.

Parameters

• feature: the feature that owned the field.
• i: the field to fetch, from 0 to GetFieldCount()-1.

validate(feature::AbstractFeature, flags::Integer, emiterror::Bool)

Validate that a feature meets constraints of its schema.

The scope of test is specified with the nValidateFlags parameter.

Regarding OGR_F_VAL_WIDTH, the test is done assuming the string width must be interpreted as the number of UTF-8 characters. Some drivers might interpret the width as the number of bytes instead. So this test is rather conservative (if it fails, then it will fail for all interpretations).

Parameters

• feature: handle to the feature to validate.
• flags: OGR_F_VAL_ALL or combination of OGR_F_VAL_NULL, OGR_F_VAL_GEOM_TYPE, OGR_F_VAL_WIDTH and OGR_F_VAL_ALLOW_NULL_WHEN_DEFAULT with | operator
• emiterror: true if a CPLError() must be emitted when a check fails

Returns

true if all enabled validation tests pass.

References

• https://gdal.org/development/rfc/rfc53ogrnotnull_default.html

keys(feature::AbstractFeature)

Fetch the keys or names on this feature.

values(feature::AbstractFeature)

Fetch the values this feature.

addfielddefn!(featuredefn::FeatureDefn, fielddefn::FieldDefn)

Add a new field definition to the passed feature definition.

To add a new field definition to a layer definition, do not use this function directly, but use OGRLCreateField() instead.

This function should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn. The OGRFieldDefn passed in is copied, and remains the responsibility of the caller.

addgeomdefn!(featuredefn::FeatureDefn, geomfielddefn::AbstractGeomFieldDefn)

Add a new field definition to the passed feature definition.

To add a new geometry field definition to a layer definition, do not use this function directly, but use OGRLayer::CreateGeomField() instead.

This method does an internal copy of the passed geometry field definition, unless bCopy is set to false (in which case it takes ownership of the field definition.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn.

deletefielddefn!(featuredefn::FeatureDefn, i::Integer)

Delete an existing field definition.

To delete an existing field definition from a layer definition, do not use this function directly, but use OGR_L_DeleteField() instead.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn.

deletegeomdefn!(featuredefn::FeatureDefn, i::Integer)

Delete an existing geometry field definition.

To delete an existing field definition from a layer definition, do not use this function directly, but use OGRLayer::DeleteGeomField() instead.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn.

dereference(featuredefn::FeatureDefn)

Decrements the reference count by one, and returns the updated count.

Destroy a feature definition object and release all memory associated with it

Destroy a feature definition view

findfieldindex(featuredefn::AbstractFeatureDefn,
    name::Union{AbstractString, Symbol})

Find field by name.

Returns

the field index, or -1 if no match found.

Remarks

This uses the OGRFeatureDefn::GetFieldIndex() method.

findgeomindex(featuredefn::AbstractFeatureDefn, name::AbstractString = "")

Find geometry field by name.

The geometry field index of the first geometry field matching the passed field name (case insensitively) is returned.

Returns

the geometry field index, or -1 if no match found.

getfeaturedefn(feature::AbstractFeature)

Fetch feature definition.

getfielddefn(featuredefn::FeatureDefn, i::Integer)

Fetch field definition of the passed feature definition.

Parameters

• featuredefn: the feature definition to get the field definition from.
• i: index of the field to fetch, between 0 and nfield(featuredefn)-1.

Returns

an handle to an internal field definition object or NULL if invalid index. This object should not be modified or freed by the application.

getgeomdefn(featuredefn::FeatureDefn, i::Integer = 0)

Fetch geometry field definition of the passed feature definition.

Parameters

• i geometry field to fetch, between 0 (default) and ngeomfield(fd)-1.

Returns

an internal field definition object or NULL if invalid index. This object should not be modified or freed by the application.

getgeomtype(featuredefn::AbstractFeatureDefn)

Fetch the geometry base type of the passed feature definition.

For layers without any geometry field, this method returns wkbNone.

This returns the same result as OGR_FD_GetGeomType(OGR_L_GetLayerDefn(hLayer)) but for a few drivers, calling OGR_L_GetGeomType() directly can avoid lengthy layer definition initialization.

For layers with multiple geometry fields, this method only returns the geometry type of the first geometry column. For other columns, use OGR_GFld_GetType(OGR_FD_GetGeomFieldDefn(OGR_L_GetLayerDefn(hLayer), i)).

getname(featuredefn::AbstractFeatureDefn)

Get name of the OGRFeatureDefn passed as an argument.

isgeomignored(featuredefn::AbstractFeatureDefn)

Determine whether the geometry can be omitted when fetching features.

issame(featuredefn1::AbstractFeatureDefn, featuredefn2::AbstractFeatureDefn)

Test if the feature definition is identical to the other one.

isstyleignored(featuredefn::AbstractFeatureDefn)

Determine whether the style can be omitted when fetching features.

nfield(featuredefn::AbstractFeatureDefn)

Fetch number of fields on the passed feature definition.

ngeom(featuredefn::AbstractFeatureDefn)

Fetch number of geometry fields on the passed feature definition.

nreference(featuredefn::AbstractFeatureDefn)

Fetch the current reference count.

reference(featuredefn::FeatureDefn)

Increments the reference count in the FeatureDefn by one.

The count is used to track the number of Features referencing this definition.

Returns

The updated reference count.

release(featuredefn::FeatureDefn)

Drop a reference, and destroy if unreferenced.

reorderfielddefns!(featuredefn::FeatureDefn, indices::Vector{Cint})

Reorder the field definitions in the array of the feature definition.

To reorder the field definitions in a layer definition, do not use this function directly, but use OGR_L_ReorderFields() instead.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn.

Parameters

• fd: handle to the feature definition.
• indices: an array of GetFieldCount() elements which is a permutation of [0, GetFieldCount()-1]. indices is such that, for each field definition at position i after reordering, its position before reordering was indices[i].

setgeomignored!(featuredefn::FeatureDefn, ignore::Bool)

Set whether the geometry can be omitted when fetching features.

setgeomtype!(featuredefn::FeatureDefn, etype::OGRwkbGeometryType)

Assign the base geometry type for the passed layer (same as the fd).

All geometry objects using this type must be of the defined type or a derived type. The default upon creation is wkbUnknown which allows for any geometry type. The geometry type should generally not be changed after any OGRFeatures have been created against this definition.

setstyleignored!(featuredefn::FeatureDefn, ignore::Bool)

Set whether the style can be omitted when fetching features.

unsafe_createfeature(featuredefn::AbstractFeatureDefn)

Returns the new feature object with null fields and no geometry

Note that the OGRFeature will increment the reference count of it's defining OGRFeatureDefn. Destruction of the OGRFeatureDefn before destruction of all OGRFeatures that depend on it is likely to result in a crash.

Starting with GDAL 2.1, returns NULL in case out of memory situation.

unsafe_createfeaturedefn(name::AbstractString)

Create a new feature definition object to hold field definitions.

The FeatureDefn maintains a reference count, but this starts at zero, and should normally be incremented by the owner.

addfeature!(layer::AbstractFeatureLayer, feature::AbstractFeature)

Write a new feature within a layer.

Remarks

The passed feature is written to the layer as a new feature, rather than overwriting an existing one. If the feature has a feature id other than OGRNullFID, then the native implementation may use that as the feature id of the new feature, but not necessarily. Upon successful return the passed feature will have been updated with the new feature id.

addfielddefn!(layer::AbstractFeatureLayer, field::AbstractFieldDefn,
    approx = false)

Create a new field on a layer.

Parameters

• layer: the layer to write the field definition.
• field: the field definition to write to disk.
• approx: If true, the field may be created in a slightly different form depending on the limitations of the format driver.

Remarks

You must use this to create new fields on a real layer. Internally the OGRFeatureDefn for the layer will be updated to reflect the new field. Applications should never modify the OGRFeatureDefn used by a layer directly.

This function should not be called while there are feature objects in existence that were obtained or created with the previous layer definition.

Not all drivers support this function. You can query a layer to check if it supports it with the GDAL.OLCCreateField capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existing features of the backing file/database should be updated accordingly.

Drivers may or may not support not-null constraints. If they support creating fields with not-null constraints, this is generally before creating any feature to the layer.

addgeomdefn!(layer::AbstractFeatureLayer, field::AbstractGeomFieldDefn,
    approx = false)

Create a new geometry field on a layer.

Parameters

• layer: the layer to write the field definition.
• field: the geometry field definition to write to disk.
• approx: If true, the field may be created in a slightly different form depending on the limitations of the format driver.

Remarks

You must use this to create new geometry fields on a real layer. Internally the OGRFeatureDefn for the layer will be updated to reflect the new field. Applications should never modify the OGRFeatureDefn used by a layer directly.

This function should not be called while there are feature objects in existence that were obtained or created with the previous layer definition.

Not all drivers support this function. You can query a layer to check if it supports it with the GDAL.OLCCreateGeomField capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existing features of the backing file/database should be updated accordingly.

Drivers may or may not support not-null constraints. If they support creating fields with not-null constraints, this is generally before creating any feature to the layer.

copy(layer, dataset, name, options)

Copy an existing layer.

This method creates a new layer, duplicate the field definitions of the source layer, and then duplicates each feature of the source layer.

Parameters

• layer: source layer to be copied.

Keyword Arguments

• dataset: the dataset handle. (Creates a new dataset in memory by default.)
• name: the name of the layer to create on the dataset.
• options: a StringList of name=value (driver-specific) options.

createlayer(name, dataset, geom, spatialref, options)

This function attempts to create a new layer on the dataset with the indicated name, spatialref, and geometry type.

Keyword Arguments

• name: the name for the new layer. This should ideally not match any existing layer on the datasource. Defaults to an empty string.
• dataset: the dataset. Defaults to creating a new in memory dataset.
• geom: the geometry type for the layer. Use wkbUnknown (default) if there are no constraints on the types geometry to be written.
• spatialref: the coordinate system to use for the new layer.
• options: a StringList of name=value (driver-specific) options.

deletefeature!(layer::AbstractFeatureLayer, i::Integer)

Delete feature with fid i from layer.

Remarks

The feature with the indicated feature id is deleted from the layer if supported by the driver. Most drivers do not support feature deletion, and will return OGRERRUNSUPPORTEDOPERATION. The OGRLTestCapability() function may be called with OLCDeleteFeature to check if the driver supports feature deletion.

dereference(layer::AbstractFeatureLayer)

Decrement layer reference count.

Returns

The reference count after decrementing.

envelope(layer::AbstractFeatureLayer, force::Bool = false)
envelope(layer::AbstractFeatureLayer, i::Integer, force::Bool = false)

Fetch the extent of this layer.

Returns the extent (MBR) of the data in the layer. If force is false, and it would be expensive to establish the extent then OGRERR_FAILURE will be returned indicating that the extent isn't know. If force is true then some implementations will actually scan the entire layer once to compute the MBR of all the features in the layer.

Parameters

• layer: handle to the layer from which to get extent.
• i: (optional) the index of the geometry field to compute the extent.
• force: Flag indicating whether the extent should be computed even if it is expensive.

Additional Remarks

Depending on the drivers, the returned extent may or may not take the spatial filter into account. So it is safer to call GetExtent() without setting a spatial filter.

Layers without any geometry may return OGRERR_FAILURE just indicating that no meaningful extents could be collected.

Note that some implementations of this method may alter the read cursor of the layer.

fidcolumnname(layer::AbstractFeatureLayer)

The name of the FID column in the database, or "" if not supported.

findfieldindex(layer::AbstractFeatureLayer,
    field::Union{AbstractString, Symbol}, exactmatch::Bool)

Find the index of the field in a layer, or -1 if the field doesn't exist.

If exactmatch is set to false and the field doesn't exists in the given form the driver might apply some changes to make it match, like those it might do if the layer was created (eg. like LAUNDER in the OCI driver).

geomcolumnname(layer::AbstractFeatureLayer)

The name of the geometry column in the database, or "" if not supported.

getgeomtype(layer::AbstractFeatureLayer)

Return the layer geometry type.

getname(layer::AbstractFeatureLayer)

Return the layer name.

getspatialfilter(layer::AbstractFeatureLayer)

Returns the current spatial filter for this layer.

getspatialref(layer::AbstractFeatureLayer)

Returns a clone of the spatial reference system for this layer.

layerdefn(layer::AbstractFeatureLayer)

Returns a view of the schema information for this layer.

Remarks

The featuredefn is owned by the layer and should not be modified.

nfeature(layer::AbstractFeatureLayer, force::Bool = false)

Fetch the feature count in this layer, or -1 if the count is not known.

Parameters

• layer: handle to the layer that owned the features.
• force: flag indicating whether the count should be computed even if it is expensive. (false by default.)

nfield(layer::AbstractFeatureLayer)

Fetch number of fields on the feature layer.

ngeom(layer::AbstractFeatureLayer)

Fetch number of geometry fields on the feature layer.

nreference(layer::AbstractFeatureLayer)

The current reference count for the layer object itself.

reference(layer::AbstractFeatureLayer)

Increment layer reference count.

Returns

The reference count after incrementing.

resetreading!(layer::AbstractFeatureLayer)

Reset feature reading to start on the first feature.

This affects nextfeature().

setattributefilter!(layer::AbstractFeatureLayer, query::AbstractString)

Set a new attribute query.

This method sets the attribute query string to be used when fetching features via the nextfeature() method. Only features for which the query evaluates as true will be returned.

Parameters

• layer: handle to the layer on which attribute query will be executed.
• query: query in restricted SQL WHERE format.

Remarks

The query string should be in the format of an SQL WHERE clause. For instance "population > 1000000 and population < 5000000" where population is an attribute in the layer. The query format is normally a restricted form of SQL WHERE clause as described in the "WHERE" section of the OGR SQL tutorial. In some cases (RDBMS backed drivers) the native capabilities of the database may be used to interpret the WHERE clause in which case the capabilities will be broader than those of OGR SQL.

Note that installing a query string will generally result in resetting the current reading position (ala resetreading!()).

setfeature!(layer::AbstractFeatureLayer, feature::AbstractFeature)

Rewrite an existing feature.

This function will write a feature to the layer, based on the feature id within the OGRFeature.

Remarks

Use OGRLTestCapability(OLCRandomWrite) to establish if this layer supports random access writing via OGRLSetFeature().

setignoredfields!(layer::AbstractFeatureLayer, fieldnames)

Set which fields can be omitted when retrieving features from the layer.

Parameters

• fieldnames: an array of field names terminated by NULL item. If NULL is

passed, the ignored list is cleared.

Remarks

If the driver supports this functionality (testable using OLCIgnoreFields capability), it will not fetch the specified fields in subsequent calls to GetFeature()/nextfeature() and thus save some processing time and/or bandwidth.

Besides field names of the layers, the following special fields can be passed: "OGR_GEOMETRY" to ignore geometry and "OGR_STYLE" to ignore layer style.

By default, no fields are ignored.

setnextbyindex!(layer::AbstractFeatureLayer, i::Integer)

Move read cursor to the i-th feature in the current resultset.

This method allows positioning of a layer such that the nextfeature() call will read the requested feature, where i is an absolute index into the current result set. So, setting it to 3 would mean the next feature read with nextfeature() would have been the fourth feature to have been read if sequential reading took place from the beginning of the layer, including accounting for spatial and attribute filters.

Parameters

• layer: handle to the layer
• i: the index indicating how many steps into the result set to seek.

Remarks

Only in rare circumstances is setnextbyindex!() efficiently implemented. In all other cases the default implementation which calls resetreading!() and then calls nextfeature() i times is used. To determine if fast seeking is available on the layer, use the testcapability() method with a value of OLCFastSetNextByIndex.

setspatialfilter!(layer::AbstractFeatureLayer, geom::AbstractGeometry)

Set a new spatial filter for the layer, using the geom.

This method set the geometry to be used as a spatial filter when fetching features via the nextfeature() method. Only features that geometrically intersect the filter geometry will be returned.

Parameters

• layer handle to the layer on which to set the spatial filter.
• geom handle to the geometry to use as a filtering region. NULL may be passed indicating that the current spatial filter should be cleared, but no new one instituted.

Remarks

Currently this test may be inaccurately implemented, but it is guaranteed that all features whose envelope (as returned by OGRGeometry::getEnvelope()) overlaps the envelope of the spatial filter will be returned. This can result in more shapes being returned that should strictly be the case.

For the time being the passed filter geometry should be in the same SRS as the geometry field definition it corresponds to (as returned by GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(i)->GetSpatialRef()). In the future this may be generalized.

Note that only the last spatial filter set is applied, even if several successive calls are done with different iGeomField values.

setspatialfilter!(layer::AbstractFeatureLayer, i::Integer,
    geom::AbstractGeometry)

Set a new spatial filter.

This method set the geometry to be used as a spatial filter when fetching features via the nextfeature() method. Only features that geometrically intersect the filter geometry will be returned.

Parameters

• layer: the layer on which to set the spatial filter.
• i: index of the geometry field on which the spatial filter operates.
• geom: the geometry to use as a filtering region. NULL may be passed indicating that the current spatial filter should be cleared, but no new one instituted.

Remarks

Currently this test is may be inaccurately implemented, but it is guaranteed that all features who's envelope (as returned by OGRGeometry::getEnvelope()) overlaps the envelope of the spatial filter will be returned. This can result in more shapes being returned that should strictly be the case.

For the time being the passed filter geometry should be in the same SRS as the layer (as returned by OGRLayer::GetSpatialRef()). In the future this may be generalized.

setspatialfilter!(layer::AbstractFeatureLayer, i::Integer, xmin, ymin, xmax,
    ymax)

Set a new rectangular spatial filter.

Parameters

• layer: the feature layer on which to set the spatial filter.
• i: index of the geometry field on which the spatial filter operates.
• xmin: the minimum X coordinate for the rectangular region.
• ymin: the minimum Y coordinate for the rectangular region.
• xmax: the maximum X coordinate for the rectangular region.
• ymax: the maximum Y coordinate for the rectangular region.

setspatialfilter!(layer::AbstractFeatureLayer, xmin, ymin, xmax, ymax)

Set a new rectangular spatial filter for the layer.

This method set rectangle to be used as a spatial filter when fetching features via the nextfeature() method. Only features that geometrically intersect the given rectangle will be returned.

The x/y values should be in the same coordinate system as the layer as a whole (as returned by OGRLayer::GetSpatialRef()). Internally this method is normally implemented as creating a 5 vertex closed rectangular polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as a convenience.

The only way to clear a spatial filter set with this method is to call OGRLayer::SetSpatialFilter(NULL).

testcapability(layer::AbstractFeatureLayer, capability::AbstractString)

Test if this layer supported the named capability.

Parameters

• capability the name of the capability to test.

Returns

true if the layer has the requested capability, false otherwise. It will return false for any unrecognized capabilities.

Additional Remarks

The capability codes that can be tested are represented as strings, but #defined constants exists to ensure correct spelling. Specific layer types may implement class specific capabilities, but this can't generally be discovered by the caller.

• OLCRandomRead / "RandomRead": true if the GetFeature() method is implemented in an optimized way for this layer, as opposed to the default implementation using resetreading!() and nextfeature() to find the requested feature id.

• OLCSequentialWrite / "SequentialWrite": true if the CreateFeature() method works for this layer. Note this means that this particular layer is writable. The same OGRLayer class may returned false for other layer instances that are effectively read-only.

• OLCRandomWrite / "RandomWrite": true if the SetFeature() method is operational on this layer. Note this means that this particular layer is writable. The same OGRLayer class may returned false for other layer instances that are effectively read-only.

• OLCFastSpatialFilter / "FastSpatialFilter": true if this layer implements spatial filtering efficiently. Layers that effectively read all features, and test them with the OGRFeature intersection methods should return false. This can be used as a clue by the application whether it should build and maintain its own spatial index for features in this layer.

• OLCFastFeatureCount / "FastFeatureCount": true if this layer can return a feature count (via GetFeatureCount()) efficiently. i.e. without counting the features. In some cases this will return true until a spatial filter is installed after which it will return false.

• OLCFastGetExtent / "FastGetExtent": true if this layer can return its data extent (via GetExtent()) efficiently, i.e. without scanning all the features. In some cases this will return true until a spatial filter is installed after which it will return false.

• OLCFastSetNextByIndex / "FastSetNextByIndex": true if this layer can perform the SetNextByIndex() call efficiently, otherwise false.

• OLCCreateField / "CreateField": true if this layer can create new fields on the current layer using CreateField(), otherwise false.

• OLCCreateGeomField / "CreateGeomField": (GDAL >= 1.11) true if this layer can create new geometry fields on the current layer using CreateGeomField(), otherwise false.

• OLCDeleteField / "DeleteField": true if this layer can delete existing fields on the current layer using DeleteField(), otherwise false.

• OLCReorderFields / "ReorderFields": true if this layer can reorder existing fields on the current layer using ReorderField() or ReorderFields(), otherwise false.

• OLCAlterFieldDefn / "AlterFieldDefn": true if this layer can alter the definition of an existing field on the current layer using AlterFieldDefn(), otherwise false.

• OLCDeleteFeature / "DeleteFeature": true if the DeleteFeature() method is supported on this layer, otherwise false.

• OLCStringsAsUTF8 / "StringsAsUTF8": true if values of OFTString fields are assured to be in UTF-8 format. If false the encoding of fields is uncertain, though it might still be UTF-8.

• OLCTransactions / "Transactions": true if the StartTransaction(), CommitTransaction() and RollbackTransaction() methods work in a meaningful way, otherwise false.

• OLCIgnoreFields / "IgnoreFields": true if fields, geometry and style will be omitted when fetching features as set by SetIgnoredFields() method.

• OLCCurveGeometries / "CurveGeometries": true if this layer supports writing curve geometries or may return such geometries. (GDAL 2.0).

unsafe_createfeature(layer::AbstractFeatureLayer)

Create and returns a new feature based on the layer definition.

The newly feature is owned by the layer (it will increase the number of features the layer by one), but the feature has not been written to the layer yet.

unsafe_getfeature(layer::AbstractFeatureLayer, i::Integer)

Return a feature (now owned by the caller) by its identifier or NULL on failure.

Parameters

• layer: the feature layer to be read from.
• i: the index of the feature to be returned.

Remarks

This function will attempt to read the identified feature. The nFID value cannot be OGRNullFID. Success or failure of this operation is unaffected by the spatial or attribute filters (and specialized implementations in drivers should make sure that they do not take into account spatial or attribute filters).

If this function returns a non-NULL feature, it is guaranteed that its feature id (OGRFGetFID()) will be the same as nFID.

Use OGRLTestCapability(OLCRandomRead) to establish if this layer supports efficient random access reading via OGRLGetFeature(); however, the call should always work if the feature exists as a fallback implementation just scans all the features in the layer looking for the desired feature.

Sequential reads (with OGRLGetNextFeature()) are generally considered interrupted by a OGRLGetFeature() call.

The returned feature is now owned by the caller, and should be freed with destroy().

unsafe_nextfeature(layer::AbstractFeatureLayer)

Fetch the next available feature from this layer.

Parameters

• layer: the feature layer to be read from.

Remarks

This method implements sequential access to the features of a layer. The resetreading!() method can be used to start at the beginning again. Only features matching the current spatial filter (set with setspatialfilter!()) will be returned.

The returned feature becomes the responsibility of the caller to delete with destroy(). It is critical that all features associated with a FeatureLayer (more specifically a FeatureDefn) be destroyed before that layer is destroyed.

Features returned by nextfeature() may or may not be affected by concurrent modifications depending on drivers. A guaranteed way of seeing modifications in effect is to call resetreading!() on layers where nextfeature() has been called, before reading again. Structural changes in layers (field addition, deletion, ...) when a read is in progress may or may not be possible depending on drivers. If a transaction is committed/aborted, the current sequential reading may or may not be valid after that operation and a call to resetreading!() might be needed.

Destroy a field definition.

Destroy a geometry field definition.

Destroy a geometry field definition view.

getdefault(fielddefn::AbstractFieldDefn)

Get default field value

References

• https://gdal.org/development/rfc/rfc53ogrnotnull_default.html

getfieldtype(fielddefn::AbstractFieldDefn)

Returns the type or subtype (if any) of this field.

Parameters

• fielddefn: handle to the field definition.

Returns

The field type or subtype.

References

• https://gdal.org/development/rfc/rfc50ogrfield_subtype.html

getjustify(fielddefn::AbstractFieldDefn)

Get the justification for this field.

Note: no driver is know to use the concept of field justification.

Fetch the name of this field.

Fetch name of this field.

getprecision(fielddefn::AbstractFieldDefn)

Get the formatting precision for this field.

This should normally be zero for fields of types other than OFTReal.

getspatialref(geomdefn::AbstractGeomFieldDefn)

Returns a clone of the spatial reference system for this field. May be NULL.

getsubtype(fielddefn::AbstractFieldDefn)

Fetch subtype of this field.

Parameters

• fielddefn: handle to the field definition to get subtype from.

Returns

field subtype.

Fetch the type of this field.

Fetch geometry type of this field.

getwidth(fielddefn::AbstractFieldDefn)

Get the formatting width for this field.

Returns

the width, zero means no specified width.

isdefaultdriverspecific(fielddefn::AbstractFieldDefn)

Returns whether the default value is driver specific.

Driver specific default values are those that are not NULL, a numeric value, a literal value enclosed between single quote characters, CURRENTTIMESTAMP, CURRENTTIME, CURRENT_DATE or datetime literal value.

References

• https://gdal.org/development/rfc/rfc53ogrnotnull_default.html

isignored(fielddefn::AbstractFieldDefn)

Return whether this field should be omitted when fetching features.

isignored(geomdefn::AbstractGeomFieldDefn)

Return whether this field should be omitted when fetching features.

isnullable(fielddefn::AbstractFieldDefn)

Return whether this field can receive null values.

By default, fields are nullable.

Even if this method returns false (i.e not-nullable field), it doesn't mean that OGRFeature::IsFieldSet() will necessarily return true, as fields can be temporarily unset and null/not-null validation is usually done when OGRLayer::CreateFeature()/SetFeature() is called.

References

• https://gdal.org/development/rfc/rfc53ogrnotnull_default.html

isnullable(geomdefn::AbstractGeomFieldDefn)

Return whether this geometry field can receive null values.

By default, fields are nullable.

Even if this method returns false (i.e not-nullable field), it doesn't mean that OGRFeature::IsFieldSet() will necessary return true, as fields can be temporarily unset and null/not-null validation is usually done when OGRLayer::CreateFeature()/SetFeature() is called.

Note that not-nullable geometry fields might also contain 'empty' geometries.

setdefault!(fielddefn::AbstractFieldDefn, default)

Set default field value.

The default field value is taken into account by drivers (generally those with a SQL interface) that support it at field creation time. OGR will generally not automatically set the default field value to null fields by itself when calling OGRFeature::CreateFeature() / OGRFeature::SetFeature(), but will let the low-level layers to do the job. So retrieving the feature from the layer is recommended.

The accepted values are NULL, a numeric value, a literal value enclosed between single quote characters (and inner single quote characters escaped by repetition of the single quote character), CURRENTTIMESTAMP, CURRENTTIME, CURRENT_DATE or a driver specific expression (that might be ignored by other drivers). For a datetime literal value, format should be 'YYYY/MM/DD HH:MM:SS[.sss]' (considered as UTC time).

Drivers that support writing DEFAULT clauses will advertize the GDALDCAPDEFAULT_FIELDS driver metadata item.

References

• https://gdal.org/development/rfc/rfc53ogrnotnull_default.html

setignored!(fielddefn::FieldDefn, ignore::Bool)

Set whether this field should be omitted when fetching features.

setignored!(geomdefn::GeomFieldDefn, ignore::Bool)

Set whether this field should be omitted when fetching features.

setjustify!(fielddefn::FieldDefn, ejustify::OGRJustification)

Set the justification for this field.

Note: no driver is know to use the concept of field justification.

Set the name of this field.

Set the name of this field.

setnullable!(geomdefn::GeomFieldDefn, nullable::Bool)

Set whether this geometry field can receive null values.

By default, fields are nullable, so this method is generally called with false to set a not-null constraint.

Drivers that support writing not-null constraint will advertize the GDALDCAPNOTNULL_GEOMFIELDS driver metadata item.

setnullable!(fielddefn::FieldDefn, nullable::Bool)

Set whether this field can receive null values.

By default, fields are nullable, so this method is generally called with false to set a not-null constraint.

Drivers that support writing not-null constraint will advertize the GDALDCAPNOTNULL_FIELDS driver metadata item.

References

• https://gdal.org/development/rfc/rfc53ogrnotnull_default.html

setparams!(fielddefn, name, etype, [nwidth, [nprecision, [justify]]])

Set defining parameters for a field in one call.

Parameters

• fielddefn: the field definition to set to.
• name: the new name to assign.
• etype: the new type (one of the OFT values like OFTInteger).
• nwidth: the preferred formatting width. 0 (default) indicates undefined.
• nprecision: number of decimals for formatting. 0 (default) for undefined.
• justify: the formatting justification ([OJUndefined], OJLeft or OJRight)

setprecision!(fielddefn::FieldDefn, precision::Integer)

Set the formatting precision for this field in characters.

This should normally be zero for fields of types other than OFTReal.

setspatialref!(geomdefn::GeomFieldDefn, spatialref::AbstractSpatialRef)

Set the spatial reference of this field.

This function drops the reference of the previously set SRS object and acquires a new reference on the passed object (if non-NULL).

setsubtype!(fielddefn::FieldDefn, subtype::OGRFieldSubType)

Set the subtype of this field.

This should never be done to an OGRFieldDefn that is already part of an OGRFeatureDefn.

Parameters

• fielddefn: handle to the field definition to set type to.
• subtype: the new field subtype.

References

• https://gdal.org/development/rfc/rfc50ogrfield_subtype.html

Set the type of this field.

Set the geometry type of this field.

setwidth!(fielddefn::FieldDefn, width::Integer)

Set the formatting width for this field in characters.

This should never be done to an OGRFieldDefn that is already part of an OGRFeatureDefn.

unsafe_createfielddefn(name::AbstractString, etype::OGRFieldType)

Create a new field definition.

By default, fields have no width, precision, are nullable and not ignored.

unsafe_creategeomdefn(name::AbstractString, etype::OGRwkbGeometryType)

Create a new field geometry definition.

addgeom!(geomcontainer::AbstractGeometry, subgeom::AbstractGeometry)

Add a geometry to a geometry container.

Some subclasses of OGRGeometryCollection restrict the types of geometry that can be added, and may return an error. The passed geometry is cloned to make an internal copy.

For a polygon, subgeom must be a linearring. If the polygon is empty, the first added subgeometry will be the exterior ring. The next ones will be the interior rings.

Parameters

• geomcontainer: existing geometry.
• subgeom: geometry to add to the existing geometry.

addpoint!(geom::AbstractGeometry, x, y)
addpoint!(geom::AbstractGeometry, x, y, z)

Add a point to a geometry (line string or point).

Parameters

• geom: the geometry to add a point to.
• x: x coordinate of point to add.
• y: y coordinate of point to add.
• z: z coordinate of point to add.

boundary(geom::AbstractGeometry)

Returns the boundary of the geometry.

A new geometry object is created and returned containing the boundary of the geometry on which the method is invoked.

boundingbox(geom::AbstractGeometry)

Returns a bounding box polygon (CW) built from envelope coordinates

buffer(geom::AbstractGeometry, dist::Real, quadsegs::Integer = 30)

Compute buffer of geometry.

Builds a new geometry containing the buffer region around the geometry on which it is invoked. The buffer is a polygon containing the region within the buffer distance of the original geometry.

Some buffer sections are properly described as curves, but are converted to approximate polygons. The nQuadSegs parameter can be used to control how many segments should be used to define a 90 degree curve - a quadrant of a circle. A value of 30 is a reasonable default. Large values result in large numbers of vertices in the resulting buffer geometry while small numbers reduce the accuracy of the result.

Parameters

• geom: the geometry.
• dist: the buffer distance to be applied. Should be expressed into the same unit as the coordinates of the geometry.
• quadsegs: the number of segments used to approximate a 90 degree (quadrant) of curvature.

centroid!(geom::AbstractGeometry, centroid::AbstractGeometry)

Compute the geometry centroid.

The centroid location is applied to the passed in OGRPoint object. The centroid is not necessarily within the geometry.

This method relates to the SFCOM ISurface::get_Centroid() method however the current implementation based on GEOS can operate on other geometry types such as multipoint, linestring, geometrycollection such as multipolygons. OGC SF SQL 1.1 defines the operation for surfaces (polygons). SQL/MM-Part 3 defines the operation for surfaces and multisurfaces (multipolygons).

centroid(geom::AbstractGeometry)

Compute the geometry centroid.

The centroid is not necessarily within the geometry.

(This method relates to the SFCOM ISurface::get_Centroid() method however the current implementation based on GEOS can operate on other geometry types such as multipoint, linestring, geometrycollection such as multipolygons. OGC SF SQL 1.1 defines the operation for surfaces (polygons). SQL/MM-Part 3 defines the operation for surfaces and multisurfaces (multipolygons).)

clone(geom::AbstractGeometry)

Returns a copy of the geometry with the original spatial reference system.

closerings!(geom::AbstractGeometry)

Force rings to be closed.

If this geometry, or any contained geometries has polygon rings that are not closed, they will be closed by adding the starting point at the end.

contains(g1::AbstractGeometry, g2::AbstractGeometry)

Returns true if g1 contains g2.

convexhull(geom::AbstractGeometry)

Returns the convex hull of the geometry.

A new geometry object is created and returned containing the convex hull of the geometry on which the method is invoked.

creategeom(geomtype::OGRwkbGeometryType)

Create an empty geometry of desired type.

This is equivalent to allocating the desired geometry with new, but the allocation is guaranteed to take place in the context of the GDAL/OGR heap.

crosses(g1::AbstractGeometry, g2::AbstractGeometry)

Returns true if the geometries are crossing.

curvegeom(geom::AbstractGeometry)

Return curve version of this geometry.

Returns a geometry that has possibly CIRCULARSTRING, COMPOUNDCURVE, CURVEPOLYGON, MULTICURVE or MULTISURFACE in it, by de-approximating linear into curve geometries.

If the geometry has no curve portion, the returned geometry will be a clone.

The reverse function is OGRGGetLinearGeometry().

delaunaytriangulation(geom::AbstractGeometry, tol::Real, onlyedges::Bool)

Return a Delaunay triangulation of the vertices of the geometry.

Parameters

• geom: the geometry.
• tol: optional snapping tolerance to use for improved robustness
• onlyedges: if true, will return a MULTILINESTRING, otherwise it will return a GEOMETRYCOLLECTION containing triangular POLYGONs.

Destroy geometry object.

Equivalent to invoking delete on a geometry, but it guaranteed to take place within the context of the GDAL/OGR heap.

Destroy prepared geometry object.

Equivalent to invoking delete on a prepared geometry, but it guaranteed to take place within the context of the GDAL/OGR heap.

difference(g1::AbstractGeometry, g2::AbstractGeometry)

Generates a new geometry which is the region of this geometry with the region of the other geometry removed.

Returns

A new geometry representing the difference of the geometries, or NULL if the difference is empty.

disjoint(g1::AbstractGeometry, g2::AbstractGeometry)

Returns true if the geometries are disjoint.

distance(g1::AbstractGeometry, g2::AbstractGeometry)

Returns the distance between the geometries or -1 if an error occurs.

empty!(geom::AbstractGeometry)

Clear geometry information.

This restores the geometry to its initial state after construction, and before assignment of actual geometry.

envelope(geom::AbstractGeometry)

Computes and returns the bounding envelope for this geometry.

envelope3d(geom::AbstractGeometry)

Computes and returns the bounding envelope (3D) for this geometry

equals(g1::AbstractGeometry, g2::AbstractGeometry)

Returns true if the geometries are equivalent.

flattento2d!(geom::AbstractGeometry)

Convert geometry to strictly 2D.

The return value will have a new type, do not continue using the original object.

forceto(geom::AbstractGeometry, targettype::OGRwkbGeometryType, [options])

Tries to force the provided geometry to the specified geometry type.

Parameters

• geom: the input geometry.
• targettype: target output geometry type.

options: (optional) options as a null-terminated vector of strings

It can promote 'single' geometry type to their corresponding collection type (see OGRGTGetCollection()) or the reverse. non-linear geometry type to their corresponding linear geometry type (see OGRGTGetLinear()), by possibly approximating circular arcs they may contain. Regarding conversion from linear geometry types to curve geometry types, only "wraping" will be done. No attempt to retrieve potential circular arcs by de-approximating stroking will be done. For that, OGRGeometry::getCurveGeometry() can be used.

The passed in geometry is cloned and a new one returned.

fromGML(data)

Create geometry from GML.

This method translates a fragment of GML containing only the geometry portion into a corresponding OGRGeometry. There are many limitations on the forms of GML geometries supported by this parser, but they are too numerous to list here.

The following GML2 elements are parsed : Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, MultiGeometry.

fromJSON(data::String)

Create a geometry object from its GeoJSON representation.

fromWKB(data)

Create a geometry object of the appropriate type from it's well known binary (WKB) representation.

Parameters

• data: pointer to the input BLOB data.

fromWKT(data::Vector{String})

Create a geometry object of the appropriate type from its well known text (WKT) representation.

Parameters

• data: input zero terminated string containing WKT representation of the geometry to be created. The pointer is updated to point just beyond that last character consumed.

geomarea(geom::AbstractGeometry)

Returns the area of the geometry or 0.0 for unsupported geometry types.

geomdim(geom::AbstractGeometry)

Get the dimension of the geometry. 0 for points, 1 for lines and 2 for surfaces.

This function corresponds to the SFCOM IGeometry::GetDimension() method. It indicates the dimension of the geometry, but does not indicate the dimension of the underlying space (as indicated by OGRGGetCoordinateDimension() function).

geomlength(geom::AbstractGeometry)

Returns the length of the geometry, or 0.0 for unsupported geometry types.

geomname(geom::AbstractGeometry)

Fetch WKT name for geometry type.

getcoorddim(geom::AbstractGeometry)

Get the dimension of the coordinates in this geometry.

Returns

This will return 2 or 3.

getgeom(geom::AbstractGeometry, i::Integer)

Fetch geometry from a geometry container.

For a polygon, getgeom(polygon,i) returns the exterior ring if i == 0, and the interior rings for i > 0.

Parameters

• geom: the geometry container from which to get a geometry from.
• i: index of the geometry to fetch, between 0 and ngeom() - 1.

getgeomtype(geom::AbstractGeometry)

Fetch geometry type code

getm(geom::AbstractGeometry, i::Integer)

Fetch the m coordinate of a point from a geometry, at index i.

getnonlineargeomflag()

Get flag to enable/disable returning non-linear geometries in the C API.

getpoint(geom::AbstractGeometry, i::Integer)

Fetch a point in line string or a point geometry, at index i.

Parameters

• i: the vertex to fetch, from 0 to ngeom()-1, zero for a point.

getspatialref(geom::AbstractGeometry)

Returns a clone of the spatial reference system for the geometry.

(The original SRS may be shared with many objects, and should not be modified.)

getx(geom::AbstractGeometry, i::Integer)

Fetch the x coordinate of a point from a geometry, at index i.

gety(geom::AbstractGeometry, i::Integer)

Fetch the y coordinate of a point from a geometry, at index i.

getz(geom::AbstractGeometry, i::Integer)

Fetch the z coordinate of a point from a geometry, at index i.

haspreparedgeomsupport()

Check whether the current GDAL instance has support for prepared geometries.

hascurvegeom(geom::AbstractGeometry, nonlinear::Bool)

Returns if this geometry is or has curve geometry.

Parameters

• geom: the geometry to operate on.
• nonlinear: set it to true to check if the geometry is or contains a CIRCULARSTRING.

intersection(g1::AbstractGeometry, g2::AbstractGeometry)

Returns a new geometry representing the intersection of the geometries, or NULL if there is no intersection or an error occurs.

Generates a new geometry which is the region of intersection of the two geometries operated on. The OGRGIntersects() function can be used to test if two geometries intersect.

intersects(g1::AbstractGeometry, g2::AbstractGeometry)

Returns whether the geometries intersect

Determines whether two geometries intersect. If GEOS is enabled, then this is done in rigorous fashion otherwise true is returned if the envelopes (bounding boxes) of the two geometries overlap.

is3d(geom::AbstractGeometry)

Returns true if the geometry has a z coordinate, otherwise false.

isempty(geom::AbstractGeometry)

Returns true if the geometry has no points, otherwise false.

ismeasured(geom::AbstractGeometry)

Returns true if the geometry has a m coordinate, otherwise false.

isring(geom::AbstractGeometry)

Returns true if the geometry is a ring, otherwise false.

issimple(geom::AbstractGeometry)

Returns true if the geometry is simple, otherwise false.

isvalid(geom::AbstractGeometry)

Returns true if the geometry is valid, otherwise false.

ngeom(geom::AbstractGeometry)

The number of elements in a geometry or number of geometries in container.

This corresponds to

• OGR_G_GetPointCount for wkbPoint[25D] or wkbLineString[25D],
• OGR_G_GetGeometryCount for geometries of type wkbPolygon[25D], wkbMultiPoint[25D], wkbMultiLineString[25D], wkbMultiPolygon[25D] or wkbGeometryCollection[25D], and
• 0 for other geometry types.

overlaps(g1::AbstractGeometry, g2::AbstractGeometry)

Returns true if the geometries overlap.

pointalongline(geom::AbstractGeometry, distance::Real)

Fetch point at given distance along curve.

Parameters

• geom: curve geometry.
• distance: distance along the curve at which to sample position. This distance should be between zero and geomlength() for this curve.

Returns

a point or NULL.

pointonsurface(geom::AbstractGeometry)

Returns a point guaranteed to lie on the surface.

This method relates to the SFCOM ISurface::get_PointOnSurface() method however the current implementation based on GEOS can operate on other geometry types than the types that are supported by SQL/MM-Part 3 : surfaces (polygons) and multisurfaces (multipolygons).

polygonfromedges(lines::AbstractGeometry, tol::Real; besteffort = false,
    autoclose = false)

Build a ring from a bunch of arcs.

Parameters

• lines: handle to an OGRGeometryCollection (or OGRMultiLineString) containing the line string geometries to be built into rings.
• tol: whether two arcs are considered close enough to be joined.

Keyword Arguments

• besteffort: (defaults to false) not yet implemented???.
• autoclose: indicates if the ring should be close when first and last points of the ring are the same. (defaults to false)

polygonize(geom::AbstractGeometry)

Polygonizes a set of sparse edges.

A new geometry object is created and returned containing a collection of reassembled Polygons: NULL will be returned if the input collection doesn't correspond to a MultiLinestring, or when reassembling Edges into Polygons is impossible due to topological inconsistencies.

preparegeom(geom::AbstractGeometry)

Create an prepared geometry of a geometry. This can speed up operations which interact with the geometry multiple times, by storing caches of calculated geometry information.

removeallgeoms!(geom::AbstractGeometry, todelete::Bool = true)

Remove all geometries from an exiting geometry container.

Parameters

• geom: the existing geometry to delete from.
• todelete: if true the geometry will be destroyed, otherwise it will not. The default is true as the existing geometry is considered to own the geometries in it.

removegeom!(geom::AbstractGeometry, i::Integer, todelete::Bool = true)

Remove a geometry from an exiting geometry container.

Parameters

• geom: the existing geometry to delete from.
• i: the index of the geometry to delete. A value of -1 is a special flag meaning that all geometries should be removed.
• todelete: if true the geometry will be destroyed, otherwise it will not. The default is true as the existing geometry is considered to own the geometries in it.

segmentize!(geom::AbstractGeometry, maxlength::Real)

Modify the geometry such it has no segment longer than the given distance.

Interpolated points will have Z and M values (if needed) set to 0. Distance computation is performed in 2d only

Parameters

• geom: the geometry to segmentize
• maxlength: the maximum distance between 2 points after segmentization

setcoorddim!(geom::AbstractGeometry, dim::Integer)

Set the coordinate dimension.

This method sets the explicit coordinate dimension. Setting the coordinate dimension of a geometry to 2 should zero out any existing Z values. Setting the dimension of a geometry collection, a compound curve, a polygon, etc. will affect the children geometries. This will also remove the M dimension if present before this call.

setnonlineargeomflag!(flag::Bool)

Set flag to enable/disable returning non-linear geometries in the C API.

This flag has only an effect on the OGRFGetGeometryRef(), OGRFGetGeomFieldRef(), OGRLGetGeomType(), OGRGFldGetType() and OGRFDGetGeomType() C API methods. It is meant as making it simple for applications using the OGR C API not to have to deal with non-linear geometries, even if such geometries might be returned by drivers. In which case, they will be transformed into their closest linear geometry, by doing linear approximation, with OGRGForceTo().

Libraries should generally not use that method, since that could interfere with other libraries or applications.

Parameters

• flag: true if non-linear geometries might be returned (default value). false to ask for non-linear geometries to be approximated as linear geometries.

Returns

a point or NULL.

setpoint!(geom::AbstractGeometry, i::Integer, x, y)
setpoint!(geom::AbstractGeometry, i::Integer, x, y, z)

Set the location of a vertex in a point or linestring geometry.

Parameters

• geom: handle to the geometry to add a vertex to.
• i: the index of the vertex to assign (zero based) or zero for a point.
• x: input X coordinate to assign.
• y: input Y coordinate to assign.
• z: input Z coordinate to assign (defaults to zero).

setpointcount!(geom::AbstractGeometry, n::Integer)

Set number of points in a geometry.

Parameters

• geom: the geometry.
• n: the new number of points for geometry.

simplify(geom::AbstractGeometry, tol::Real)

Compute a simplified geometry.

Parameters

• geom: the geometry.
• tol: the distance tolerance for the simplification.

simplifypreservetopology(geom::AbstractGeometry, tol::Real)

Simplify the geometry while preserving topology.

Parameters

• geom: the geometry.
• tol: the distance tolerance for the simplification.

symdifference(g1::AbstractGeometry, g2::AbstractGeometry)

Returns a new geometry representing the symmetric difference of the geometries or NULL if the difference is empty or an error occurs.

toGML(geom::AbstractGeometry)

Convert a geometry into GML format.

toISOWKB(geom::AbstractGeometry, order::OGRwkbByteOrder = wkbNDR)

Convert a geometry into SFSQL 1.2 / ISO SQL/MM Part 3 well known binary format.

Parameters

• geom: handle on the geometry to convert to a well know binary data from.
• order: One of wkbXDR or [wkbNDR] indicating MSB or LSB byte order resp.

toISOWKT(geom::AbstractGeometry)

Convert a geometry into SFSQL 1.2 / ISO SQL/MM Part 3 well known text format.

toJSON(geom::AbstractGeometry; kwargs...)

Convert a geometry into GeoJSON format.

• The following options are supported :
• COORDINATE_PRECISION=number: maximum number of figures after decimal separator to write in coordinates.
• SIGNIFICANT_FIGURES=number: maximum number of significant figures.
• If COORDINATEPRECISION is defined, SIGNIFICANTFIGURES will be ignored if
• specified.
• When none are defined, the default is COORDINATE_PRECISION=15.

Parameters

• geom: handle to the geometry.

Returns

A GeoJSON fragment or NULL in case of error.

toKML(geom::AbstractGeometry, altitudemode = C_NULL)

Convert a geometry into KML format.

toWKB(geom::AbstractGeometry, order::OGRwkbByteOrder = wkbNDR)

Convert a geometry well known binary format.

Parameters

• geom: handle on the geometry to convert to a well know binary data from.
• order: One of wkbXDR or [wkbNDR] indicating MSB or LSB byte order resp.

toWKT(geom::AbstractGeometry)

Convert a geometry into well known text format.

touches(g1::AbstractGeometry, g2::AbstractGeometry)

Returns true if the geometries are touching.

transform!(geom::AbstractGeometry, coordtransform::CoordTransform)

Apply arbitrary coordinate transformation to geometry.

Parameters

• geom: handle on the geometry to apply the transform to.
• coordtransform: handle on the transformation to apply.

union(g1::AbstractGeometry, g2::AbstractGeometry)

Returns a new geometry representing the union of the geometries.

within(g1::AbstractGeometry, g2::AbstractGeometry)

Returns true if g1 is contained within g2.

wkbsize(geom::AbstractGeometry)

Returns size (in bytes) of related binary representation.

addpart!(stylemanager::StyleManager, styletool::StyleTool)

Add a part (style tool) to the current style.

Parameters

• stylemanager: handle to the style manager.
• styletool: the style tool defining the part to add.

Returns

true on success, false on error.

addstyle!(stylemanager::StyleManager, stylename, stylestring)

Add a style to the current style table.

Parameters

• stylemanager: handle to the style manager.
• stylename: the name of the style to add.
• stylestring: (optional) the style string to use, or (if not provided) to use the style stored in the manager.

Returns

true on success, false on error.

addstyle!(styletable::StyleTable, stylename, stylestring)

Add a new style in the table.

Parameters

• styletable: handle to the style table.
• name: the name the style to add.
• stylestring: the style string to add.

Returns

true on success, false on error

asdouble(styletool::StyleTool, id::Integer, nullflag = Ref{Cint}(0))

Get Style Tool parameter value as a double.

Parameters

• styletool: handle to the style tool.
• id: the parameter id from the enumeration corresponding to the type of this style tool (one of the OGRSTPenParam, OGRSTBrushParam, OGRSTSymbolParam or OGRSTLabelParam enumerations)
• nullflag: pointer to an integer that will be set to true or false to indicate whether the parameter value is NULL.

Returns

the parameter value as a double and sets nullflag.

asint(styletool::StyleTool, id::Integer, nullflag = Ref{Cint}(0))

Get Style Tool parameter value as an integer.

Parameters

• styletool: handle to the style tool.
• id: the parameter id from the enumeration corresponding to the type of this style tool (one of the OGRSTPenParam, OGRSTBrushParam, OGRSTSymbolParam or OGRSTLabelParam enumerations)
• nullflag: pointer to an integer that will be set to true or false to indicate whether the parameter value is NULL.

Returns

the parameter value as an integer and sets nullflag.

asstring(styletool::StyleTool, id::Integer)
asstring(styletool::StyleTool, id::Integer, nullflag::Ref{Cint})

Get Style Tool parameter value as a string.

Parameters

• styletool: handle to the style tool.
• id: the parameter id from the enumeration corresponding to the type of this style tool (one of the OGRSTPenParam, OGRSTBrushParam, OGRSTSymbolParam or OGRSTLabelParam enumerations)
• nullflag: pointer to an integer that will be set to true or false to indicate whether the parameter value is NULL.

Returns

the parameter value as a string and sets nullflag.

Destroy Style Manager.

Parameters

• stylemanager: handle to the style manager to destroy.

Destroy Style Table.

Parameters

• styletable: handle to the style table to destroy.

Destroy Style Tool.

Parameters

• styletool: handle to the style tool to destroy.

findstylestring(styletable::StyleTable, name::AbstractString)

Get a style string by name.

Parameters

• styletable: handle to the style table.
• name: the name of the style string to find.

Returns

the style string matching the name or NULL if not found or error.

getstylestring(styletool::StyleTool)

Get the style string for this Style Tool.

Parameters

• styletool: handle to the style tool.

Returns

the style string for this style tool or "" if the styletool is invalid.

gettype(styletool::StyleTool)

Determine type of Style Tool.

Parameters

• styletool: handle to the style tool.

Returns

the style tool type, one of OGRSTCPen (1), OGRSTCBrush (2), OGRSTCSymbol (3) or OGRSTCLabel (4). Returns OGRSTCNone (0) if the OGRStyleToolH is invalid.

getunit(styletool::StyleTool)

Get Style Tool units.

Parameters

• styletool: handle to the style tool.

Returns

the style tool units.

initialize!(stylemanager::StyleManager, stylestring = C_NULL)

Initialize style manager from the style string.

Parameters

• stylemanager: handle to the style manager.
• stylestring: the style string to use (can be NULL).

Returns

true on success, false on error.

laststyle(styletable::StyleTable)

Get the style name of the last style string fetched with OGRSTBLGetNextStyle.

Parameters

• styletable: handle to the style table.

Returns

the Name of the last style string or NULL on error.

loadstyletable!(styletable::StyleTable, filename::AbstractString)

Load a style table from a file.

Parameters

• styletable: handle to the style table.
• filename: the name of the file to load from.

Returns

true on success, false on error

nextstyle(styletable::StyleTable)

Get the next style string from the table.

Parameters

• styletable: handle to the style table.

Returns

the next style string or NULL on error.

npart(stylemanager::StyleManager)
npart(stylemanager::StyleManager, stylestring::AbstractString)

Get the number of parts in a style.

Parameters

• stylemanager: handle to the style manager.
• stylestring: (optional) the style string on which to operate. If NULL then the current style string stored in the style manager is used.

Returns

the number of parts (style tools) in the style.

resetreading!(styletable::StyleTable)

Reset the next style pointer to 0.

Parameters

• styletable: handle to the style table.

savestyletable(styletable::StyleTable, filename::AbstractString)

Save a style table to a file.

Parameters

• styletable: handle to the style table.
• filename: the name of the file to save to.

Returns

true on success, false on error

setparam!(styletool::StyleTool, id::Integer, value)

Set Style Tool parameter value.

Parameters

• styletool: handle to the style tool.
• id: the parameter id from the enumeration corresponding to the type of this style tool (one of the OGRSTPenParam, OGRSTBrushParam, OGRSTSymbolParam or OGRSTLabelParam enumerations)
• value: the new parameter value, can be an Integer, Float64, or AbstactString

setunit!(styletool::StyleTool, newunit::OGRSTUnitId, scale::Real)

Set Style Tool units.

Parameters

• styletool: handle to the style tool.
• newunit: the new unit.
• scale: ground to paper scale factor.

toRGBA(styletool::StyleTool, color::AbstractString)

Return the r,g,b,a components of a color encoded in #RRGGBB[AA] format.

Parameters

• styletool: handle to the style tool.
• pszColor: the color to parse

Returns

(R,G,B,A) tuple of Cints.

unsafe_createstylemanager(styletable = C_NULL)

OGRStyleMgr factory.

Parameters

• styletable: OGRStyleTable or NULL if not working with a style table.

Returns

an handle to the new style manager object.

unsafe_createstyletable()

OGRStyleTable factory.

Returns

an handle to the new style table object.

unsafe_createstyletool(classid::OGRSTClassId)

OGRStyleTool factory.

Parameters

• classid: subclass of style tool to create. One of OGRSTCPen (1), OGRSTCBrush (2), OGRSTCSymbol (3) or OGRSTCLabel (4).

Returns

an handle to the new style tool object or NULL if the creation failed.

unsafe_getpart(stylemanager::StyleManager, id::Integer,
    stylestring = C_NULL)

Fetch a part (style tool) from the current style.

Parameters

• stylemanager: handle to the style manager.
• id: the part number (0-based index).
• stylestring: (optional) the style string on which to operate. If not provided, then the current style string stored in the style manager is used.

Returns

OGRStyleToolH of the requested part (style tools) or NULL on error.

addfielddefn!(layer::AbstractFeatureLayer, name, etype::OGRFieldType;
    <keyword arguments>)

Create a new field on a layer.

This function should not be called while there are feature objects in existence that were obtained or created with the previous layer definition.

Not all drivers support this function. You can query a layer to check if it supports it with the OLCCreateField capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existing features of the backing file/database should be updated accordingly.

Drivers may or may not support not-null constraints. If they support creating fields with not-null constraints, this is generally before creating any feature to the layer.

Parameters

• layer: the layer to write the field definition.
• name: name of the field definition to write to disk.
• etype: type of the field definition to write to disk.

Keyword arguments

• nwidth: the preferred formatting width. 0 (default) indicates undefined.
• nprecision: number of decimals for formatting. 0 (default) for undefined.
• justify: the formatting justification ([OJUndefined], OJLeft or OJRight)
• approx: If true (default false), the field may be created in a slightly different form depending on the limitations of the format driver.

writegeomdefn!(layer::AbstractFeatureLayer, name, etype::OGRwkbGeometryType,
    approx=false)

Write a new geometry field on a layer.

This function should not be called while there are feature objects in existence that were obtained or created with the previous layer definition.

Not all drivers support this function. You can query a layer to check if it supports it with the OLCCreateField capability. Some drivers may only support this method while there are still no features in the layer. When it is supported, the existing features of the backing file/database should be updated accordingly.

Drivers may or may not support not-null constraints. If they support creating fields with not-null constraints, this is generally before creating any feature to the layer.

Parameters

• layer: the layer to write the field definition.
• name: name of the field definition to write to disk.
• etype: type of the geometry field defintion to write to disk.

Keyword arguments

• approx: If true (default false), the geometry field may be created in a slightly different form depending on the limitations of the driver.

RasterDataset(dataset::AbstractDataset)

This data structure is returned by the ArchGDAL.readraster function and is a wrapper for a GDAL dataset. This wrapper is to signal the user that the dataset should be treated as a 3D AbstractArray where the first two dimensions correspond to longitude and latitude and the third dimension corresponds to different raster bands.

As it is a wrapper around a GDAL Dataset, it supports the usual raster methods for a GDAL Dataset such as getgeotransform, nraster, getband, getproj, width, and height. As it is also a subtype of AbstractDiskArray{T,3}, it supports the following additional methods: readblock!, writeblock!, eachchunk, haschunks, etc. This satisfies the DiskArray interface, allowing us to be able to index into it like we would an array.

Constructing a RasterDataset will error if the raster bands do not have all the same size and a common element data type.

_common_size(ds::AbstractDataset)

Determines the size of the raster bands in a dataset and errors if the sizes are not unique.

readraster(s::String; kwargs...)

Opens a GDAL raster dataset. The difference to ArchGDAL.read is that this function returns a RasterDataset, which is a subtype of AbstractDiskArray{T,3}, so that users can operate on the array using direct indexing.

Destroys a color table.

getcolorentryasrgb(ct::ColorTable, i::Integer)

Fetch a table entry in RGB format.

In theory this method should support translation of color palettes in non-RGB color spaces into RGB on the fly, but currently it only works on RGB color tables.

Parameters

• i entry offset from zero to GetColorEntryCount()-1.

Returns

true on success, or false if the conversion isn't supported.

paletteinterp(ct::ColorTable)

Fetch palette interpretation.

Returns

palette interpretation enumeration value, usually GPI_RGB.

setcolorentry!(ct::ColorTable, i::Integer, entry::GDAL.GDALColorEntry)

Set entry in color table.

Note that the passed in color entry is copied, and no internal reference to it is maintained. Also, the passed in entry must match the color interpretation of the table to which it is being assigned.

The table is grown as needed to hold the supplied offset.

Parameters

• i entry offset from 0 to ncolorentry()-1.
• entry value to assign to table.

unsafe_clone(ct::ColorTable)

Make a copy of a color table.

unsafe_createcolortable(palette::GDALPaletteInterp)

Construct a new color table.

asdouble(rat::RasterAttrTable, row::Integer, col::Integer)

Fetch field value as a double.

The value of the requested column in the requested row is returned as a double. Non double fields will be converted to double with the possibility of data loss.

Parameters

• row row to fetch (zero based).
• col column to fetch (zero based).

asint(rat::RasterAttrTable, row::Integer, col::Integer)

Fetch field value as a integer.

The value of the requested column in the requested row is returned as an int. Non-integer fields will be converted to int with the possibility of data loss.

Parameters

• row row to fetch (zero based).
• col column to fetch (zero based).

asstring(rat::RasterAttrTable, row::Integer, col::Integer)

Fetch field value as a string.

The value of the requested column in the requested row is returned as a string. If the field is numeric, it is formatted as a string using default rules, so some precision may be lost.

Parameters

• row row to fetch (zero based).
• col column to fetch (zero based).

attributeio!(rat::RasterAttrTable, access::GDALRWFlag, col, startrow, nrows,
    data::Vector)

Read or Write a block of data to/from the Attribute Table.

Parameters

• access Either GF_Read or GF_Write
• col Column of the Attribute Table
• startrow Row to start reading/writing (zero based)
• nrows Number of rows to read or write
• data Vector of Float64, Int32 or AbstractString to read/write. Should be at least nrows long.

changesarewrittentofile(rat::RasterAttrTable)

Determine whether changes made to this RAT are reflected directly in the dataset

If this returns false then RasterBand.SetDefaultRAT() should be called. Otherwise this is unnecessary since changes to this object are reflected in the dataset.

columnname(rat::RasterAttrTable, i::Integer)

Fetch name of indicated column.

Parameters

• i the column index (zero based).

Returns

the column name or an empty string for invalid column numbers.

columntype(rat::RasterAttrTable, i::Integer)

Fetch column type.

Parameters

• col the column index (zero based).

Returns

column type or GFT_Integer if the column index is illegal.

columnusage(rat::RasterAttrTable, i::Integer)

Fetch column usage value.

createcolumn!(rat::RasterAttrTable, name, fieldtype::GDALRATFieldType,
    fieldusage::GDALRATFieldUsage)

Create new column.

If the table already has rows, all row values for the new column will be initialized to the default value ("", or zero). The new column is always created as the last column, can will be column (field) "GetColumnCount()-1" after CreateColumn() has completed successfully.

Destroys a RAT.

findcolumnindex(rat::RasterAttrTable, usage::GDALRATFieldUsage)

Returns the index of the first column of the requested usage type, or -1 if no match is found.

Parameters

• usage usage type to search for.

findrowindex(rat::RasterAttrTable, pxvalue::Real)

Get row for pixel value.

Given a raw pixel value, the raster attribute table is scanned to determine which row in the table applies to the pixel value. The row index is returned.

Parameters

• pxvalue the pixel value.

Returns

The row index or -1 if no row is appropriate.

getlinearbinning(rat::RasterAttrTable)

Get linear binning information.

Returns

• row0min the lower bound (pixel value) of the first category.
• binsize the width of each category (in pixel value units).

initializeRAT!(rat::RasterAttrTable, colortable::ColorTable)

Initialize from color table.

This method will setup a whole raster attribute table based on the contents of the passed color table. The Value (GFUMinMax), Red (GFURed), Green (GFUGreen), Blue (GFUBlue), and Alpha (GFU_Alpha) fields are created, and a row is set for each entry in the color table.

The raster attribute table must be empty before calling initializeRAT!().

The Value fields are set based on the implicit assumption with color tables that entry 0 applies to pixel value 0, 1 to 1, etc.

ncolumn(rat::RasterAttrTable)

Fetch table column count.

nrow(rat::RasterAttrTable)

Fetch row count.

setlinearbinning!(rat::RasterAttrTable, row0min::Real, binsize::Real)

Set linear binning information.

For RATs with equal sized categories (in pixel value space) that are evenly spaced, this method may be used to associate the linear binning information with the table.

Parameters

• row0min the lower bound (pixel value) of the first category.
• binsize the width of each category (in pixel value units).

setrowcount!(rat::RasterAttrTable, n::Integer)

Set row count.

Resizes the table to include the indicated number of rows. Newly created rows will be initialized to their default values - "" for strings, and zero for numeric fields.

setvalue!(rat::RasterAttrTable, row, col, val)

Set field value from string.

The indicated field (column) on the indicated row is set from the passed value. The value will be automatically converted for other field types, with a possible loss of precision.

Parameters

• row row to fetch (zero based).
• col column to fetch (zero based).
• val the value to assign, can be an AbstractString, Integer or Float64.

toColorTable(rat::RasterAttrTable, n::Integer = -1)

Translate to a color table.

Parameters

• n The number of entries to produce (0 to n-1), or -1 to auto-determine the number of entries.

Returns

the generated color table or NULL on failure.

unsafe_clone(rat::RasterAttrTable)

Copy Raster Attribute Table.

Creates a new copy of an existing raster attribute table. The new copy becomes the responsibility of the caller to destroy. May fail (return NULL) if the attribute table is too large to clone: (nrow() * ncolumn() > RAT_MAX_ELEM_FOR_CLONE)

unsafe_createRAT(ct::ColorTable)

Construct table from an existing colortable.

unsafe_createRAT()

Construct empty table.

accessflag(band::AbstractRasterBand)

Return the access flag (e.g. OF_READONLY or OF_UPDATE) for this band.

blocksize(band::AbstractRasterBand)

Fetch the "natural" block size of this band.

GDAL contains a concept of the natural block size of rasters so that applications can organized data access efficiently for some file formats. The natural block size is the block size that is most efficient for accessing the format. For many formats this is simple a whole scanline in which case *pnXSize is set to GetXSize(), and *pnYSize is set to 1.

However, for tiled images this will typically be the tile size.

Note that the X and Y block sizes don't have to divide the image size evenly, meaning that right and bottom edge blocks may be incomplete. See ReadBlock() for an example of code dealing with these issues.

copywholeraster!( source::AbstractRasterBand, dest::AbstractRasterBand;
    [options, [progressfunc]])

Copy all raster band raster data.

This function copies the complete raster contents of one band to another similarly configured band. The source and destination bands must have the same width and height. The bands do not have to have the same data type.

It implements efficient copying, in particular "chunking" the copy in substantial blocks.

Currently the only options value supported is : "COMPRESSED=YES" to force alignment on target dataset block sizes to achieve best compression. More options may be supported in the future.

Parameters

• source the source band
• dest the destination band
• options transfer hints in "StringList" Name=Value format.
• progressfunc a function(::Float64, ::String)::Bool to call to report progress

createmaskband!(band::AbstractRasterBand, nflags::Integer)

Adds a mask band to the current band.

The default implementation of the CreateMaskBand() method is implemented based on similar rules to the .ovr handling implemented using the GDALDefaultOverviews object. A TIFF file with the extension .msk will be created with the same basename as the original file, and it will have as many bands as the original image (or just one for GMF_PER_DATASET). The mask images will be deflate compressed tiled images with the same block size as the original image if possible.

If you got a mask band with a previous call to GetMaskBand(), it might be invalidated by CreateMaskBand(). So you have to call GetMaskBand() again.

See also: http://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask

fillraster!(band::AbstractRasterBand, realvalue::Real, imagvalue::Real = 0)

Fill this band with a constant value.

GDAL makes no guarantees about what values pixels in newly created files are set to, so this method can be used to clear a band to a specified "default" value. The fill value is passed in as a double but this will be converted to the underlying type before writing to the file. An optional second argument allows the imaginary component of a complex constant value to be specified.

Parameters

• realvalue: Real component of fill value
• imagvalue: Imaginary component of fill value, defaults to zero

getcategorynames(band::AbstractRasterBand)

Fetch the list of category names for this raster.

The return list is a "StringList" in the sense of the CPL functions. That is a NULL terminated array of strings. Raster values without associated names will have an empty string in the returned list. The first entry in the list is for raster values of zero, and so on.

getcolorinterp(band::AbstractRasterBand)

Color Interpretation value for band

getdataset(band::AbstractRasterBand)

Fetch the handle to its dataset handle, or NULL if this cannot be determined.

Note that some RasterBands are not considered to be a part of a dataset, such as overviews or other "freestanding" bands.

getdefaultRAT(band::AbstractRasterBand)

A RAT will be returned if there is a default one associated with the band, otherwise NULL is returned. The returned RAT is owned by the band and should not be deleted by the application.

getmaskband(band::IRasterBand)

Return the mask band associated with the band.

The RasterBand class includes a default implementation of GetMaskBand() that returns one of four default implementations:

• If a corresponding .msk file exists it will be used for the mask band.
• If the dataset has a NODATA_VALUES metadata item, an instance of the new

GDALNoDataValuesMaskBand class will be returned. GetMaskFlags() will return GMF_NODATA | GMF_PER_DATASET.

• If the band has a nodata value set, an instance of the new

GDALNodataMaskRasterBand class will be returned. GetMaskFlags() will return GMF_NODATA.

• If there is no nodata value, but the dataset has an alpha band that seems to

apply to this band (specific rules yet to be determined) and that is of type GDT_Byte then that alpha band will be returned, and the flags GMF_PER_DATASET and GMF_ALPHA will be returned in the flags.

• If neither of the above apply, an instance of the new

GDALAllValidRasterBand class will be returned that has 255 values for all pixels. The null flags will return GMF_ALL_VALID.

Note that the GetMaskBand() should always return a RasterBand mask, even if it is only an all 255 mask with the flags indicating GMF_ALL_VALID.

See also: http://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask

Returns

a valid mask band.

getnodatavalue(band::AbstractRasterBand)

Fetch the no data value for this band.

If there is no out of data value, nothing will be returned instead. The no data value for a band is generally a special marker value used to mark pixels that are not valid data. Such pixels should generally not be displayed, nor contribute to analysis operations.

Returns

the nodata value for this band or nothing.

getoffset(band::AbstractRasterBand)

Fetch the raster value offset.

This (in combination with GetScale()) is used to transform raw pixel values into the units returned by GetUnits(). For e.g. this might be used to store elevations in GUInt16 bands with a precision of 0.1, starting from -100.

Units value = (raw value * scale) + offset

For file formats that don't know this intrinsically, a value of 0 is returned.

getoverview(band::IRasterBand, i::Integer)

Fetch overview raster band object.

getscale(band::AbstractRasterBand)

Fetch the raster value scale.

This value (in combination with the GetOffset() value) is used to transform raw pixel values into the units returned by GetUnits(). For example this might be used to store elevations in GUInt16 bands with a precision of 0.1, and starting from -100.

Units value = (raw value * scale) + offset

For file formats that don't know this intrinsically a value of one is returned.

getunittype(band::AbstractRasterBand)

Return a name for the units of this raster's values. For instance, it might be "m" for an elevation model in meters, or "ft" for feet.

height(band::AbstractRasterBand)

Fetch the height in pixels of this band.

indexof(band::AbstractRasterBand)

Fetch the band number (1+) within its dataset, or 0 if unknown.

This method may return a value of 0 to indicate overviews, or free-standing RasterBand objects without a relationship to a dataset.

maskflaginfo(band::AbstractRasterBand)

Returns the flags as in maskflags(@ref) but unpacks the bit values into a named tuple with the following fields:

• all_valid
• per_dataset
• alpha
• nodata

Returns

A named tuple with unpacked mask flags

maskflags(band::AbstractRasterBand)

Return the status flags of the mask band associated with the band.

The GetMaskFlags() method returns an bitwise OR-ed set of status flags with the following available definitions that may be extended in the future:

• GMF_ALL_VALID (0x01): There are no invalid pixels, all mask values

will be 255. When used this will normally be the only flag set.

• GMF_PER_DATASET (0x02): The mask band is shared between all bands on

the dataset.

• GMF_ALPHA (0x04): The mask band is actually an alpha band and may

have values other than 0 and 255.

• GMF_NODATA (0x08): Indicates the mask is actually being generated

from nodata values. (mutually exclusive of GMF_ALPHA)

The RasterBand class includes a default implementation of GetMaskBand() that returns one of four default implementations:

• If a corresponding .msk file exists it will be used for the mask band.
• If the dataset has a NODATA_VALUES metadata item, an instance of the new

GDALNoDataValuesMaskBand class will be returned. GetMaskFlags() will return GMF_NODATA | GMF_PER_DATASET.

• If the band has a nodata value set, an instance of the new

GDALNodataMaskRasterBand class will be returned. GetMaskFlags() will return GMF_NODATA.

• If there is no nodata value, but the dataset has an alpha band that seems to

apply to this band (specific rules yet to be determined) and that is of type GDT_Byte then that alpha band will be returned, and the flags GMF_PER_DATASET and GMF_ALPHA will be returned in the flags.

• If neither of the above apply, an instance of the new GDALAllValidRasterBand

class will be returned that has 255 values for all pixels. The null flags will return GMF_ALL_VALID.

See also: http://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask

Returns

a valid mask band.

maximum(band::AbstractRasterBand)

Fetch the maximum value for this band.

minimum(band::AbstractRasterBand)

Fetch the minimum value for this band.

noverview(band::AbstractRasterBand)

Return the number of overview layers available, zero if none.

pixeltype(band::AbstractRasterBand)

Fetch the pixel data type for this band.

regenerateoverviews!(band::AbstractRasterBand,
    overviewbands::Vector{<:AbstractRasterBand}, resampling = "NEAREST")

Generate downsampled overviews.

This function will generate one or more overview images from a base image using the requested downsampling algorithm. Its primary use is for generating overviews via BuildOverviews(), but it can also be used to generate downsampled images in one file from another outside the overview architecture.

Parameters

• band the source (base level) band.
• overviewbands the list of downsampled bands to be generated.

Keyword Arguments

• resampling (optional) Resampling algorithm (eg. "AVERAGE"). default to "NEAREST".
• progressfunc (optional) a function(::Float64, ::String)::Bool to call to report progress

Additional Remarks

The output bands need to exist in advance.

This function will honour properly NODATA_VALUES tuples (special dataset metadata) so that only a given RGB triplet (in case of a RGB image) will be considered as the nodata value and not each value of the triplet independantly per band.

sampleoverview(band::IRasterBand, nsamples::Integer)

Fetch best overview satisfying nsamples number of samples.

Returns the most reduced overview of the given band that still satisfies the desired number of samples nsamples. This function can be used with zero as the number of desired samples to fetch the most reduced overview. The same band as was passed in will be returned if it has not overviews, or if none of the overviews have enough samples.

setcategorynames!(band::AbstractRasterBand, names::Vector{String})

Set the category names for this band.

setcolorinterp!(band::AbstractRasterBand, color::GDALColorInterp)

Set color interpretation of a band.

setcolortable!(band::AbstractRasterBand, colortable::ColorTable)

Set the raster color table.

The driver will make a copy of all desired data in the colortable. It remains owned by the caller after the call.

Parameters

• colortable color table to apply (where supported).

setdefaultRAT!(band::AbstractRasterBand, rat::RasterAttrTable)

Set default Raster Attribute Table.

Associates a default RAT with the band. If not implemented for the format a CPLE_NotSupported error will be issued. If successful a copy of the RAT is made, the original remains owned by the caller.

setnodatavalue!(band::AbstractRasterBand, value::Real)

Set the no data value for this band.

setoffset!(band::AbstractRasterBand, value::Real)

Set scaling offset.

setscale!(band::AbstractRasterBand, ratio::Real)

Set scaling ratio.

setunittype!(band::AbstractRasterBand, unitstring::AbstractString)

Set unit type of band to unittype.

Values should be one of "" (the default indicating it is unknown), "m" indicating meters, or "ft" indicating feet, though other nonstandard values are allowed.

unsafe_getcolortable(band::AbstractRasterBand)

Returns a clone of the color table associated with the band.

(If there is no associated color table, the original result is NULL. The original color table remains owned by the RasterBand, and can't be depended on for long, nor should it ever be modified by the caller.)

width(band::AbstractRasterBand)

Fetch the width in pixels of this band.

rasterio!(dataset::AbstractDataset, buffer::AbstractArray{<:Any, 3},
    bands; <keyword arguments>)
rasterio!(dataset::AbstractDataset, buffer::AbstractArray{<:Any, 3}, bands, rows,
    cols; <keyword arguments>)
rasterio!(rasterband::AbstractRasterBand, buffer::AbstractMatrix{<:Any};
    <keyword arguments>)
rasterio!(rasterband::AbstractRasterBand, buffer::AbstractMatrix{<:Any}, rows,
    cols; <keyword arguments>)

Read/write a region of image data from multiple bands.

This method allows reading a region of one or more RasterBands from this dataset into a buffer, or writing data from a buffer into a region of the RasterBands. It automatically takes care of data type translation if the element type (<:Any) of the buffer is different than that of the RasterBand. The method also takes care of image decimation / replication if the buffer size (xsz × ysz) is different than the size of the region being accessed (xsize × ysize).

The pxspace, linespace and bandspace parameters allow reading into or writing from various organization of buffers.

For highest performance full resolution data access, read and write on "block boundaries" as returned by blocksize(), or use the readblock!() and writeblock!() methods.

Parameters

• rows A continuous range of rows expressed as a UnitRange{<:Integer}, such as 2:9.
• cols A continuous range of columns expressed as a UnitRange{<:Integer}, such as 2:9.
• access Either GF_Read to read a region of data, or GF_Write to write a region of data.
• xoffset The pixel offset to the top left corner of the region to be accessed. It will be 0 (default) to start from the left.
• yoffset The line offset to the top left corner of the region to be accessed. It will be 0 (default) to start from the top.
• xsize The width of the region of the band to be accessed in pixels.
• ysize The height of the region of the band to be accessed in lines.
• buffer The buffer into which the data should be read, or from which it should be written. It must contain ≥ xsz * ysz * <# of bands> words of type eltype(buffer). It is organized in left to right, top to bottom pixel order. Spacing is controlled by the pxspace, and linespace parameters
• xsz The width of the buffer into which the desired region is to be read, or from which it is to be written.
• ysz The height of the buffer into which the desired region is to be read, or from which it is to be written.
• bands The list of bands (1-based) to be read/written.
• pxspace The byte offset from the start of a pixel value in the buffer to the start of the next pixel value within a scanline. By default (i.e., 0) the size of eltype(buffer) will be used.
• linespace The byte offset from the start of one scanline in pBuffer to the start of the next. By default (i.e., 0) the value of sizeof(eltype(buffer)) * xsz will be used.
• bandspace The byte offset from the start of one bands data to the start of the next. By default (0), it will be linespace * ysz implying band sequential organization of the buffer.

Returns

CE_Failure if the access fails, otherwise CE_None.

readblock!(rb::AbstractRasterBand, xoffset::Integer, yoffset::Integer,
    buffer)

Read a block of image data efficiently.

This method accesses a "natural" block from the raster band without resampling, or data type conversion. For a more generalized, but potentially less efficient access use RasterIO().

Parameters

• xoffset the horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.
• yoffset the vertical block offset, with zero indicating the top most block, 1 the next block and so forth.
• buffer the buffer into which the data will be read. The buffer must be large enough to hold GetBlockXSize()*GetBlockYSize() words of type GetRasterDataType().

writeblock!(rb::AbstractRasterBand, xoffset::Integer, yoffset::Integer,
    buffer)

Write a block of image data efficiently.

This method accesses a "natural" block from the raster band without resampling, or data type conversion. For a more generalized, but potentially less efficient access use RasterIO().

Parameters

• xoffset the horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.
• yoffset the vertical block offset, with zero indicating the left most block, 1 the next block and so forth.
• buffer the buffer from which the data will be written. The buffer must be large enough to hold GetBlockXSize()*GetBlockYSize() words of type GetRasterDataType().

clone(spref::AbstractSpatialRef)

Makes a clone of the Spatial Reference System. May return NULL.

crs2transform(f::Function, sourcecrs::GeoFormat, targetcrs::GeoFormat;
    kwargs...)

Run the function f on a coord transform generated from the source and target crs definitions. These can be any GeoFormat (from GeoFormatTypes) that holds a coordinate reference system.

kwargs are passed through to importCRS.

OGRCoordinateTransformation destructor.

getattrvalue(spref::AbstractSpatialRef, name::AbstractString, i::Integer)

Fetch indicated attribute of named node.

This method uses GetAttrNode() to find the named node, and then extracts the value of the indicated child. Thus a call to getattrvalue(spref,"UNIT",1) would return the second child of the UNIT node, which is normally the length of the linear unit in meters.

Parameters name the tree node to look for (case insensitive). i the child of the node to fetch (zero based).

Returns the requested value, or nothing if it fails for any reason.

importCRS!(spref::AbstractSpatialRef, x::GeoFormatTypes.GeoFormat)

Import a coordinate reference system from a GeoFormat into the spatial ref.

importCRS(x::GeoFormatTypes.GeoFormat; [order=:compliant])

Import a coordinate reference system from a GeoFormat into GDAL, returning an ArchGDAL.AbstractSpatialRef.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant (the default) will use axis ordering compliant with the relevant CRS authority.

importEPSG!(spref::AbstractSpatialRef, code::Integer)

Initialize SRS based on EPSG GCS or PCS code.

This method will initialize the spatial reference based on the passed in EPSG GCS or PCS code. It is relatively expensive, and generally involves quite a bit of text file scanning. Reasonable efforts should be made to avoid calling it many times for the same coordinate system.

Additional Remarks

This method is similar to importFromEPSGA() except that EPSG preferred axis ordering will not be applied for geographic coordinate systems. EPSG normally defines geographic coordinate systems to use lat/long contrary to typical GIS use). Since OGR 1.10.0, EPSG preferred axis ordering will also not be applied for projected coordinate systems that use northing/easting order.

The coordinate system definitions are normally read from the EPSG derived support files such as pcs.csv, gcs.csv, pcs.override.csv, gcs.override.csv and falling back to search for a PROJ.4 epsg init file or a definition in epsg.wkt.

These support files are normally searched for in /usr/local/share/gdal or in the directory identified by the GDAL_DATA configuration option. See CPLFindFile() for details.

importEPSG(code::Integer; [order=:compliant])

Construct a Spatial Reference System from its EPSG GCS or PCS code.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant, will use axis ordering compliant with the relevant CRS authority.

importEPSGA!(spref::AbstractSpatialRef, code::Integer)

Initialize SRS based on EPSG CRS code.

This method is similar to importFromEPSG() except that EPSG preferred axis ordering will be applied for geographic and projected coordinate systems. EPSG normally defines geographic coordinate systems to use lat/long, and also there are also a few projected coordinate systems that use northing/easting order contrary to typical GIS use). See importFromEPSG() for more details on operation of this method.

importEPSGA(code::Integer; [order=:compliant])

Construct a Spatial Reference System from its EPSG CRS code.

This method is similar to importFromEPSG() except that EPSG preferred axis ordering will be applied for geographic and projected coordinate systems. EPSG normally defines geographic coordinate systems to use lat/long, and also there are also a few projected coordinate systems that use northing/easting order contrary to typical GIS use). See importFromEPSG() for more details on operation of this method.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant, will use axis ordering compliant with the relevant CRS authority.

importESRI!(spref::AbstractSpatialRef, esristr::AbstractString)

Import coordinate system from ESRI .prj format(s).

This function will read the text loaded from an ESRI .prj file, and translate it into an OGRSpatialReference definition. This should support many (but by no means all) old style (Arc/Info 7.x) .prj files, as well as the newer pseudo-OGC WKT .prj files. Note that new style .prj files are in OGC WKT format, but require some manipulation to correct datum names, and units on some projection parameters. This is addressed within importFromESRI() by an automatic call to morphFromESRI().

Currently only GEOGRAPHIC, UTM, STATEPLANE, GREATBRITIAN_GRID, ALBERS, EQUIDISTANT_CONIC, TRANSVERSE (mercator), POLAR, MERCATOR and POLYCONIC projections are supported from old style files.

At this time there is no equivalent exportToESRI() method. Writing old style .prj files is not supported by OGRSpatialReference. However the morphToESRI() and exportToWkt() methods can be used to generate output suitable to write to new style (Arc 8) .prj files.

importESRI(esristr::AbstractString; kwargs...)

Create SRS from its ESRI .prj format(s).

Passing the keyword argument order=:compliant or order=:trad will set the mapping strategy to return compliant axis order or traditional lon/lat order.

importPROJ4!(spref::AbstractSpatialRef, projstr::AbstractString)

Import PROJ.4 coordinate string.

The OGRSpatialReference is initialized from the passed PROJ.4 style coordinate system string. In addition to many +proj formulations which have OGC equivalents, it is also possible to import "+init=epsg:n" style definitions. These are passed to importFromEPSG(). Other init strings (such as the state plane zones) are not currently supported.

Example: pszProj4 = "+proj=utm +zone=11 +datum=WGS84"

Some parameters, such as grids, recognized by PROJ.4 may not be well understood and translated into the OGRSpatialReference model. It is possible to add the +wktext parameter which is a special keyword that OGR recognized as meaning "embed the entire PROJ.4 string in the WKT and use it literally when converting back to PROJ.4 format".

For example: "+proj=nzmg +lat_0=-41 +lon_0=173 +x_0=2510000 +y_0=6023150 +ellps=intl +units=m +nadgrids=nzgd2kgrid0005.gsb +wktext"

importPROJ4(projstr::AbstractString; [order=:compliant])

Create SRS from its PROJ.4 string.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant, will use axis ordering compliant with the relevant CRS authority.

importURL!(spref::AbstractSpatialRef, url::AbstractString)

Set spatial reference from a URL.

This method will download the spatial reference at a given URL and feed it into SetFromUserInput for you.

importURL(url::AbstractString; [order=:compliant])

Construct SRS from a URL.

This method will download the spatial reference at a given URL and feed it into SetFromUserInput for you.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant, will use axis ordering compliant with the relevant CRS authority.

importUserInput(code::AbstractString; [order=:compliant])

Construct a Spatial Reference System from a user provided code that is parsed by GDAL. This is useful when the input code is in an unknown format or a shortcut not covered by more constrained methods. An example is the code "EPSG:4326+3855", the shortest way to describe a combination of a horizontal and vertical crs.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant, will use axis ordering compliant with the relevant CRS authority.

importWKT!(spref::AbstractSpatialRef, wktstr::AbstractString)

Import from WKT string.

This method will wipe the existing SRS definition, and reassign it based on the contents of the passed WKT string. Only as much of the input string as needed to construct this SRS is consumed from the input string, and the input string pointer is then updated to point to the remaining (unused) input.

importWKT(wktstr::AbstractString; [order=:compliant])

Create SRS from its WKT string.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant, will use axis ordering compliant with the relevant CRS authority.

importXML!(spref::AbstractSpatialRef, xmlstr::AbstractString)

Import SRS from XML format (GML only currently).

importXML(xmlstr::AbstractString; [order=:compliant])

Construct SRS from XML format (GML only currently).

Passing the keyword argument order=:compliant or order=:trad will set the mapping strategy to return compliant axis order or traditional lon/lat order.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant, will use axis ordering compliant with the relevant CRS authority.

morphfromESRI!(spref::AbstractSpatialRef)

Convert in place from ESRI WKT format.

The value notes of this coordinate system are modified in various manners to adhere more closely to the WKT standard. This mostly involves translating a variety of ESRI names for projections, arguments and datums to "standard" names, as defined by Adam Gawne-Cain's reference translation of EPSG to WKT for the CT specification.

Missing parameters in TOWGS84, DATUM or GEOGCS nodes can be added to the WKT, comparing existing WKT parameters to GDAL's databases. Note that this optional procedure is very conservative and should not introduce false information into the WKT definition (although caution should be advised when activating it). Needs the Configuration Option GDAL_FIX_ESRI_WKT be set to one of the following (TOWGS84 recommended for proper datum shift calculations)

GDAL_FIX_ESRI_WKT values:

• TOWGS84 Adds missing TOWGS84 parameters (necessary for datum transformations), based on named datum and spheroid values.
• DATUM Adds EPSG AUTHORITY nodes and sets SPHEROID name to OGR spec.
• GEOGCS Adds EPSG AUTHORITY nodes and sets GEOGCS, DATUM and SPHEROID names to OGR spec. Effectively replaces GEOGCS node with the result of importFromEPSG(n), using EPSG code n corresponding to the existing GEOGCS. Does not impact PROJCS values.

morphtoESRI!(spref::AbstractSpatialRef)

Convert in place to ESRI WKT format.

The value nodes of this coordinate system are modified in various manners more closely map onto the ESRI concept of WKT format. This includes renaming a variety of projections and arguments, and stripping out nodes note recognised by ESRI (like AUTHORITY and AXIS).

newspatialref(wkt::AbstractString = ""; order=:compliant)

Construct a Spatial Reference System from its WKT.

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant, will use axis ordering compliant with the relevant CRS authority.

reproject(points, sourceproj::GeoFormat, destproj::GeoFormat;
    [order=:compliant])

Reproject points to a different coordinate reference system and/or format.

Arguments

• coord: Vector of Geometry points
• sourcecrs: The current coordinate reference system, as a GeoFormat
• targetcrs: The coordinate reference system to transform to, using any CRS capable GeoFormat

Keyword Arguments

• order: Sets the axis mapping strategy. :trad will use traditional lon/lat axis ordering in any actions done with the crs. :compliant (the default) will use axis ordering compliant with the relevant CRS authority.

Example

julia> using ArchGDAL, GeoFormatTypes

julia> ArchGDAL.reproject(
    [[118, 34], [119, 35]],
    ProjString("+proj=longlat +datum=WGS84 +no_defs"),
    EPSG(2025)
)
2-element Array{Array{Float64,1},1}:
 [-2.60813482878655e6, 1.5770429674905164e7]
 [-2.663928675953517e6, 1.56208905951487e7]

setattrvalue!(spref::AbstractSpatialRef, path::AbstractString,
    value::AbstractString)

Set attribute value in spatial reference.

Missing intermediate nodes in the path will be created if not already in existence. If the attribute has no children one will be created and assigned the value otherwise the zeroth child will be assigned the value.

Parameters

• path: full path to attribute to be set. For instance "PROJCS|GEOGCS|UNIT".
• value: (optional) to be assigned to node, such as "meter". This may be left out if you just want to force creation of the intermediate path.

toEPSG(spref::AbstractSpatialRef)

Export EPSG code for this coordinate system if available.

toMICoordSys(spref::AbstractSpatialRef)

Export coordinate system in Mapinfo style CoordSys format.

toPROJ4(spref::AbstractSpatialRef)

Export coordinate system in PROJ.4 format.

toWKT(spref::AbstractSpatialRef, simplify::Bool)

Convert this SRS into a nicely formatted WKT string for display to a person.

Parameters

• spref: the SRS to be converted
• simplify: true if the AXIS, AUTHORITY and EXTENSION nodes should be stripped off.

toWKT(spref::AbstractSpatialRef)

Convert this SRS into WKT format.

toXML(spref::AbstractSpatialRef)

Export coordinate system in XML format.

Converts the loaded coordinate reference system into XML format to the extent possible. LOCALCS coordinate systems are not translatable. An empty string will be returned along with OGRERRNONE.

transform!(xvertices, yvertices, zvertices, obj::CoordTransform)

Transform points from source to destination space.

Parameters

• xvertices array of nCount X vertices, modified in place.
• yvertices array of nCount Y vertices, modified in place.
• zvertices array of nCount Z vertices, modified in place.

Returns

true on success, or false if some or all points fail to transform.

unsafe_createcoordtrans(source::AbstractSpatialRef,
    target::AbstractSpatialRef)

Create transformation object.

Parameters

• source: source spatial reference system.
• target: target spatial reference system.

Returns

NULL on failure or a ready to use transformation object.

applygeotransform(geotransform::Vector{Float64}, pixel::Float64,
    line::Float64)

Apply GeoTransform to x/y coordinate.

Applies the following computation, converting a (pixel,line) coordinate into a georeferenced (geo_x,geo_y) location.

    geo_x = geotransform[1] + pixel*geotransform[2] + line*geotransform[3]
    geo_y = geotransform[4] + pixel*geotransform[5] + line*geotransform[6]

Parameters

• geotransform Six coefficient GeoTransform to apply.
• pixel input pixel position.
• line input line position.

composegeotransform!(gt1::Vector{Float64}, gt2::Vector{Float64},
    gtout::Vector{Float64})

Compose two geotransforms.

The resulting geotransform is the equivalent to padfGT1 and then padfGT2 being applied to a point.

Parameters

• gt1 the first geotransform, six values.
• gt2 the second geotransform, six values.
• gtout the output geotransform, six values.

invgeotransform!(gt_in::Vector{Float64}, gt_out::Vector{Float64})

Invert Geotransform.

This function will invert a standard 3x2 set of GeoTransform coefficients. This converts the equation from being pixel to geo to being geo to pixel.

Parameters

• gt_in Input geotransform (six doubles - unaltered).
• gt_out Output geotransform (six doubles - updated).

Returns

gt_out

gdalinfo(dataset::AbstractDataset, options = String[])

List various information about a GDAL supported raster dataset.

Parameters

• dataset: The source dataset.
• options: List of options (potentially including filename and open options). The accepted options are the ones of the gdalinfo utility.

Returns

String corresponding to the information about the raster dataset.

unsafe_gdalbuildvrt(
    datasets::Vector{<:AbstractDataset},
    options = String[];
    dest = "/vsimem/tmp")

Build a VRT from a list of datasets.

Parameters

• datasets: The list of input datasets.
• options: List of options (potentially including filename and open options). The accepted options are the ones of the gdalbuildvrt utility.

Returns

The output dataset.

unsafe_gdaldem(
    dataset::AbstractDataset,
    processing::String,
    options = String[];
    dest = "/vsimem/tmp",
    colorfile)

Tools to analyze and visualize DEMs.

Parameters

• dataset: The source dataset.
• pszProcessing: the processing to apply (one of "hillshade", "slope", "aspect", "color-relief", "TRI", "TPI", "Roughness").
• options: List of options (potentially including filename and open options). The accepted options are the ones of the gdaldem utility.

Keyword Arguments

• colorfile: color file (mandatory for "color-relief" processing, should be empty otherwise).

Returns

The output dataset.

unsafe_gdalgrid(
    dataset::AbstractDataset,
    options = String[];
    dest = "/vsimem/tmp")

Create a raster from the scattered data.

Parameters

• dataset: The source dataset.
• options: List of options (potentially including filename and open options). The accepted options are the ones of the gdal_grid utility.

Returns

The output dataset.

unsafe_gdalnearblack(
    dataset::AbstractDataset,
    options = String[];
    dest = "/vsimem/tmp")

Convert nearly black/white borders to exact value.

Parameters

• dataset: The source dataset.
• options: List of options (potentially including filename and open options). The accepted options are the ones of the nearblack utility.

Returns

The output dataset.

unsafe_gdalrasterize(
    dataset::AbstractDataset,
    options = String[];
    dest = "/vsimem/tmp")

Burn vector geometries into a raster.

Parameters

• dataset: The source dataset.
• options: List of options (potentially including filename and open options). The accepted options are the ones of the gdal_rasterize utility.

Returns

The output dataset.

unsafe_gdaltranslate(
    dataset::AbstractDataset,
    options = String[];
    dest = "/vsimem/tmp")

Convert raster data between different formats.

Parameters

• dataset: The dataset to be translated.
• options: List of options (potentially including filename and open options). The accepted options are the ones of the gdal_translate utility.

Returns

The output dataset.

unsafe_gdalvectortranslate(
    datasets::Vector{<:AbstractDataset},
    options = String[];
    dest = "/vsimem/tmp")

Convert vector data between file formats.

Parameters

• datasets: The list of input datasets (only 1 supported currently).
• options: List of options (potentially including filename and open options). The accepted options are the ones of the ogr2ogr utility.

Returns

The output dataset.

unsafe_gdalwarp(
    datasets::Vector{<:AbstractDataset},
    options = String[];
    dest = "/vsimem/tmp")

Image reprojection and warping function.

Parameters

• datasets: The list of input datasets.
• options: List of options (potentially including filename and open options). The accepted options are the ones of the gdalwarp utility.

Returns

The output dataset.

copyfiles(drv::Driver, new::AbstractString, old::AbstractString)
copyfiles(drvname::AbstractString, new::AbstractString, old::AbstractString)

Copy all the files associated with a dataset.

deregister(drv::Driver)

Deregister the passed driver.

extensiondriver(filename::AbstractString)

Returns a driver shortname that matches the filename extension.

So extensiondriver("/my/file.tif") == "GTiff".

extensions()

Returns a Dict{String,String} of all of the file extensions that can be read by GDAL, with their respective drivers' shortnames.

getdriver(name::AbstractString)

Fetch a driver based on the short name (such as GTiff).

getdriver(i::Integer)

Fetch driver by index.

identifydriver(filename::AbstractString)

Identify the driver that can open a raster file.

This function will try to identify the driver that can open the passed filename by invoking the Identify method of each registered Driver in turn. The first driver that successful identifies the file name will be returned. If all drivers fail then NULL is returned.

listdrivers()

Returns a listing of all registered drivers.

longname(drv::Driver)

Return the long name of a driver (e.g. GeoTIFF), or empty string.

ndriver()

Fetch the number of registered drivers.

options(drv::Driver)

Return the list of creation options of the driver [an XML string].