Реализация GeoInterface

GeoInterface требует определения шести функций для пользовательского геометрического объекта. Помимо этого, может быть полезно также реализовать некоторые необязательные методы, если они применимы или выполняются быстрее, чем Fallbacks.

Если ваш пакет поддерживает геопространственные операции с геометрическими объектами, например пересечения, также реализуйте эти интерфейсы там, где применимо.

И последнее, но не менее важное: мы также предоставляем интерфейс для признаков — геометрических объектов со свойствами, — если это применимо.

Требуется для геометрического объекта

GeoInterface.isgeometry(geom::customgeom)::Bool = true
GeoInterface.geomtrait(geom::customgeom)::DataType = XTrait() # <: AbstractGeometryTrait
# для PointTraits
GeoInterface.ncoord(geomtrait(geom), geom::customgeom)::Integer
GeoInterface.getcoord(geomtrait(geom), geom::customgeom, i)::Real
# не для PointTraits
GeoInterface.ngeom(geomtrait(geom), geom::customgeom)::Integer
GeoInterface.getgeom(geomtrait(geom), geom::customgeom, i)

Здесь getgeom и getcoord могут также быть итераторами (без i). Они возвращают новый геометрический объект с правильным типажом geomtrait. Это означает, что вызов getgeom для геометрического объекта, имеющего LineStringTrait, должен возвращать некий объект, реализующий PointTrait. Данную иерархию можно проверить программным путем с помощью subtrait. Дополнительные сведения о geomtrait см. в разделе Type hierarchy.

ngeom и getgeom — это псевдонимы для геометрических аналогов, так же как npoints и getpoint — для LineStringTrait.

Необязательно для геометрического объекта

Существуют также необязательные универсальные методы, которые могут помочь с нахождением геометрического объекта.

GeoInterface.crs(geomtrait(geom), geom::customgeom)::GeoFormatTypes.GeoFormat
GeoInterface.extent(geomtrait(geom), geom::customgeom)::Extents.Extent

В случае с областями Extents.extent(geom::customgeom) является резервным методом для GeoInterface.extent и может использоваться здесь для обеспечения более широкой совместимости. Если не определен ни тот, ни другой метод, GeoInterface.extent рассчитывает область на основе точек геометрического объекта.

Наконец, существует множество других необязательных функций для каждого конкретного геометрического объекта. GeoInterface предоставляет резервные реализации на основе приведенных выше универсальных функций, но они не оптимизированы. Они подробно описаны в разделе Fallbacks.

Преобразование

Может быть полезным, когда кто угодно может преобразовать любой пользовательский геометрический объект в ваш тип геометрических объектов, если этот пользовательский тип также поддерживает GeoInterface. Для этого требуются приведенные ниже методы, реализация которых должна быть определена согласно методам GeoInterface, таким как ngeom, getgeom или просто вызовы coordinates.

# Этот метод будет вызываться при GeoInterface.convert(::Type{T}, geom)
# if geomtrait(geom) == LineStringTrait()
GeoInterface.convert(::Type{CustomLineString}, ::LineStringTrait, geom) = ...
GeoInterface.convert(::Type{CustomPolygon}, ::PolygonTrait, geom) = ...

Требуется для признаков и их коллекций

Признак — это геометрический объект со свойствами и, согласно современной терминологии, строка в таблице. В свою очередь, коллекция признаков — это их вектор, который часто бывает представлен в виде таблицы.

Для признака реализованы следующие элементы:

GeoInterface.isfeature(feat::customfeat)::Bool = true
GeoInterface.properties(feat::customfeat)
GeoInterface.geometry(feat::customfeat)

В свою очередь, для коллекции признаков реализованы следующие элементы:

GeoInterface.isfeaturecollection(::Type{customcollection}) = true
GeoInterface.getfeature(trait(::customcollection), ::customcollection, i)
GeoInterface.nfeature(trait(::customcollection), ::customcollection)
GeoInterface.geometrycolumns(::customcollection) = (:geometry,)  # может быть множественным!

geometrycolumns позволяет другим пакетам определять, какое поле в строке или какой столбец в таблице содержит геометрический объект или объекты.

Геопространственные операции

distance(geomtrait(a), geomtrait(b), a, b)
buffer(geomtrait(geom), geom, distance)
convexhull(geomtrait(geom), geom)

Геопространственные связи

Эти функции используются для описания связей между геометрическими объектами согласно определению в расширенной модели девяти пересечений (DE-9IM, Dimensionally Extended 9 Intersection Model).

equals(geomtrait(a), geomtrait(b), a, b)
disjoint(geomtrait(a), geomtrait(b), a, b)
intersects(geomtrait(a), geomtrait(b), a, b)
touches(geomtrait(a), geomtrait(b), a, b)
within(geomtrait(a), geomtrait(b), a, b)
contains(geomtrait(a), geomtrait(b), a, b)
overlaps(geomtrait(a), geomtrait(b), a, b)
crosses(geomtrait(a), geomtrait(b), a, b)
relate(geomtrait(a), geomtrait(b), a, b, relationmatrix)

