How to Integrate 3DCityDB Importer/Exporter into a Custom Web API (Oracle 19c Backend)

[Mganjirad]

Hi 3DCityDB team,

First of all, thank you for providing such a powerful and well-structured tool for working with CityGML and 3D urban models. I’m currently working on a project where I need to:

• Ingest CityGML, OBJ, or glTF files
  

• Convert them to SDO_GEOMETRY (solid)
  

• Store them in Oracle Spatial (19c)
  

• Make them available via a custom Web API
  

I’ve seen that the Importer/Exporter tool supports Oracle databases, and I’ve successfully used it in a desktop workflow. However, I would like to automate this process and integrate it into a backend Web API (for example, developed in C# or Python), where users can upload 3D model files, and the system performs the import into the Oracle database programmatically.
My key questions are:

1. Is there any way to invoke the Importer/Exporter functionality from within a web service, such as via CLI, Java API, or some service endpoint?

2. If not directly possible, is there any recommended approach or workaround to integrate 3DCityDB import/export into a custom backend pipeline?

3. Are there any Java classes or configurations in the Importer/Exporter module that could be reused or wrapped as part of a server-side integration?

My current Oracle version is 19c, but I’m open to upgrading to a newer version if it makes the integration easier or more robust.

I'd really appreciate any pointers, documentation references, or shared experiences from the team or community regarding this kind of server-side integration.

Thanks again for your excellent work and support!

Best regards,
Mohammad Ganjirad
GIS & Backend Developer

[clausnagel]

Have you checked chapter 4.9 in the user manual on the Importer/Exporter CLI? https://3dcitydb-docs.readthedocs.io/en/latest/impexp/cli.html

[Mganjirad]

Thank you very much for your helpful reply and for pointing me to the CLI documentation. It definitely opens a clear path for automating imports using external scripts or backend processes.

From a Web API integration perspective, the CLI has both advantages and limitations:

✅ Pros:

Enables full automation of import/export operations.

Can be executed in backend services via subprocess calls (e.g., in C# or Python).

Supports Oracle Spatial, which fits my target system (currently Oracle 19c).

⚠️ Cons:

No direct REST or programmatic API interface — requires invoking an external Java process.

Limited flexibility in modifying or dynamically configuring imports on the fly.

Managing file-based config and logs in real-time web environments can be a bit tricky.

That said, the CLI is still a solid option for batch automation.

However, I’m particularly interested in how the Importer/Exporter internally handles the conversion of CityGML or CityJSON data into valid 3D SDO_GEOMETRY objects in Oracle. I’d like to understand the relevant source code to explore how geometry mapping, solid modeling, and database insertion are handled under the hood.

📌 My actual goal is not to deploy the full 3DCityDB schema or server — I only need to extract and reuse the logic that reads CityGML/CityJSON and generates SDO_GEOMETRY solids for Oracle Spatial.

Could you kindly guide me to:

The part(s) of the source code responsible for this conversion and database writing?

Or any internal utility classes or modules that encapsulate this functionality?

Any hints would be highly appreciated, and could help me better tailor a lightweight integration for my use case.
Thank you again for your time and the amazing work you've done with 3DCityDB.

Best regards,

[BWibo]

Are you strictly limited to Oracle Spatial?
If no, you could use PostgREST on top of the PostgreSQL version of 3DCityDB.
It allows you to create a REST API by exposing database views, tables or functions defining your API endpoints. PostgREST offer out of the box support for e.g. powerful filtering capabilites and much more.

An advantage of this approach is that you can use v5 of 3DCityDB and citydb-tool. See https://docs.3dcitydb.net/ for more.

Possibly, there are similar services you can use on top of Oracle databases?
@karinpatenge: Do you know something like this?

[Mganjirad]

@BWibo ,Thank you very much for the insightful suggestion. PostgREST on top of PostgreSQL indeed seems like a powerful and flexible approach, especially with support for CityDB v5 and citydb-tool. I completely understand the value of such RESTful access layers for geospatial applications.

However, in our current ecosystem, we are strictly working with Oracle Spatial 19c as the core of both our spatial and non-spatial services. Migrating to PostgreSQL would introduce considerable overhead in terms of time, resources, and architectural changes — which is unfortunately not feasible for us in the short term.

That said, we’re very interested in implementing a similar automated 3D data ingestion workflow, where formats like CityGML or CityJSON can be directly converted to 3D Oracle Spatial solids and stored in tables for further spatial analysis via web services.

Currently, I don’t intend to install or fully rely on 3DCityDB, but rather I'm exploring ways to understand and possibly reuse the logic of its Oracle Importer/Exporter components, especially how it handles the transformation of CityGML to Oracle 3D spatial types.

Would you mind guiding me on where in the 3DCityDB source code (especially for Oracle) I can find the transformation and loading logic? That would be incredibly helpful for implementing a lightweight, customized and web-based pipeline suited to our Oracle-based infrastructure.

Again, I really appreciate your help and any further direction you can provide.

Best regards,
Mohammad

[BWibo]

Sorry, I'm not familiar with the Oracle code, but it should be easy to find in the Importer/Exporter repo.
I can recommend the Search in repo function:

[Mganjirad]

Thank you very much for your response and the helpful suggestion. I’ll definitely explore the Importer/Exporter repository. Thanks

[clausnagel]

citydb-tool is the more modern tool with an easy-to-use Java API. However, it only supports PostgreSQL at the moment. If you must stick with Oracle, you have to go with the legacy Importer/Exporter. Here is a high-level summary of its flow for importing CityGML/CityJSON:

1. citygml4j 2.x is used for parsing (and writing) CityGML/CityJSON data. Moreover, the Importer/Exporter uses the citygml4j class hierarchy as internal data model.
2. The classes in org.citydb.core.operation.importer are generally reponsible for converting citygml4j objects from CityGML/CityJSON and importing them into the database.
3. The org.citydb.core.operation.importer.database.content.DBSurfaceGeometry class converts citygml4j geometries into a databse-agnostic GeometryObject object defined in the org.citydb.core.database package. For solid geometries, it uses the helper class org.citydb.core.operation.importer.util.GeometryConverter to convert a citygml4j Solid object.
4. The org.citydb.core.database package is a database abstraction layer. It defines general, database-agnostic interfaces such as GeometryObject, which are used throughout the code. The database adapters in org.citydb.core.database.adapter implement these interfaces for a specific database such as Oracle. So, look here to see how the solid represented as GeometryObject is finally turned into an Oracle geometry.

My recommendation is to manually create a very simple CityGML or CityJSON dataset. For example, a Building which just a lod1Solid geometry. And then debug through the code at the above mentioned places to see what happens.

[Mganjirad]

Thanks a lot for the helpful explanation and the suggestion! I’ll try the minimal dataset approach and dig into the conversion logic. Really appreciate your time.