Package: geofiles
Geo-referenced Geometry File FormatsClassic geometry file formats as.obj,.off,.ply,.stlor.daedo not support the utilization of coordinate
systems besides from a local system, that can not be defined more precisely.
This feature is a major requirement for global applications, exchanging geo-referenced models e.g. in the context of
outdoor augmented reality applications.For this reason, the present project evaluates different possibilities of geo-referenced geometry files.Next to wide-spread standards asGeoVRML,X3D,CityJSON,GeoJSON,GMLorKML, we introduce four
geo-referenced extensions called.geoobj,.geooff,.geoplyand.geostl.
While, the named standard formats allow defining objects with multiple additional features, they also come with an
overhead according to the file size and an increased structural complexity with disadvantages to the read performance.
This overhead has to be minimized in many use cases and for this reason, some file formats are more suitable than
others. For completeness: the overhead can be further reduced using binary representations (like binaryobjorstl)
instead of textual ones, but since not all named formats support a binary mode, this is ignored in favor of
human-readability within this project and comparison.Geo-referenced ExtensionsIn this chapter you can find multiple extensions of classic geometry file formats.
All of these extensions support two major features:Defining the coordinate reference system (CRS) of the used vertices' coordinatesDefining an optional origin, which represents an absolute geo-referenced location and an implicit local Cartesian
coordinate frame for the models with a metric unit.Additional featuresSome proposed file formats support additional features such as:Geographical extentTransformation information (local per object or global for all vertices)Scaling factorTranslationRotationArbitrary meta information, with three fixed keys:Global per file such as:Translation unit (tu): any unit can be used. The present project only supports transformations with metres (
m)Rotation unit (ru: any unit can be used. The present project only supports transformations with degrees (
deg)Local per objectType (type): Type of the geo-object such as Building, Car, etc.GeoOBJThe.geoobjfile format extends the classic.objfile format with two line-types:Thecrsline type is used to define the coordinate system which is used within the fileTheorline type is used to define the optional origin of the verticesExample:crs urn:ogc:def:crs:EPSG::4326
or 48.3028533074941 14.2842865755919 279.307006835938AddonsNext to the geo-referencing features, the.geoobjextension also supports exchangingscale,rotation, as well
astranslationinformation using the following line prefixes:scfor adding scale information (sis already defined in.objfor smoothing groups)tfor translation informationrfor rotation angular informationExample:sc 1.5 2 5
t 10 -5 4
r 90 45 10Note that: if either a scaling, a translation or a rotation information is stated after an object definition with the
prefixo, the transformation is not interpreted globally, but locally for the specific object.Next to that it also supports the optional geographical extent meta information, containing the minimal (first three
values) and maximal (remaining three values) coordinate value expressions using the line prefixe.
This information can be useful for filtering geo-referenced files without any need to iterate all vertices.e -0.5 -0.5 -0.5 0.5 0.5 0.5GeoObj also supports meta information on file or on object level:mfor arbitrary object based meta information. Every meta entry contains a key as first element followed by one or
more values. Reserved keys:typefor object type informationmffor arbitrary file based meta information. Every meta entry contains a key as first element followed by one or
more values. Reserved keys:tufor defining the translation unit (default is metresm)rufor defining the rotation unit (default is degreesdeg)mf tu inch
mf ru rad
m axis_ordering x y zAnd finally GeoObj contains an extension to map object hierarchy:hcan be used before an object definition to change the hierarchy level. Like this an object tree can be createdUses the absolute index of the used hierarchy level (e.g. 2 represents a grandchildren-object root->children->
grandchildren)Use 0 for root levelParents are set to the last object of the specified levelcrs urn:ogc:def:crs:OGC:2:84
or 14.2842798233032 48.30284881591775 279.807006835938
v -0.5009357136907019 -0.4994462475020125 0.5
v -0.5009357136907019 -0.4994462475020125 -0.5
v -0.5009356247086404 0.4994462914230726 -0.5
g cubes
h 1
o child1
f 1 2 3
o child2
f 1 2 3
h 2
o child3
f 1 2 3GeoOFFThe.geoofffile format extends the classic.offfile.
For this we introduce a new file header usingGeoOFFinstead ofOFF.
The next non-empty line after this header is used to define the crs.Example:GeoOFF
urn:ogc:def:crs:EPSG::4326GeoOFF supports alternative headers, using different postfix values. The pattern of the header is based on theOFFheader definition and is defined like[ST][C][N][4][n]GeoOFF[o][e][s][t][r][f*][m*].
Like this GeoOFF is able to support:An absolute origin using theoheader postfix symbolExtent information using theeheader postfix symbolGlobal scaling information using thesheader postfix symbolGlobal translation information using thetheader postfix symbolGlobal rotation information using therheader postfix symbolArbitrary meta information using themheader postfix symbol for object information orffor file information (
which can occur multiple times)Defined as blank-separated list of key/value pairs likekey valueValues may be again a list of values that are separated with a whitespace likekey value1 value2 value3Reserved keys for file meta information (f):tufor defining the translation unit (default is metresm)rufor defining the rotation unit (default is degreesdeg)Reserved keys for object meta information (m):typefor object type informationExample:GeoOFFostrffm
urn:ogc:def:crs:OGC:2:84
14.2842798233032 48.30284881591775 279.807006835938
2 2 2
10 50 100
90 0 0
tu inch 
axis_ordering x y z
type genericobjectNote:The.offprefixes are currently not supported in the implementations.GeoPLYThe.geoplyfile format extends the classic.plyfile format with two header-line-types:Thecrsline type is used to define the coordinate system which is used within the fileTheoriginline type is used to define the optional origin of the verticesIn addition to those types it also changes the header fromplytogeoply.geoply
crs urn:ogc:def:crs:EPSG::4326
o 48.3028533074941 14.2842865755919 279.307006835938
...
end_headerAddonsNext to the geo-referencing features, the.geplyextension also supports exchanging globalscale,rotation, as
well astranslationinformation using the following line prefixes:scalefor adding scale informationtranslatefor translation informationrotatefor rotation angular informationmetafor arbitrary object based meta information. Every meta entry contains a key as first element followed by one
or more values. Reserved keys:typefor object type informationmetaffor arbitrary file based meta information. Every meta entry contains a key as first element followed by one
or more values. Reserved keys:tufor defining the translation unit (default is metresm)rufor defining the rotation unit (default is degreesdeg)Example:geoply
...
scale 1.5 2 5
translate 10 -5 4
rotate 90 45 10
metaf tu m
metaf ru deg
meta type genericobject
metaf axis_ordering x y z
...
end_headerNext to that it also supports the optional geographical extent meta information, containing the minimal (first three
values) and maximal (remaining three values) coordinate value expressions using theextentheader.
This information can be useful for filtering geo-referenced files without any need to iterate all vertices.geoply
...
extent -0.5 -0.5 -0.5 0.5 0.5 0.5
...
end_headerGeoSTLThe.geostlfile format extends the classic.stlfile using thegeosolidroot element.
Followed by thegeosolidprefix of the file format a meta-data tuple is introduced.
This tuple consists of the crs at the first position, followed by the optional origin coordinates and finally the
optional stl name.geosolid urn:ogc:def:crs:OGC:2:84 48.3028533074941 14.2842865755919 279.307006835938 fileNameFile format comparisonThe different named file formats come with a variable amount of features according to e.g. the supported CRS, an origin
for specifying a local coordinate system, the meta information of the minimal and maximal coordinates (geographical
extent), multi-object support or also differ in the representation of vertices. To take up the last point, some formats
use e.g. central vertex lists with referencing indices in the face definition and others re-define the vertices within
every indiviudal face. Next to that there are many different other features (e.g. smoothing groups in.obj,geographicalExtentinCityJSONor exact property definitions in.ply), which vary between the file formats and
lead to a diverse semantic expressiveness.FileGeo-ReferenceGeometryAppearanceSceneAnimationBase FormatEncodingCRSOrigin  SupportGeographical ExtentFacetedMultiple  ObjectsObject HierarchyVertex ReferencesColorMaterialImage textureLight sourcesViewport/CamerasTransformation InformationCityJSONJSONTextAny†✓✓✓Global✓✓✓Global Translation + ScalingGeoJSONJSONTextWGS84Via bounding box per object✓✓Via GeoJSON  CSS extensionGeoOBJOBJText*Any✓✓✓✓✓Global✓✓✓✓GeOFFOFFText*Any✓✓✓Global✓✓GeoPLYPLYText*Any✓✓✓Global✓✓✓✓GeoSTLSTLText*Any✓✓GMLXMLTextAny✓✓✓✓CityGMLGMLTextAny✓✓✓✓✓✓KMLXMLText or zipped (KMZ)WGS84✓✓✓GeoVRMLVRMLText or  BinaryWGS84 / EPSG4326 / UTM✓✓✓✓✓Local✓✓✓✓✓✓✓X3DXML,VRMLorJSONText or BinaryMultiple supported†✓✓✓✓Local✓✓✓✓✓✓✓ColladaXMLTextNone (but, due to XML structure easily addable)✓✓✓Local✓✓✓✓✓✓✓† Some file formats do not explicitly support an origin representation, but this feature can be approximated using translations.* Currently, only text support, but the base format would support binary, so a binary extension would be possible.Size comparisonThe following file comparison uses the minimal required sub-set of the specific file formats to represent geo-referenced
3D models. Additional features (e.g. GeographicalExtent inCityJSON) are not considered as far as possible, to avoid a
negative bias of the comparison. Next to that also the used reader does not support all features of the input files (
e.g..mtbmaterial information) and may use different line-ending symbols (Windows vs Linux). This would lead to the
situation that in some cases the input file size is greater than the geo-referenced version. For this reason we have
decided to do a normalization first by reading the input files with our custom reader and exporting the normalized
representation using our custom obj writer. The exported and normalized files are used as basis of comparison.You can find most of the used obj fileshere. The only
exceptions are the Amsterdam (find ithere) and Berlin (find
ithere) city model files. Also note that,
X3D is currently not explicitly supported by the present framework since it can be encoded using XML or VRML. Next to
that it is the successor ofVRMLand supports many features
ofGeoVRMLwithin
thegeospatial extensionwith only minor differences. For this reason it would result in a comparable size when using the VRML encoding and is
left out in the following comparison.FileVerticesOriginalCityJSONCityJSON (Origin)GeoJSONGeoOBJGeoOBJ (Origin)GeoOFFGeoOFF (Origin)GeoPLYGeoPLY (Origin)GeoSTLGeoSTL (Origin)GeoVRMLGeoVRML (Origin)GMLCityGMLKMLColladaalligator3208184.07308.59214.051402.25278.69184.16272.42177.89272.57178.041396.25877.53319.46225.362202.642204.782237.52252.84amsterdam (lod12)816665532.228470.136299.0136669.927703.425532.307543.885372.767544.035372.9136455.3524063.048732.876562.1857459.3357461.4758369.687010.23amsterdam (lod13)875285941.459095.586765.4939431.348271.615941.538100.625770.548100.785770.7039202.3325855.529375.497045.8361789.5661791.7062768.627526.90amsterdam (lod22)1118747713.5711764.698775.5950944.4310702.757713.6610484.217495.1110484.367495.2750646.4533341.3712115.759127.0979824.7379826.8781089.439743.88armadillo499903608.545279.484097.0523622.394791.053608.634693.413510.984693.563511.1423476.9216381.745426.154244.1536998.2737000.4137583.914352.77beast323111873.352850.452094.729550.492629.151873.442566.041810.332566.191810.489686.466660.983008.322253.0313723.1513725.2813944.122440.75beetle-alt198871364.182037.911554.369120.801847.801364.261808.951325.411809.101325.579067.756249.002099.641616.5314292.7414294.8814519.081677.35beetle114864.34105.1374.90485.0194.6464.4292.3862.1692.5362.32482.03319.74109.4379.64759.87762.01771.7586.36berlin (112-100-1-1)48785948961.1055113.5853715.41236389.9750359.3448961.1849406.4848008.3249406.6348008.47233359.29224993.2956550.7555153.02366578.82366580.96372280.3646080.28berlin (112-103-1-1)30649530495.9134371.9133481.48148411.1031386.4130495.9930787.7729897.3530787.9229897.50146510.83141185.7635275.9534385.95230153.20230155.34233732.9828699.57bimba1124558132.8212024.379231.3253081.7010925.948132.9010706.287913.2510706.437913.4052769.7736012.0212354.049561.4383171.8583173.9984489.509938.64cheburashka6669420.93667.32486.383148.23601.94421.01588.91407.98589.06408.143129.512044.29687.07506.574932.364934.505010.33544.41cow2903182.93286.82211.611369.35258.21183.01252.53177.33252.68177.491361.40909.95295.53220.752146.052148.192179.90233.77fandisk6475391.15646.70454.713047.66583.21391.23570.56378.58570.71378.733031.651879.89665.88474.324779.884782.024855.58527.38happy492513443.425200.363925.1123271.054718.753443.514622.543347.304622.693347.4523134.5915475.175344.564069.7436462.9836465.1137040.564286.65homer6002378.70600.39437.642832.50541.53378.78529.80367.06529.95367.212815.801839.43618.19455.874438.164440.304508.31489.86horse484854382.415150.794856.2223164.354677.064382.504582.364287.794582.514287.9422960.0721192.625293.054998.9136137.5336139.6736705.534252.00igea1343459716.5014490.8011028.7863413.2213178.609716.5812916.199454.1812916.349454.3363040.7642268.4514884.6011423.0299360.6699362.80100934.8311998.91lucy499873728.415310.784216.8823867.914822.383728.494724.743630.854724.893631.0123660.9117097.445457.444363.9837242.9937245.1337828.604384.12max-planck500773628.485297.054117.2123729.974808.403628.574710.583530.754710.733530.9123558.6516499.045444.444265.0437107.8637110.0037693.594369.81nefertiti499713621.605288.334109.9223695.484800.083621.684702.473524.084702.623524.2323529.7316459.265434.944256.9737066.2937068.4237651.704361.96ogre621943820.096569.444426.3029260.925963.303820.175841.823698.695841.973698.8529090.9216271.916752.974610.2645852.0345854.1746578.485418.86rocker-arm10044666.931008.63765.364742.64910.28667.02890.65647.39890.80647.554714.263254.511038.25795.427430.397432.537547.93823.07spot2930186.33289.49215.271380.09260.62186.41254.89180.68255.04180.841372.51927.27298.28224.502163.752165.892197.91235.95stanford-bunny359472442.783719.062784.6216390.433377.292442.863307.082372.643307.232372.8016294.3910877.713757.362852.2125682.4125684.5426089.193069.58suzanne50723.7641.7127.51149.1938.0323.8437.0422.8537.1923.01150.4095.1744.4430.68213.99216.13217.2236.16teapot3644202.44341.26234.581489.62309.19202.52302.07195.40302.22195.551481.45937.85354.97248.732335.362337.502372.23281.07woody69436.3363.5042.99297.2456.9236.4255.5635.0655.7135.22295.92186.1266.0946.01466.95469.08474.2152.25xyzrgb_dragon1250669280.7513452.3310501.4559080.2112231.719280.8311987.429036.5511987.579036.7058707.6841024.4313811.4810864.7592511.8892514.0193975.8711134.29Average668835531.917236.096177.4531497.916590.635532.006459.995401.356460.145401.5131220.1425006.227435.086378.0049078.8249080.9549849.966010.68Note:Sizes are in KiloByte (KB)Note 2:Some results are below the baseline. GeoOFF and GeoPLY are for example smaller compared to the input OBJ
file's, because of the missing line prefix. While vertices and faces are marked withvandfin OBJ, this prefix is
implicitly given by the ordering and the number of elements in the two mentioned file formats (and their base
formatsOFFandPLY). The line prefix results in a comparable high overhead, when it comes to files with thousands
of lines.An interactive visualization of the size comparison can be foundhere.Getting startedTo set up and use the project have a look at the detailed descriptionhereYou can install the framework via pip:pip install geofilesImporting filesThe present project supports multiple reader implementations for importing (geo-referenced) geometry files (.obj,.geoobj,.ply,.geoply,.off,.geooff,.stl,.geostl,CityJSON,GeoJSON,KML,GML,CityGML,Collada (.dae)).
Using one of these readers is the entrypoint to the framework and allows to create an in-memory geometry model using
theGeoObjectFileclass. Note that only a subset of the features of the named files are currently supported. So
reading files with non-supported features may result in a loss of information (e.g. smoothing groups in.obj, exact
property definitions of.plyor classes of CityObjects inCityJSON, etc.)reader=GeoObjReader()path="mygreatfile.geoobj"withopen(path)asfile:geoObjFile:GeoObjectFile=reader.read(file)Next to file imports, the framework also supports to read geometric objects from strings:geoobj="""crs urn:ogc:def:crs:OGC:2:84v 14.2842865755919 48.3028533074941 279.307006835938v 14.2842865755919 48.3028533074941 280.307006835938v 14.2842865755907 48.3028443243414 280.307006835938o trianglef 1 2 3"""geoObjFile:GeoObjectFile=reader.read_string(file)ConvertingThe present framework supports different conversion methodologies as converting from one to another coordinate reference
system.
Next to the CRS-conversion the framework also supports to transform between origin and non-origin based representations,
as well as between geo-referenced and local representations.
Finally, there is also basic support for transforming (scale, rotation, translation) a model's vertices.# 1. Change coordinate systemconverter=CrsConverter()converted=converter.convert(geoObjFile,"urn:ogc:def:crs:OGC:2:84")# 2. Change to origin-based representationoriginconverter=OriginConverter()origin_based=originconverter.to_origin(converted)# 3. Apply transformationtransformer=Transformer()origin_based.scaling=[2,2,2]origin_based.translation=[5,10,-5]origin_based.rotation=[45,30,90]transformed=transformer.transform(origin_based)Determining Geographical ExtentThe geographical extent of a file can be determined in two ways:Only searching for the min and max coordinates of the values (not considering transformation or origin information)Determining the geographical extent considering all available meta informationDepending on the use case one variant is more suitable than the other. If you are going to ignore transformation
information in your application, the additional overhead of the second method is not required, otherwise if you want to
know the extents considering this meta information you have to use theExtentCalculatorclass.# 1. Classic geographical extentgeoObjFile:GeoObjectFile=...geoObjFile.update_extent()# 2. Using the ExtentCalculatorobjFileWithExtents=ExtentCalculator.update_extent(geoObjFile,True,True)Exporting filesFinally, the in-memory model representations can be re-written to your hard drive using one of the writer
implementations.
Note:That some file formats presuppose a specific CRS (e.g..kmlrequires vertices inWgs84representation)Most file formats do not support transformation (scale, rotation, translation) meta-information. A model's vertices
have to be transformed first before exported to such a file format.The writers will automatically append the specific file type (unless you setappend_file_typetoFalse)writer=GeoPlyWriter()writer.write("mygreatfile.geoply",transformed,append_file_type=False)Alternatively, the writers can also be used to create file format specific output like JSON (for GeoJSON, CityJSON, ...)
, XML (for GML, KML, ...) or just string:writer=GeoPlyWriter()string_output=writer.write_to_string(transformed)writer=GeoJsonWriter()json_output=writer.create_json(transformed)writer=GmlWriter()xml_output=writer.create_xml(transformed)FAQWhy yet another 3D geometry file format like.geoobj?During our research in the context of outdoor augmented reality applications, we were looking for a possibility
for exchanging geo-referenced geometry models. In this context, the other named file formats come with a too high
overhead (e.g.XMLtags or not required meta information as object types like inCityJson) in our opinion and
are for this reason not ideal.You describe multiple geo-referenced file formats. Which one should I use for geo-referenced 3D models?This depends on the use case. If you have to exchange the models with as little overhead as possible we recommend
using the proposed.geoply,.geoobjor.geooffformat extensions. If you require semantic expressiveness,
you should prefer other formats likeCityJsonorGML.How are vertices defined, if I use the origin-based approach of.geoobj,.geoply,.geooffor.geostl?In the origin-based version, vertices are represented within a local Cartesian coordinate system with the defined
origin as coordinate system origin (0, 0, 0).The local coordinate system is intended as a left handed system.The local coordinate system uses the x-axis as abscissa axis (width information), y-axis as ordinate axis (length
information) and z-axis as applicate axis (height information).The units used in this type of coordinate system are assumed to be inmeters.How is the transformation information defined?The proposed transformation information is separated into tuples (one value per axis) for translation, rotation
and scale.Per default: For the translation, meter based offsets are intended to be used, the rotation is based on degrees
and the scale tuple is represented using numeric factors.GeoOBJ,GeoOFFandGeoPLYsupport to change the used unit for translation/rotation informationContributingFirst make sure to read ourgeneral contribution guidelines.LicenceCopyright (c) 2021 the original author or authors.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES.This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one athttps://mozilla.org/MPL/2.0/.ResearchIf you are going to use this project as part of a research paper, we would ask you to reference this project by citing
it.