Геопространственные множества

symdifference(geomtrait(a), geomtrait(b), a, b)
difference(geomtrait(a), geomtrait(b), a, b)
intersection(geomtrait(a), geomtrait(b), a, b)
union(geomtrait(a), geomtrait(b), a, b)

Тестирование интерфейса

GeoInterface предоставляет набор тестов для типа геометрических объектов. Он служит для проверки того, правильно ли реализованы и работают требуемые функции.

GeoInterface.testgeometry(geom)
GeoInterface.testfeature(geom)

Примеры

Все пользовательские геометрические объекты реализуют

GeoInterface.isgeometry(geom::customgeom)::Bool = true

geom::customgeom с типажами наподобие точки реализует

GeoInterface.geomtrait(geom::customgeom)::DataType = PointTrait()
GeoInterface.ncoord(::PointTrait, geom::customgeom)::Integer
GeoInterface.getcoord(::PointTrait, geom::customgeom, i)::Real

# Значения по умолчанию
GeoInterface.ngeom(::PointTrait, geom)::Integer = 0
GeoInterface.getgeom(::PointTrait, geom::customgeom, i) = nothing

geom::customgeom с типажами типа «Ломаная линия» реализует следующие методы:

GeoInterface.geomtrait(geom::customgeom)::DataType = LineStringTrait()
GeoInterface.ncoord(::LineStringTrait, geom::customgeom)::Integer

# Это псевдонимы для npoint и getpoint
GeoInterface.ngeom(::LineStringTrait, geom::customgeom)::Integer
GeoInterface.getgeom(::LineStringTrait, geom::customgeom, i) # точки geomtrait

# Необязательно
GeoInterface.isclosed(::LineStringTrait, geom::customgeom)::Bool
GeoInterface.issimple(::LineStringTrait, geom::customgeom)::Bool
GeoInterface.length(::LineStringTrait, geom::customgeom)::Real

geom::customgeom с типажами типа «Многоугольник» может реализовывать следующие методы:

GeoInterface.geomtrait(geom::customgeom)::DataType = PolygonTrait()
GeoInterface.ncoord(::PolygonTrait, geom::customgeom)::Integer

# Это псевдонимы для nring и getring
GeoInterface.ngeom(::PolygonTrait, geom::customgeom)::Integer
GeoInterface.getgeom(::PolygonTrait, geom::customgeom, i)::"LineStringTrait"

# Необязательно
GeoInterface.area(::PolygonTrait, geom::customgeom)::Real
GeoInterface.centroid(::PolygonTrait, geom::customgeom)::"PointTrait"
GeoInterface.pointonsurface(::PolygonTrait, geom::customgeom)::"PointTrait"
GeoInterface.boundary(::PolygonTrait, geom::customgeom)::"LineStringTrait"

geom::customgeom с типажами типа «Коллекция геометрических объектов» должен реализовывать следующие методы:

GeoInterface.geomtrait(geom::customgeom) = GeometryCollectionTrait()
GeoInterface.ncoord(::GeometryCollectionTrait, geom::customgeom)::Integer
GeoInterface.ngeom(::GeometryCollectionTrait, geom::customgeom)::Integer
GeoInterface.getgeom(::GeometryCollectionTrait,geom::customgeomm, i)::"GeometryTrait"

geom::customgeom с типажами типа «Мультиточка» должен реализовывать следующие методы:

GeoInterface.geomtrait(geom::customgeom) = MultiPointTrait()
GeoInterface.ncoord(::MultiPointTrait, geom::customgeom)::Integer

# Это псевдонимы для npoint и getpoint
GeoInterface.ngeom(::MultiPointTrait, geom::customgeom)::Integer
GeoInterface.getgeom(::MultiPointTrait, geom::customgeom, i)::"PointTrait"

geom::customgeom с типажами типа «Множественная ломаная линия» должен реализовывать следующие методы:

GeoInterface.geomtrait(geom::customgeom) = MultiLineStringTrait()
GeoInterface.ncoord(::MultiLineStringTrait, geom::customgeom)::Integer

# Это псевдонимы для nlinestring и getlinestring
GeoInterface.ngeom(::MultiLineStringTrait, geom::customgeom)::Integer
GeoInterface.getgeom(::MultiLineStringTrait,geom::customgeomm, i)::"LineStringTrait"

geom::customgeom с типажами типа «Мультимногоугольник» должен реализовывать следующие методы:

GeoInterface.geomtrait(geom::customgeom) = MultiPolygonTrait()
GeoInterface.ncoord(::MultiPolygonTrait, geom::customgeom)::Integer

# Это псевдонимы для npolygon и getpolygon
GeoInterface.ngeom(::MultiPolygonTrait, geom::customgeom)::Integer
GeoInterface.getgeom(::MultiPolygonTrait, geom::customgeom, i)::"PolygonTrait"