diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md
new file mode 100644
index 0000000..d4073f0
--- /dev/null
+++ b/.agents/skills/release/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: release
+description: Prepare, validate, and create an Up3date release tag by following docs/RELEASE.md. Use when the user asks to prepare, tag, publish, retry, or troubleshoot a project release.
+---
+
+# Release
+
+Prepare and create an Up3date release tag using the repository's release
+runbook as the authoritative procedure.
+
+## Workflow
+
+1. Locate the repository root and read `docs/RELEASE.md` completely before
+ taking any release-related action. Follow its current contents even when
+ they differ from this summary.
+2. Inspect the current branch, working tree, remotes, version declarations,
+ lockfile, changelog, existing tags, and relevant GitHub release state.
+ Do not modify or discard unrelated user changes.
+3. Determine the intended semantic version without a `v` prefix. If the user
+ has not supplied it and it cannot be unambiguously inferred from completed
+ release preparation, ask which version to release.
+4. Prepare and synchronize the version and release notes exactly as required
+ by `docs/RELEASE.md`. Run the prescribed local quality checks and resolve
+ failures that are within the requested release scope.
+5. Stop before tagging if the release commit is not on `main`, the local
+ `main` is not current, the worktree is dirty, required checks have failed,
+ versions disagree, release notes are missing, or the tag/release already
+ exists. Explain the concrete blocker instead of bypassing a safeguard.
+6. Summarize the version, target commit, validation results, and the command
+ that will publish the tag. Obtain explicit user confirmation immediately
+ before creating or pushing the tag unless the user's current request
+ already explicitly authorizes creating and pushing that exact tag.
+7. Create and push the release tag only through the helper specified by
+ `docs/RELEASE.md`. Do not manually create a GitHub release; the tag-driven
+ workflow owns that step.
+8. Report the pushed tag and the release workflow result or link when it is
+ available. If the workflow fails, diagnose it and follow the runbook's
+ recovery rules.
+
+## Safety Rules
+
+- Never force-update a release tag.
+- Never delete or recreate a tag unless the user explicitly authorizes the
+ exact recovery operation and the runbook permits it.
+- Treat a published release tag as immutable.
+- Do not bypass branch protection, tag protection, required checks, or
+ version synchronization.
+- Do not invent release notes. Derive them from the actual changes and keep
+ them consistent with the existing changelog style, asking the user when a
+ product-facing description requires judgment.
+- If `docs/RELEASE.md` is absent or contradictory, stop and report the issue.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 0000000..606c9f5
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1,5 @@
+# Approval from either owner is sufficient for repository-wide changes.
+* @konmast3r @liberostelios
+
+# Keep ownership explicit for changes to the ownership policy itself.
+/.github/CODEOWNERS @konmast3r @liberostelios
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
new file mode 100644
index 0000000..4f0f4a4
--- /dev/null
+++ b/.github/workflows/quality.yml
@@ -0,0 +1,264 @@
+name: Code quality
+
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: quality-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ quality:
+ name: Ruff, typing, and unit tests
+ runs-on: ubuntu-latest
+ continue-on-error: false
+
+ defaults:
+ run:
+ shell: bash --noprofile --norc -euo pipefail {0}
+
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+ - name: Install uv and Python
+ uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+ with:
+ enable-cache: true
+ python-version: "3.13"
+
+ - name: Install dependencies
+ run: uv sync --locked --dev
+
+ - name: Check formatting
+ id: formatting
+ continue-on-error: true
+ run: uv run ruff format --check --diff .
+
+ - name: Lint, imports, naming, and annotations
+ id: linting
+ continue-on-error: true
+ run: uv run ruff check --output-format=github .
+
+ - name: Enforce city_object spelling
+ id: city_object_spelling
+ continue-on-error: true
+ run: |
+ if grep -RInE --include='*.py' '(^|[^[:alnum:]_])[a-z_]*cityobjects?[a-z_]*([^[:alnum:]_]|$)' addon.py core models tests __init__.py; then
+ echo 'Use city_object or city_objects in Python identifiers.'
+ exit 1
+ fi
+
+ - name: Type check
+ id: type_checking
+ continue-on-error: true
+ run: uv run mypy
+
+ - name: Run unit tests
+ id: unit_tests
+ continue-on-error: true
+ env:
+ COVERAGE_FILE: .coverage.unit
+ run: >-
+ uv run pytest
+ --cov=.
+ --cov-branch
+ --cov-report=
+ --cov-fail-under=0
+
+ - name: Upload unit coverage
+ if: always()
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+ with:
+ name: unit-coverage
+ path: .coverage.unit
+ include-hidden-files: true
+ if-no-files-found: ignore
+ retention-days: 1
+
+ - name: Report quality results
+ if: always()
+ env:
+ FORMATTING_RESULT: ${{ steps.formatting.outcome }}
+ LINTING_RESULT: ${{ steps.linting.outcome }}
+ SPELLING_RESULT: ${{ steps.city_object_spelling.outcome }}
+ TYPE_CHECKING_RESULT: ${{ steps.type_checking.outcome }}
+ UNIT_TESTS_RESULT: ${{ steps.unit_tests.outcome }}
+ run: |
+ {
+ echo '## Code quality results'
+ echo '| Check | Result |'
+ echo '| --- | --- |'
+ echo "| Formatting | ${FORMATTING_RESULT} |"
+ echo "| Linting | ${LINTING_RESULT} |"
+ echo "| city_object spelling | ${SPELLING_RESULT} |"
+ echo "| Type checking | ${TYPE_CHECKING_RESULT} |"
+ echo "| Unit tests | ${UNIT_TESTS_RESULT} |"
+ } >> "${GITHUB_STEP_SUMMARY}"
+
+ for result in \
+ "${FORMATTING_RESULT}" \
+ "${LINTING_RESULT}" \
+ "${SPELLING_RESULT}" \
+ "${TYPE_CHECKING_RESULT}" \
+ "${UNIT_TESTS_RESULT}"; do
+ if [[ "${result}" != 'success' ]]; then
+ exit 1
+ fi
+ done
+
+ blender_integration:
+ name: Blender ${{ matrix.blender_version }} integration tests
+ needs: quality
+ runs-on: ubuntu-latest
+ continue-on-error: false
+
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - blender_version: "5.2.0"
+ blender_series: "5.2"
+ blender_sha256: "96f6c181a30f4950607839dc84d42a354b250d8a0231b098b59b7bc69c351c48"
+
+ defaults:
+ run:
+ shell: bash --noprofile --norc -euo pipefail {0}
+
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+ - name: Install uv and Python
+ uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+ with:
+ enable-cache: true
+ python-version: "3.13"
+
+ - name: Install dependencies
+ run: uv sync --locked --dev
+
+ - name: Install Blender ${{ matrix.blender_version }}
+ id: blender_setup
+ continue-on-error: true
+ env:
+ BLENDER_VERSION: ${{ matrix.blender_version }}
+ BLENDER_SERIES: ${{ matrix.blender_series }}
+ BLENDER_SHA256: ${{ matrix.blender_sha256 }}
+ run: |
+ blender_directory="blender-${BLENDER_VERSION}-linux-x64"
+ blender_archive="${RUNNER_TEMP}/${blender_directory}.tar.xz"
+ curl --fail --location --silent --show-error \
+ "https://download.blender.org/release/Blender${BLENDER_SERIES}/${blender_directory}.tar.xz" \
+ --output "${blender_archive}"
+ echo "${BLENDER_SHA256} ${blender_archive}" \
+ | sha256sum --check --strict
+ tar --extract --file "${blender_archive}" --directory "${RUNNER_TEMP}"
+ echo "BLENDER_EXECUTABLE=${RUNNER_TEMP}/${blender_directory}/blender" \
+ >> "${GITHUB_ENV}"
+
+ - name: Run headless Blender integration tests
+ id: blender_integration
+ continue-on-error: true
+ env:
+ COVERAGE_FILE: .coverage.blender
+ PYTHONPATH: ${{ github.workspace }}/.venv/lib/python3.13/site-packages
+ run: >-
+ "${BLENDER_EXECUTABLE}"
+ --background
+ --factory-startup
+ --python-use-system-env
+ --python-exit-code 1
+ --python tests/blender/run_integration_tests.py
+
+ - name: Upload Blender coverage
+ if: always()
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+ with:
+ name: blender-coverage-${{ matrix.blender_version }}
+ path: .coverage.blender
+ include-hidden-files: true
+ if-no-files-found: ignore
+ retention-days: 1
+
+ - name: Report Blender integration results
+ if: always()
+ env:
+ BLENDER_SETUP_RESULT: ${{ steps.blender_setup.outcome }}
+ BLENDER_INTEGRATION_RESULT: ${{ steps.blender_integration.outcome }}
+ run: |
+ {
+ echo '## Blender ${{ matrix.blender_version }} integration results'
+ echo '| Check | Result |'
+ echo '| --- | --- |'
+ echo "| Blender setup | ${BLENDER_SETUP_RESULT} |"
+ echo "| Headless Blender integration | ${BLENDER_INTEGRATION_RESULT} |"
+ } >> "${GITHUB_STEP_SUMMARY}"
+
+ for result in \
+ "${BLENDER_SETUP_RESULT}" \
+ "${BLENDER_INTEGRATION_RESULT}"; do
+ if [[ "${result}" != 'success' ]]; then
+ exit 1
+ fi
+ done
+
+ coverage:
+ name: Combined test coverage
+ needs: [quality, blender_integration]
+ runs-on: ubuntu-latest
+
+ defaults:
+ run:
+ shell: bash --noprofile --norc -euo pipefail {0}
+
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+ - name: Install uv and Python
+ uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+ with:
+ enable-cache: true
+ python-version: "3.13"
+
+ - name: Install dependencies
+ run: uv sync --locked --dev
+
+ - name: Download unit coverage
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+ with:
+ name: unit-coverage
+ path: .coverage-inputs/unit
+
+ - name: Download Blender coverage
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+ with:
+ pattern: blender-coverage-*
+ path: .coverage-inputs/blender
+ merge-multiple: true
+
+ - name: Check combined test coverage
+ run: |
+ uv run coverage combine .coverage-inputs/unit .coverage-inputs/blender
+
+ if uv run coverage report | tee coverage-report.txt; then
+ coverage_status=0
+ else
+ coverage_status=$?
+ fi
+
+ {
+ echo '## Combined test coverage'
+ echo '```text'
+ cat coverage-report.txt
+ echo '```'
+ } >> "${GITHUB_STEP_SUMMARY}"
+
+ exit "${coverage_status}"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..2773e65
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,169 @@
+name: Create release
+
+on:
+ push:
+ tags:
+ - "*.*.*"
+
+permissions:
+ contents: write
+
+jobs:
+ release:
+ name: Create release
+ runs-on: ubuntu-latest
+
+ defaults:
+ run:
+ shell: bash --noprofile --norc -euo pipefail {0}
+
+ steps:
+ - name: Check out repository history
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ fetch-depth: 0
+
+ - name: Read declared versions
+ id: versions
+ run: |
+ python - <<'PY' >> "${GITHUB_OUTPUT}"
+ import ast
+ import tomllib
+ from pathlib import Path
+
+ with Path("pyproject.toml").open("rb") as file:
+ project_version = tomllib.load(file)["project"]["version"]
+
+ with Path("blender_manifest.toml").open("rb") as file:
+ manifest_version = tomllib.load(file)["version"]
+
+ module = ast.parse(Path("__init__.py").read_text(encoding="utf-8"))
+ bl_info_node = next(
+ node
+ for node in module.body
+ if isinstance(node, ast.Assign)
+ and any(
+ isinstance(target, ast.Name) and target.id == "bl_info"
+ for target in node.targets
+ )
+ )
+ bl_info = ast.literal_eval(bl_info_node.value)
+ addon_version = ".".join(str(part) for part in bl_info["version"])
+
+ with Path("uv.lock").open("rb") as file:
+ lock_data = tomllib.load(file)
+ lock_version = next(
+ package["version"]
+ for package in lock_data["package"]
+ if package["name"] == "up3date"
+ )
+
+ print(f"project={project_version}")
+ print(f"manifest={manifest_version}")
+ print(f"addon={addon_version}")
+ print(f"lock={lock_version}")
+ PY
+
+ - name: Validate release tag
+ env:
+ PROJECT_VERSION: ${{ steps.versions.outputs.project }}
+ MANIFEST_VERSION: ${{ steps.versions.outputs.manifest }}
+ ADDON_VERSION: ${{ steps.versions.outputs.addon }}
+ LOCK_VERSION: ${{ steps.versions.outputs.lock }}
+ run: |
+ if [[ ! "${GITHUB_REF_NAME}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "Release tags must use the 0.0.0 format without a prefix."
+ exit 1
+ fi
+ if [[ "${GITHUB_REF_NAME}" != "${PROJECT_VERSION}" ]]; then
+ echo "Release tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${PROJECT_VERSION}."
+ exit 1
+ fi
+ if [[ "${MANIFEST_VERSION}" != "${PROJECT_VERSION}" ]]; then
+ echo "blender_manifest.toml version ${MANIFEST_VERSION} does not match pyproject.toml version ${PROJECT_VERSION}."
+ exit 1
+ fi
+ if [[ "${ADDON_VERSION}" != "${PROJECT_VERSION}" ]]; then
+ echo "bl_info version ${ADDON_VERSION} does not match pyproject.toml version ${PROJECT_VERSION}."
+ exit 1
+ fi
+ if [[ "${LOCK_VERSION}" != "${PROJECT_VERSION}" ]]; then
+ echo "uv.lock version ${LOCK_VERSION} does not match pyproject.toml version ${PROJECT_VERSION}."
+ exit 1
+ fi
+
+ - name: Read release notes
+ id: release_notes
+ env:
+ PROJECT_VERSION: ${{ steps.versions.outputs.project }}
+ run: |
+ notes_file="${RUNNER_TEMP}/up3date-release-notes.md"
+ awk -v version="${PROJECT_VERSION}" '
+ index($0, "## [" version "]") == 1 { in_section = 1; next }
+ in_section && /^## / { exit }
+ in_section { print }
+ ' CHANGELOG.md > "${notes_file}"
+
+ if [[ -z "$(tr -d '[:space:]' < "${notes_file}")" ]]; then
+ echo "No notes found for version ${PROJECT_VERSION} in CHANGELOG.md."
+ exit 1
+ fi
+
+ echo "notes_file=${notes_file}" >> "$GITHUB_OUTPUT"
+
+ - name: Verify tag is on main
+ run: |
+ git fetch --no-tags origin main:refs/remotes/origin/main
+ if ! git merge-base --is-ancestor "${GITHUB_SHA}" origin/main; then
+ echo "Tag ${GITHUB_REF_NAME} does not point to a commit on main."
+ exit 1
+ fi
+
+ - name: Build Blender add-on package
+ id: package
+ env:
+ PROJECT_VERSION: ${{ steps.versions.outputs.project }}
+ run: |
+ package_file="${RUNNER_TEMP}/up3date-${PROJECT_VERSION}.zip"
+
+ git archive \
+ --format=zip \
+ --output="${package_file}" \
+ "${GITHUB_SHA}" \
+ -- \
+ blender_manifest.toml \
+ __init__.py \
+ addon.py \
+ core \
+ models \
+ LICENSE
+
+ unzip -t "${package_file}"
+
+ if unzip -Z1 "${package_file}" | grep -Eq '(^|/)(tests|\.github|docs|scripts)/|(^|/)(pyproject\.toml|uv\.lock)$'; then
+ echo "The release package contains development or infrastructure files."
+ exit 1
+ fi
+
+ echo "package_file=${package_file}" >> "${GITHUB_OUTPUT}"
+
+ - name: Create GitHub release
+ env:
+ GH_TOKEN: ${{ github.token }}
+ PACKAGE_FILE: ${{ steps.package.outputs.package_file }}
+ PROJECT_VERSION: ${{ steps.versions.outputs.project }}
+ RELEASE_NOTES_FILE: ${{ steps.release_notes.outputs.notes_file }}
+ run: |
+ if gh release view "${PROJECT_VERSION}" --repo "${GITHUB_REPOSITORY}" >/dev/null 2>&1; then
+ echo "GitHub release ${PROJECT_VERSION} already exists; skipping."
+ exit 0
+ fi
+
+ gh release create \
+ "${PROJECT_VERSION}" \
+ "${PACKAGE_FILE}#Up3date Blender add-on" \
+ --repo "${GITHUB_REPOSITORY}" \
+ --verify-tag \
+ --target "${GITHUB_SHA}" \
+ --title "${PROJECT_VERSION}" \
+ --notes-file "${RELEASE_NOTES_FILE}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..635d470
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to Up3date are documented here.
+
+## [0.0.0]
+
+- Add CityJSON 2.0 document parsing and serialization.
+- Support City Objects, attributes, relationships, extensions, metadata,
+ coordinate transforms, appearances, geometry templates, and geometry
+ instances.
+- Support CityJSON geometry primitives and LoD values through the Python model
+ layer.
+- Import supported surface and solid geometries as editable Blender meshes with
+ semantic materials.
+- Preserve unsupported editable geometry and CityJSON document data for
+ round-trip export.
+- Add CityJSON import/export integration with Blender 5.2.
diff --git a/README.md b/README.md
index bdd848d..1cd4515 100644
--- a/README.md
+++ b/README.md
@@ -1,132 +1,133 @@
-*This add-on was originally developed by Konstantinos Mastorakis ([konmast3r](https://github.com/konmast3r/)) as part of their research orientation project for the MSc Geomatics programme of TU Delft. Its functionality was further developed for the needs of their MSc thesis [An integrative workflow for 3D city model versioning](http://resolver.tudelft.nl/uuid:a7f7f0c8-7a34-454e-973a-d55f5b8b0dfe)*
-
-I plan to keep developing this add-on as a free-time project since I enjoy it a lot and because I see that there are many enthusiasts out there already using it in ways more serious than I expected. Although I am very excited to see that, I can't guarantee how much and how often `Up3date` going to be further developed.
-
-
# Up3date
-A Blender add-on to import, edit and export new instances of [CityJSON](http://cityjson.org)-encoded 3D city models. All buildings' levels of detail (LoD), attributes and semantic surfaces are stored and can be accesed via Blender's graphical interface.
+Up3date is a Blender add-on for importing, inspecting, editing, and exporting
+[CityJSON 2.0](https://www.cityjson.org/specs/2.0.2/) 3D city models. City
+object attributes, relationships, levels of detail (LoDs), coordinates, and
+semantic surfaces are represented in Blender through object and material
+custom properties.
+The add-on was originally developed by Konstantinos Mastorakis ([konmast3r](https://github.com/konmast3r/))
+as part of the MSc Geomatics programme at TU Delft and was further developed
+for the MSc thesis [An integrative workflow for 3D city model versioning](http://resolver.tudelft.nl/uuid:a7f7f0c8-7a34-454e-973a-d55f5b8b0dfe).
## Requirements
-- Blender Version >=2.80
+- Blender 5.2 or newer
+The add-on follows the CityJSON schemas and document structure described in
+the linked specification.
-## Testing Datasets
+## CityJSON support
-You can find sample datasets at the official [CityJSON](https://www.cityjson.org/datasets/#datasets-converted-from-citygml) website. In case you have 3D city model datasets encoded in `CityGML` you can use the free [Conversion Tool](https://www.cityjson.org/help/users/conversion/) to convert to and from `CityGML` and `CityJSON` and vice versa.
+The importer and exporter support the CityJSON document structure, including:
-Trying to import really big datasets such as `New York` will take several minutes because of the amount of information contained. With the rest sample `CityJSON` files everything should work noticeably faster. Depending on your machine, it could take some seconds up to few minutes minute to import the 3D city model.
+- City Objects, attributes, parent/child relationships, and extension City
+ Objects whose type starts with `+`;
+- `MultiPoint`, `MultiLineString`, `MultiSurface`, `CompositeSurface`, `Solid`,
+ `CompositeSolid`, and `MultiSolid` geometry primitives;
+- LoDs from `0` through `3`, including decimal LoDs such as `2.2`;
+- semantic surfaces and their custom properties;
+- coordinate `transform` objects and `metadata`, including the CRS;
+- `appearance`, `geometry-templates`, `GeometryInstance`, and `extensions`.
+There is an important distinction between parsing and Blender visualization:
+`MultiSurface`, `CompositeSurface`, and `Solid` geometries are converted to
+editable Blender meshes. Other CityJSON geometry types, including
+`MultiPoint`, `MultiLineString`, `CompositeSolid`, `MultiSolid`, and
+`GeometryInstance`, are kept as empty Blender objects with their serialized
+geometry attached so they can be written back during export. Their geometry is
+not currently expanded into editable Blender meshes.
-## Installation
+Appearance, geometry templates, and extensions are preserved when exporting an
+imported scene, but textures and CityJSON material definitions are not applied
+as Blender materials. Semantic surfaces are represented using Blender
+materials instead.
-1. Download this repository as zip (through GitHub this can be done through the `Clone or download` > `Download ZIP` button).
+## Testing datasets
-2. Run `Blender` and go to `Edit > Preferences > Add-ons` and press the `Install...` button.
+Sample datasets are available from the official
+[CityJSON datasets](https://www.cityjson.org/datasets/). CityGML datasets can
+be converted with the official [CityJSON conversion tools](https://www.cityjson.org/help/users/conversion/).
+Large datasets may take several minutes to import, depending on the machine.
-3. Select the downloaded ZIP and press `Install Add-on from File...`.
+## Installation
-4. Enable the add-on from the list, by ticking the empty box next to the add-on's name.
-*(Optional: If you wish to update to a newer version, un-tick and tick again the add-on to reload it!)*
+1. Download this repository as a ZIP, or create a ZIP containing the add-on
+ files.
+2. In Blender, open `Edit > Preferences > Add-ons` and choose `Install...`.
+3. Select the ZIP and install it.
+4. Enable **Up3date** in the add-on list.
+When updating an installed copy, disable and re-enable the add-on after
+installing the new ZIP.
## Usage
-### Before you start!
-
-- For better understanding of the logic behind the add-on it is **strongly** recommended to have a quick (or thorough :-)) look on the [CityJSON documentation](https://www.cityjson.org/specs/1.0.1/#city-object) if you are unfamiliar with it.
-
-- In case you run `Blender` through the console, useful feedback is given in it, informing about the progress of the import and export process. Upon importing and exporting from `Blender` it might prove quite useful since in the case of big files it can take up to several minutes. It will also print an error message in case of a crash, which is quite useful for debugging purposes.*
-**\*Important: Make sure `Blender's` viewport is in `Object Mode` before importing and exporting a CityJSON file.**
-
-
-### Importing a 3D city model
-
-Go to `File > Import > CityJSON (.json)` and navigate to the directory where the `CityJSON` file is stored and open it.
-
-
-
-#### Options
-
-The following options are available during file selection:
-
-* `Materials' type`:
- * `Surfaces` will create materials according to semantic surfaces *(e.g. RoofSurface, WallSurface)*, if present, and load their attributes.
- * ` City Objects` will create materials per city object and according to the city object's type *(e.g. Building, Road)*.
-* `Reuse materials`: Enable this if you want semantic surface materials to be reused when they share the same type. For example, all `RoofSurface` faces will have the same materials. *This only work when `Surfaces` are selected as `Materials' type`*.
-**\*Important: Greatly improves speed of loading, but semantic surfaces' attributes can be lost, if present!**
-* `Clean scene`: Enable this if you want the script to clean the scene of any existing object prior to importing the `CityJSON` objects.
-
-
-
-#### Useful tips
-
-- After a successful import, you should be able to see the model somewhere close to the axis origin. Rotation of the scene and zooming in and out might help you, locating the model.
-In case you can't see the model, select an object from the `Outliner`* (always in `Object Mode`) and click `View > Frame Selected` or use the `home` button of your keyboard right after importing and try zooming in.
-**\*Important: Make sure the object you are selecting is a `mesh object` and not an `empty object`. You can check that from the small pointing down triangle icon next to the object's name.**
-
-- A different `Collection` is created for each `LoD` present in the 3D city model. In case more than 1 geometry exists for the objects -representing different `LODs` (levels of detail)-, every geometry is stored under the appropriate `Collection`, under the parent `CityObject`. You can display different `Collections` by clicking on the `eye icon` in the `Outliner` at the top right of the interface (see screenshot below). By default all the `LOD_x` collections should be visible right after importing the 3D city model. In case you see any artefacts that is the reason! Choosing only one visible collection should remove all artifacts.
-
-- In case you want to visualize a certain area, click `Shift + B` and draw a rectangle with your mouse to zoom into that specific area of the 3D city model. This also moves the rotation center at that point, which will come handy when you want to inspect specific areas of the model.
-
-- To see the attributes of each object, simply select the object on the screen and click on the `Object Properties` tab on the bottom right of `Blender's` interface. Then click `Custom Properties` drop down menu (see screenshot below).
-
-- To see the semantics of each surface, select an object in `Object Mode`, hit `TAB` to toggle `Edit Mode` and click `Face Select` (top left of the viewport between the `Edit Mode` and the `View` button). Select a face of the object and click on the `Material Properties` tab at the bottom right. Scroll down and click on `Custom Properties`(see screenshot below).
-
-
-
+### Importing a CityJSON file
+
+Choose `File > Import > CityJSON (.json)`, select a file, and confirm the
+import. The file selector provides these options:
+
+- **Materials' type — Surfaces**: create materials from semantic surface
+ types such as `RoofSurface` and `WallSurface`.
+- **Materials' type — City Objects**: create materials from City Object types
+ such as `Building` and `Road`.
+- **Reuse materials**: reuse semantic-surface materials with the same type.
+ This can improve import speed, but per-surface custom properties cannot be
+ represented independently when materials are shared.
+- **Clean scene**: remove existing Blender objects, collections, and stored
+ CityJSON scene properties before importing.
+
+The importer applies a CityJSON `transform` to recover real-world
+coordinates, then translates the model near the scene origin for Blender.
+The CRS and the translation parameters are stored under `World Properties` so
+the exporter can reconstruct the original coordinate space. A collection named
+`LoD` is created for each imported mesh LoD.
+
+For large files, Blender's console reports import progress and timing. If the
+model is not visible, select a mesh object in the Outliner and use `View >
+Frame Selected` (or press `Home`). Keep the viewport in `Object Mode` while
+starting an import or export.
+
+
-
-- `Blender` translates the 3D city model at the beginning of the axis upon importing. The translation parameters and the `CRS` are visible under the `World Properties` for transforming the coordinates back to original if needed.
-
-
-
-
-
-### Exporting a 3D city model
-
-`Up3date's` exporting module was desinged and implemented in order to be able to export any scene of `Blender` into a `CityJSON` file.
-
-**To do so and because there are certain differences between the two data models *(Blender and CityJSON)* some conventions were made to allow lossless exporting. **
-
-In order to export objects from `Blender's` scene the following steps need to be followed:
-
-1. For every `LoD/geometry` a `Mesh object`* has to be added into `Blender's` scene. In case there are already created `Collections` from a previously imported `CityJSON` file, it is not necessary to add the `LoD/geometry` into it, but recommended for organization purposes.
-
-**\*Important: The mesh should be named in a predefined way for `Up3date` to be able to parse it correctly. Example: a `LoD0` geometry should be named as `0: [LoD0] ID_of_object` preserving also the spaces.**
-
-For every `Mesh / geometry` 2 more things needs to be added as `Custom Properties` for the exporter to work. You need to add them yourself after selecting the `Mesh object` in `Object Mode`, clicking on the `Object Properties` button *(second screenshot of the documentation)*, expanding the `Custom Properties` and clicking the `Add` button to add a new `Custom Property`. After addition, edit the property by hitting the `Edit` button next to it. You only need to change `Property Name` and `Property Value`.
-
-* `type`: the_surface_type (*`Surface`, `MultiSurface`, `CompositeSurface` and `Solid`* are accepted)
-* `lod` : the_number_of_lod
-
-
-
-2. An `Empty object` representing the `CityObject` has to be created named as `ID_of_object` *(should be exactly the same name as the `Mesh` described above without the `0: [LoD0] ` prefix)*. To rename any object just double-click on it in the `Outliner` and type a new name.
-This object will be the `parent` for the various `LoD` geometries that a `CityObject` might have. For any `CityObject's` *(aka building's)* attribute you wish to store, a new `Custom Property` has to be added to the `Empty Object`. You have to manually add them via `Blender's` graphical interface exactly the same way as described in `step 1`.
-In case the attributes have to be nested, for example the `postal code` of an `address`, then the `Custom Property` key should be `address.postalcode` so `Up3date` can understand the nested attribute structure from the `.` and handle it accordingly *(see picture below)*.
-
-
-
-3. If the semantics of a *(`LoD 2` or above)* `geometry` surfaces are known and you want to add them, they can be assigned (again) as `Custom Properties` of `Materials` to the respective faces. For every `Mesh / Geometry` object `Blender` allows the creation of `Materials`. To assign semantics that will be exported in the `CityJSON` file, you will need to first create (a) new material(s) inside the newly added `Mesh / Geometry` object (just select the object in `Object Mode` and go to the `Materials` tab). If working with a pre-imported file, you can select an already existing material. Don't worry if the materials' names look like `WallSurface.001` etc. The only information exported is the value of the `Custom Property` `type` of the material (i.e. the semantic).
-In the case of creating new materials you need to add a `Custom Property` to each one of them which must look like the following: `type: Semantic_name` *(`WallSurface`, `RoofSurface`, `GroundSurface` etc)* (see also picture below).
-After successfully adding the material(s) and the `Custom Property`, select the geometry in `Object Mode`, hit the `tab` button to swap to `Edit Mode` and click the `Face Select` button right next to the `Edit Mode` option *(as explained under the 5th `Useful tip` in the section above)*.
-With the appropriate face selected select the appropriate material and hit the `Assign` button to link that material to the face.
-
- 
-
-4. Finally, go to `File > Export > CityJSON (.json)` and export the new instance. Voila!
-
-
-
-## Further Development
-
-If you are using `Visual Studio Code`, you may:
-
-- Install [Blender Development](https://marketplace.visualstudio.com/items?itemName=JacquesLucke.blender-development): a plugin that allows starting and debugging Python scripts from VSC.
-- Install the [fake-bpy-module](https://github.com/nutti/fake-bpy-module) to enable auto-completion: `pip install fake-bpy-module-2.80`.
-
-Clone this repository and have fun!
-If you experience any bugs or have recommendations etc, you can open a new issue, providing all the necessary information. I can't promise to take them all under consideration but I always appreciate them.
\ No newline at end of file
+
+
+City Object attributes are available under an object's `Object Properties >
+Custom Properties`. Semantic surface properties are available on the material
+assigned to a mesh face.
+
+### Exporting a CityJSON file
+
+Choose `File > Export > CityJSON (.json)`. The exporter creates a CityJSON
+document from the current Blender scene. It recognizes imported Up3date
+objects automatically. For geometry created manually, use the following
+structure:
+
+1. Create an **Empty** for each City Object. Name it with the CityJSON object
+ ID and add a custom property `type` such as `Building`, `Road`, or
+ `GenericCityObject`. Add CityJSON attributes with the prefix
+ `attributes.`; for example, `attributes.measuredHeight`. Nested attributes
+ use dots, such as `attributes.address.postalCode`.
+2. Create one **Mesh** child per geometry. Add string custom properties
+ `type` and `lod`. `type` must be `MultiSurface`, `CompositeSurface`, or
+ `Solid` for geometry edited as a Blender mesh. For example, use `lod: 2`
+ and `type: MultiSurface`.
+3. To export semantic surfaces, assign materials to mesh faces and add a
+ string custom property `type` to each material, for example
+ `type: WallSurface` or `type: RoofSurface`.
+4. Export the scene.
+
+The exporter can remove duplicate vertices. Its **Remove vertex duplicates**
+option is enabled by default; **Precision** controls the decimal precision
+used when comparing untransformed vertices. Imported CityJSON transforms are
+preserved and used when coordinates are written back.
+
+
+
+
+
+## Development
+
+For development, testing, and contribution instructions see
+[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
diff --git a/__init__.py b/__init__.py
index e564268..cad0cb3 100644
--- a/__init__.py
+++ b/__init__.py
@@ -1,18 +1,10 @@
-"""Main module of the CityJSON Blender addon"""
-
-import bpy
-from bpy.props import BoolProperty, EnumProperty, IntProperty, StringProperty
-from bpy.types import Operator
-from bpy_extras.io_utils import ExportHelper, ImportHelper
-
-from .core import operator, prop, ui
-from .core.objects import CityJSONExporter, CityJSONParser
+"""Entry point for the Up3date Blender add-on."""
bl_info = {
"name": "Up3date",
"author": "Konstantinos Mastorakis",
- "version": (1, 0),
- "blender": (2, 80, 0),
+ "version": (0, 0, 0),
+ "blender": (5, 2, 0),
"location": "File > Import > CityJSON (.json) || File > Export > CityJSON (.json)",
"description": "Visualize, edit and export 3D City Models encoded in CityJSON format",
"warning": "",
@@ -21,161 +13,15 @@
}
-class ImportCityJSON(Operator, ImportHelper):
- "Load a CityJSON file"
-
- bl_idname = "cityjson.import_file" # important since its how bpy.ops.import_test.some_data is constructed
- bl_label = "Import CityJSON"
-
- # ImportHelper mixin class uses this
- filename_ext = ".json"
-
- filter_glob: StringProperty(
- default="*.json",
- options={"HIDDEN"},
- maxlen=255, # Max internal buffer length, longer would be clamped.
- )
-
- material_type: EnumProperty(
- name="Materials' type",
- items=(
- (
- "SURFACES",
- "Surfaces",
- "Creates materials based on semantic surface types",
- ),
- (
- "CITY_OBJECTS",
- "City Objects",
- "Creates materials based on the type of city object",
- ),
- ),
- description=("Create materials based on city object or semantic surfaces"),
- )
-
- reuse_materials: BoolProperty(
- name="Reuse materials",
- description="Use common materials according to surface type",
- default=True,
- )
-
- clean_scene: BoolProperty(
- name="Clean scene",
- description="Remove existing objects from the scene before importing",
- default=True,
- )
-
- def execute(self, context):
- """Executes the import process"""
-
- parser = CityJSONParser(
- self.filepath,
- material_type=self.material_type,
- reuse_materials=self.reuse_materials,
- clear_scene=self.clean_scene,
- )
-
- return parser.execute()
-
-
-class ExportCityJSON(Operator, ExportHelper):
- "Export scene as a CityJSON file"
-
- bl_idname = "cityjson.export_file"
- bl_label = "Export CityJSON"
-
- # ExportHelper mixin class uses this
- filename_ext = ".json"
-
- filter_glob: StringProperty(
- default="*.json",
- options={"HIDDEN"},
- maxlen=255, # Max internal buffer length, longer would be clamped.
- )
-
- check_for_duplicates: BoolProperty(
- name="Remove vertex duplicates",
- default=True,
- )
-
- precision: IntProperty(
- name="Precision",
- default=5,
- description="Decimals to check for vertex duplicates",
- min=0,
- max=12,
- )
- # single_lod_switch: BoolProperty(
- # name="Export single LoD",
- # description="Enable to export only a single LoD",
- # default=False,
- # )
-
- # export_single_lod: EnumProperty(
- # name="Select LoD :",
- # items=(('LoD0', "LoD 0",
- # "Export only LoD 0"),
- # ('LoD1', "LoD 1",
- # "Export only LoD 1"),
- # ('LoD2', "LoD 2",
- # "Export only LoD 2"),
- # ),
- # description=(
- # "Select which LoD should be exported"
- # )
- # )
- def execute(self, context):
-
- exporter = CityJSONExporter(
- self.filepath,
- check_for_duplicates=self.check_for_duplicates,
- precision=self.precision,
- )
- return exporter.execute()
-
-
-classes = (
- ImportCityJSON,
- ExportCityJSON,
- prop.Up3dateCityJSONfyProperties,
- operator.Up3dateCityJsonfy,
- ui.Up3datePTgui,
-)
-
-
-def menu_func_export(self, context):
- """Defines the menu item for CityJSON import"""
- self.layout.operator(ExportCityJSON.bl_idname, text="CityJSON (.json)")
-
-
-def menu_func_import(self, context):
- """Defines the menu item for CityJSON export"""
- self.layout.operator(ImportCityJSON.bl_idname, text="CityJSON (.json)")
-
-
-def register():
- """Registers the classes and functions of the addon"""
-
- for cls in classes:
- bpy.utils.register_class(cls)
- bpy.types.Scene.cityjsonfy_properties = bpy.props.PointerProperty(
- type=prop.Up3dateCityJSONfyProperties
- )
- bpy.types.TOPBAR_MT_file_import.append(menu_func_import)
- bpy.types.TOPBAR_MT_file_export.append(menu_func_export)
-
-
-def unregister():
- """Unregisters the classes and functions of the addon"""
-
- bpy.types.TOPBAR_MT_file_import.remove(menu_func_import)
- bpy.types.TOPBAR_MT_file_export.remove(menu_func_export)
+def register() -> None:
+ """Load and register the Blender-dependent add-on implementation."""
+ from . import addon
- for cls in classes:
- bpy.utils.unregister_class(cls)
+ addon.register()
- del bpy.types.Scene.cityjsonfy_properties
+def unregister() -> None:
+ """Unregister the Blender-dependent add-on implementation."""
+ from . import addon
-if __name__ == "__main__":
- register()
+ addon.unregister()
diff --git a/addon.py b/addon.py
new file mode 100644
index 0000000..0dc5375
--- /dev/null
+++ b/addon.py
@@ -0,0 +1,170 @@
+"""Blender-dependent implementation of the Up3date add-on."""
+
+import bpy
+from bpy.props import BoolProperty, EnumProperty, IntProperty, StringProperty
+from bpy.types import Operator
+from bpy_extras.io_utils import ExportHelper, ImportHelper
+
+from .core import operator, prop, ui
+from .core.blender_types import BlenderContext, Menu
+from .core.objects import CityJSONExporter, CityJSONParser
+
+
+class ImportCityJSON(Operator, ImportHelper):
+ "Load a CityJSON file"
+
+ bl_idname = "cityjson.import_file" # important since its how bpy.ops.import_test.some_data is constructed
+ bl_label = "Import CityJSON"
+
+ # ImportHelper mixin class uses this
+ filename_ext = ".json"
+
+ filter_glob: StringProperty(
+ default="*.json",
+ options={"HIDDEN"},
+ maxlen=255, # Max internal buffer length, longer would be clamped.
+ )
+
+ material_type: EnumProperty(
+ name="Materials' type",
+ items=(
+ (
+ "SURFACES",
+ "Surfaces",
+ "Creates materials based on semantic surface types",
+ ),
+ (
+ "CITY_OBJECTS",
+ "City Objects",
+ "Creates materials based on the type of city object",
+ ),
+ ),
+ description=("Create materials based on city object or semantic surfaces"),
+ )
+
+ reuse_materials: BoolProperty(
+ name="Reuse materials",
+ description="Use common materials according to surface type",
+ default=True,
+ )
+
+ clean_scene: BoolProperty(
+ name="Clean scene",
+ description="Remove existing objects from the scene before importing",
+ default=True,
+ )
+
+ def execute(self, context: BlenderContext) -> set[str]:
+ """Executes the import process"""
+
+ parser = CityJSONParser(
+ self.filepath,
+ material_type=self.material_type,
+ reuse_materials=self.reuse_materials,
+ clear_scene=self.clean_scene,
+ )
+
+ return parser.execute()
+
+
+class ExportCityJSON(Operator, ExportHelper):
+ "Export scene as a CityJSON file"
+
+ bl_idname = "cityjson.export_file"
+ bl_label = "Export CityJSON"
+
+ # ExportHelper mixin class uses this
+ filename_ext = ".city.json"
+
+ filter_glob: StringProperty(
+ default="*.city.json",
+ options={"HIDDEN"},
+ maxlen=255, # Max internal buffer length, longer would be clamped.
+ )
+
+ check_for_duplicates: BoolProperty(
+ name="Remove vertex duplicates",
+ default=True,
+ )
+
+ precision: IntProperty(
+ name="Precision",
+ default=5,
+ description="Decimals to check for vertex duplicates",
+ min=0,
+ max=12,
+ )
+ # single_lod_switch: BoolProperty(
+ # name="Export single LoD",
+ # description="Enable to export only a single LoD",
+ # default=False,
+ # )
+
+ # export_single_lod: EnumProperty(
+ # name="Select LoD :",
+ # items=(('LoD0', "LoD 0",
+ # "Export only LoD 0"),
+ # ('LoD1', "LoD 1",
+ # "Export only LoD 1"),
+ # ('LoD2', "LoD 2",
+ # "Export only LoD 2"),
+ # ),
+ # description=(
+ # "Select which LoD should be exported"
+ # )
+ # )
+ def execute(self, context: BlenderContext) -> set[str]:
+
+ exporter = CityJSONExporter(
+ self.filepath,
+ check_for_duplicates=self.check_for_duplicates,
+ precision=self.precision,
+ )
+ return exporter.execute()
+
+
+classes = (
+ ImportCityJSON,
+ ExportCityJSON,
+ prop.Up3dateCityJSONfyProperties,
+ operator.Up3dateCityJsonfy,
+ ui.Up3datePTgui,
+)
+
+
+def menu_func_export(self: Menu, context: BlenderContext) -> None:
+ """Defines the menu item for CityJSON import"""
+ self.layout.operator(ExportCityJSON.bl_idname, text="CityJSON (.json)")
+
+
+def menu_func_import(self: Menu, context: BlenderContext) -> None:
+ """Defines the menu item for CityJSON export"""
+ self.layout.operator(ImportCityJSON.bl_idname, text="CityJSON (.json)")
+
+
+def register() -> None:
+ """Registers the classes and functions of the addon"""
+
+ for cls in classes:
+ bpy.utils.register_class(cls)
+ bpy.types.Scene.cityjsonfy_properties = bpy.props.PointerProperty(
+ type=prop.Up3dateCityJSONfyProperties
+ )
+ bpy.types.TOPBAR_MT_file_import.append(menu_func_import)
+ bpy.types.TOPBAR_MT_file_export.append(menu_func_export)
+
+
+def unregister() -> None:
+ """Unregisters the classes and functions of the addon"""
+
+ bpy.types.TOPBAR_MT_file_import.remove(menu_func_import)
+ bpy.types.TOPBAR_MT_file_export.remove(menu_func_export)
+
+ for cls in classes:
+ bpy.utils.unregister_class(cls)
+
+ del bpy.types.Scene.cityjsonfy_properties
+
+
+if __name__ == "__main__":
+ register()
diff --git a/blender_manifest.toml b/blender_manifest.toml
new file mode 100644
index 0000000..e1e2557
--- /dev/null
+++ b/blender_manifest.toml
@@ -0,0 +1,19 @@
+schema_version = "1.0.0"
+
+id = "up3date"
+version = "0.0.0"
+name = "Up3date"
+tagline = "Visualize, edit and export 3D City Models encoded in CityJSON format"
+maintainer = "Konstantinos Mastorakis"
+type = "add-on"
+
+blender_version_min = "5.2.0"
+
+license = [
+ "SPDX:GPL-3.0-or-later",
+]
+
+tags = ["Import-Export"]
+
+[permissions]
+files = "Import and export CityJSON files from/to disk"
diff --git a/core/blender_types.py b/core/blender_types.py
new file mode 100644
index 0000000..8ba124e
--- /dev/null
+++ b/core/blender_types.py
@@ -0,0 +1,160 @@
+"""Structural types for the subset of Blender's Python API used by Up3date."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, MutableMapping, Sequence
+from typing import Protocol, Self
+
+
+class Vector(Protocol):
+ """Vector-like value exposed by Blender's mesh API."""
+
+ def __getitem__(self, index: int) -> float: ...
+
+ def __iter__(self) -> Iterator[float]: ...
+
+
+class Matrix(Protocol):
+ """Matrix supporting Blender's matrix-vector multiplication."""
+
+ def __matmul__(self, vector: Vector) -> Vector: ...
+
+
+class CustomPropertyOwner(Protocol):
+ def __setitem__(self, key: str, value: object) -> None: ...
+
+
+class BlenderMaterial(CustomPropertyOwner, Protocol):
+ name: str
+ diffuse_color: tuple[float, float, float, float]
+
+ def __getitem__(self, key: str) -> object: ...
+
+ def __setitem__(self, key: str, value: object) -> None: ...
+
+ def get(self, key: str, default: object = None) -> object: ...
+
+
+class MaterialCollection(Protocol):
+ def __bool__(self) -> bool: ...
+
+ def __getitem__(self, index: int) -> BlenderMaterial | None: ...
+
+ def __iter__(self) -> Iterator[BlenderMaterial | None]: ...
+
+ def __len__(self) -> int: ...
+
+ def append(self, material: BlenderMaterial) -> None: ...
+
+
+class BlenderVertex(Protocol):
+ co: Vector
+
+
+class BlenderPolygon(Protocol):
+ index: int
+ material_index: int
+ vertices: Sequence[int]
+
+
+class VertexCollection(Protocol):
+ def __getitem__(self, index: int) -> BlenderVertex: ...
+
+ def __iter__(self) -> Iterator[BlenderVertex]: ...
+
+ def __len__(self) -> int: ...
+
+ def add(self, count: int) -> None: ...
+
+ def foreach_set(self, attribute: str, values: Sequence[object]) -> None: ...
+
+
+class PolygonCollection(Protocol):
+ def __getitem__(self, index: int) -> BlenderPolygon: ...
+
+ def __iter__(self) -> Iterator[BlenderPolygon]: ...
+
+ def __len__(self) -> int: ...
+
+ def add(self, count: int) -> None: ...
+
+ def foreach_set(self, attribute: str, values: Sequence[object]) -> None: ...
+
+
+class LoopCollection(Protocol):
+ def add(self, count: int) -> None: ...
+
+ def foreach_set(self, attribute: str, values: Sequence[object]) -> None: ...
+
+
+class BlenderMesh(Protocol):
+ materials: MaterialCollection
+ vertices: VertexCollection
+ polygons: PolygonCollection
+ loops: LoopCollection
+
+ def update(self) -> None: ...
+
+
+class BlenderObject(CustomPropertyOwner, Protocol):
+ name: str
+ type: str
+ data: BlenderMesh
+ parent: BlenderObject | None
+ location: Sequence[float]
+ matrix_world: Matrix
+ bound_box: Sequence[Sequence[float]]
+
+ def __contains__(self, key: object) -> bool: ...
+
+ def __getitem__(self, key: str) -> object: ...
+
+ def __setitem__(self, key: str, value: object) -> None: ...
+
+ def get(self, key: str, default: object = None) -> object: ...
+
+ def items(self) -> Iterable[tuple[str, object]]: ...
+
+
+class ObjectLinker(Protocol):
+ def link(self, obj: BlenderObject) -> None: ...
+
+
+class CollectionLinker(Protocol):
+ def link(self, collection: BlenderCollection) -> None: ...
+
+
+class BlenderCollection(Protocol):
+ objects: ObjectLinker
+ children: CollectionLinker
+
+
+class Up3dateProperties(Protocol):
+ lod: str
+ feature_type: str
+ geometry_type: str
+
+
+class BlenderScene(Protocol):
+ world: MutableMapping[str, object]
+ collection: BlenderCollection
+ cityjsonfy_properties: Up3dateProperties
+
+
+class BlenderContext(Protocol):
+ scene: BlenderScene
+ selected_objects: Iterable[BlenderObject]
+
+
+class UILayout(Protocol):
+ def label(self, *, text: str) -> None: ...
+
+ def operator(self, operator: str, *, text: str = "") -> object: ...
+
+ def prop(self, data: object, property: str) -> None: ...
+
+ def row(self, *, align: bool = False) -> Self: ...
+
+
+class Menu(Protocol):
+ layout: UILayout
diff --git a/core/material.py b/core/material.py
index f417b5f..ff9a97c 100644
--- a/core/material.py
+++ b/core/material.py
@@ -4,12 +4,20 @@
based on the semantics of the CityJSON file.
"""
-from typing import ClassVar
+from typing import ClassVar, Protocol, cast
import bpy
+from ..models.geomprimitives import GeometryPrimitive, Semantics
+from .blender_types import BlenderMaterial
from .utils import assign_properties, clean_list
+Color = tuple[float, float, float, float]
+
+
+class TypedCityObject(Protocol):
+ type: str
+
class BasicMaterialFactory:
"""A factory that creates a simple material for every city object"""
@@ -20,9 +28,9 @@ class BasicMaterialFactory:
"GroundSurface": (0.507, 0.233, 0.036, 1.0),
}
- default_color = (0, 0, 0, 1)
+ default_color: ClassVar[Color] = (0, 0, 0, 1)
- def get_surface_color(self, surface_type):
+ def get_surface_color(self, surface_type: str) -> Color:
"""Returns the material color of the appropriate surface type"""
if surface_type in self.material_colors:
@@ -30,34 +38,41 @@ def get_surface_color(self, surface_type):
return self.default_color
- def create_material(self, surface):
+ def create_material(self, surface: Semantics) -> BlenderMaterial:
"""Returns a new material based on the semantic surface of the object"""
- mat = bpy.data.materials.new(name=surface["type"])
+ mat = bpy.data.materials.new(name=surface.type)
- assign_properties(mat, surface)
+ assign_properties(mat, surface.to_dict())
- mat.diffuse_color = self.get_surface_color(surface["type"])
+ mat.diffuse_color = self.get_surface_color(surface.type)
return mat
- def get_material(self, surface):
+ def get_material(self, surface: Semantics) -> BlenderMaterial:
"""Returns the material that corresponds to the semantic surface"""
return self.create_material(surface)
- def get_materials(self, geometry=None, **params):
+ def get_materials(
+ self,
+ geometry: GeometryPrimitive | None = None,
+ city_object: TypedCityObject | None = None,
+ ) -> tuple[list[BlenderMaterial], list[int | None]]:
"""Returns the materials and material index list for the given
geometry
"""
- mats = []
- values = []
- if "semantics" in geometry:
- values = geometry["semantics"]["values"]
-
- for surface in geometry["semantics"]["surfaces"]:
+ mats: list[BlenderMaterial] = []
+ values: list[int | None] = []
+ if geometry is None:
+ return mats, values
+ semantics = getattr(geometry, "semantics", None)
+ if semantics is not None:
+ values = cast(list[int | None], semantics.values)
+
+ for surface in semantics.surfaces:
mats.append(self.get_material(surface))
- values = clean_list(values)
+ values = cast(list[int | None], clean_list(values))
return mats, values
@@ -66,17 +81,15 @@ class ReuseMaterialFactory(BasicMaterialFactory):
"""A class that re-uses a material with similar semantics"""
@staticmethod
- def check_material(material, surface):
+ def check_material(material: BlenderMaterial, surface: Semantics) -> bool:
"""Checks if the material can represent the provided surface"""
- if not material.name.startswith(surface["type"]): # noqa: SIM103
+ if not material.name.startswith(surface.type):
return False
- # TODO: Add logic here to check for semantic surface attributes
-
- return True
+ return material.get("type") == surface.type
- def get_material(self, surface):
+ def get_material(self, surface: Semantics) -> BlenderMaterial:
"""Returns the material that corresponds to the semantic surface"""
matches = [m for m in bpy.data.materials if self.check_material(m, surface)]
@@ -102,10 +115,10 @@ class CityObjectTypeMaterialFactory:
"WaterBody": (54 / 255, 197 / 255, 214 / 255, 1.0),
}
- default_color = (0.3, 0.3, 0.3, 1)
+ default_color: ClassVar[Color] = (0.3, 0.3, 0.3, 1)
@staticmethod
- def create_material(name, color):
+ def create_material(name: str, color: Color) -> BlenderMaterial:
"""Returns a new material based on the semantic surface of the object"""
mat = bpy.data.materials.new(name=name)
@@ -113,7 +126,7 @@ def create_material(name, color):
return mat
- def get_type_color(self, object_type):
+ def get_type_color(self, object_type: str) -> Color:
"""Returns the color that corresponds to the provided city object type"""
if object_type in self.type_color:
@@ -121,7 +134,7 @@ def get_type_color(self, object_type):
return self.default_color
- def get_material(self, object_type):
+ def get_material(self, object_type: str) -> BlenderMaterial:
"""Returns the material that corresponds to the provided
object type
"""
@@ -131,9 +144,15 @@ def get_material(self, object_type):
return self.create_material(object_type, self.get_type_color(object_type))
- def get_materials(self, cityobject=None, **params):
+ def get_materials(
+ self,
+ geometry: GeometryPrimitive | None = None,
+ city_object: TypedCityObject | None = None,
+ ) -> tuple[list[BlenderMaterial], list[int | None]]:
"""Returns the materials and material index list for the given
geometry
"""
- return ([self.get_material(cityobject["type"])], [])
+ if city_object is None:
+ return ([], [])
+ return ([self.get_material(city_object.type)], [])
diff --git a/core/objects.py b/core/objects.py
index 59575c0..cc89cf8 100644
--- a/core/objects.py
+++ b/core/objects.py
@@ -3,28 +3,47 @@
import json
import sys
import time
+from collections.abc import Iterable, Sequence
from datetime import UTC, datetime
+from typing import Any, Protocol, cast
import bpy
import idprop
-from ..models.cityjson import CityJSON
+from ..models.city_objects import CITY_OBJECT_TYPES, ExtensionObject, GenericCityObject
+from ..models.cityjson import CityJSONDocument
+from ..models.geomprimitives import (
+ GEOMETRY_PRIMITIVE_TYPES,
+ GeometryPrimitive,
+ GeometrySemantics,
+ geom_primitive_from_dict,
+)
+from ..models.geomtemplates import GeometryInstance
+from .blender_types import (
+ BlenderObject,
+ PolygonCollection,
+ VertexCollection,
+)
from .material import (
BasicMaterialFactory,
CityObjectTypeMaterialFactory,
ReuseMaterialFactory,
+ TypedCityObject,
)
from .utils import (
+ CITYJSON_DOCUMENT_EXTRAS_PROPERTY,
+ CITYJSON_GEOMETRY_PROPERTY,
+ CITYJSON_ID_PROPERTY,
assign_properties,
clean_buffer,
coord_translate_axis_origin,
coord_translate_by_offset,
create_empty_object,
create_mesh_object,
- export_attributes,
export_metadata,
export_parent_child,
export_transformation_parameters,
+ get_cityjson_id,
get_collection,
get_geometry_name,
link_face_semantic_surface,
@@ -35,15 +54,40 @@
)
+class GeometryContainer(Protocol):
+ geometry: list[Any]
+
+
+class ParsedCityObject(TypedCityObject, Protocol):
+ parents: list[str]
+
+ def to_dict(self) -> dict[str, Any]: ...
+
+
+MaterialFactory = (
+ BasicMaterialFactory | ReuseMaterialFactory | CityObjectTypeMaterialFactory
+)
+
+type GeometryModel = GeometryPrimitive | GeometryInstance
+
+
class CityJSONParser:
"""Class that parses a CityJSON file to Blender"""
- def __init__(self, filepath, material_type, reuse_materials=True, clear_scene=True):
+ def __init__(
+ self,
+ filepath: str,
+ material_type: str,
+ reuse_materials: bool = True,
+ clear_scene: bool = True,
+ ) -> None:
self.filepath = filepath
self.clear_scene = clear_scene
- self.data = {}
- self.vertices = []
+ self.data: dict[str, Any] = {}
+ self.document: CityJSONDocument | None = None
+ self.vertices: Sequence[Sequence[float]] = ()
+ self.material_factory: MaterialFactory
if material_type == "SURFACES":
if reuse_materials:
@@ -53,46 +97,48 @@ def __init__(self, filepath, material_type, reuse_materials=True, clear_scene=Tr
else:
self.material_factory = CityObjectTypeMaterialFactory()
- def load_data(self):
+ def load_data(self) -> None:
"""Loads the CityJSON data from the file"""
with open(self.filepath) as json_file:
self.data = json.load(json_file)
+ self.document = CityJSONDocument.from_dict(self.data)
- def prepare_vertices(self):
+ def prepare_vertices(self) -> None:
"""Prepares the vertices by applying any required transformations"""
- vertices = []
+ vertices: list[tuple[float, float, float]] = []
+
+ if self.document is None:
+ raise RuntimeError("CityJSON data must be loaded before preparing vertices")
+
+ transform = self.document.transform
# Checking if coordinates need to be transformed and
# transforming if necessary
- if "transform" not in self.data:
- for vertex in self.data["vertices"]:
- vertices.append(tuple(vertex))
+ if transform is None:
+ for vertex in self.document.vertices:
+ vertices.append((float(vertex[0]), float(vertex[1]), float(vertex[2])))
else:
- trans_param = self.data["transform"]
# Transforming coords to actual real world coords
- for vertex in self.data["vertices"]:
- x = vertex[0] * trans_param["scale"][0] + trans_param["translate"][0]
- y = vertex[1] * trans_param["scale"][1] + trans_param["translate"][1]
- z = vertex[2] * trans_param["scale"][2] + trans_param["translate"][2]
+ x_scale = transform.scale[0] or 1
+ y_scale = transform.scale[1] or 1
+ z_scale = transform.scale[2] or 1
+ for vertex in self.document.vertices:
+ x = vertex[0] * x_scale + transform.translate[0]
+ y = vertex[1] * y_scale + transform.translate[1]
+ z = vertex[2] * z_scale + transform.translate[2]
vertices.append((x, y, z))
# Creating transform properties
bpy.context.scene.world["transformed"] = True
- bpy.context.scene.world["transform.X_scale"] = trans_param["scale"][0]
- bpy.context.scene.world["transform.Y_scale"] = trans_param["scale"][1]
- bpy.context.scene.world["transform.Z_scale"] = trans_param["scale"][2]
-
- bpy.context.scene.world["transform.X_translate"] = trans_param["translate"][
- 0
- ]
- bpy.context.scene.world["transform.Y_translate"] = trans_param["translate"][
- 1
- ]
- bpy.context.scene.world["transform.Z_translate"] = trans_param["translate"][
- 2
- ]
+ bpy.context.scene.world["transform.X_scale"] = transform.scale[0]
+ bpy.context.scene.world["transform.Y_scale"] = transform.scale[1]
+ bpy.context.scene.world["transform.Z_scale"] = transform.scale[2]
+
+ bpy.context.scene.world["transform.X_translate"] = transform.translate[0]
+ bpy.context.scene.world["transform.Y_translate"] = transform.translate[1]
+ bpy.context.scene.world["transform.Z_translate"] = transform.translate[2]
if "Axis_Origin_X_translation" in bpy.context.scene.world:
offx = -bpy.context.scene.world["Axis_Origin_X_translation"]
@@ -109,32 +155,35 @@ def prepare_vertices(self):
# Updating vertices with new translated vertices
self.vertices = translation[0]
- def parse_geometry(self, theid: str, obj: dict, geom, index):
+ def parse_geometry(
+ self, theid: str, obj: ParsedCityObject, geom: GeometryModel, index: int
+ ) -> BlenderObject:
"""Returns a mesh object for the provided geometry"""
+ if geom.type not in {"MultiSurface", "CompositeSurface", "Solid"}:
+ geom_obj = create_empty_object(get_geometry_name(theid, geom, index))
+ geom_obj[CITYJSON_GEOMETRY_PROPERTY] = json.dumps(geom.to_dict())
+ geom_obj["type"] = geom.type
+ if hasattr(geom, "lod"):
+ geom_obj["lod"] = str(geom.lod)
+ return geom_obj
+
bound = []
# Checking how nested the geometry is i.e what kind of 3D
# geometry it contains
- if geom["type"] == "MultiSurface" or geom["type"] == "CompositeSurface":
- for face in geom["boundaries"]:
+ if geom.type in ("MultiSurface", "CompositeSurface"):
+ for face in geom.boundaries:
if face:
bound.append(tuple(face[0]))
- elif geom["type"] == "Solid":
- for shell in geom["boundaries"]:
+ elif geom.type == "Solid":
+ for shell in geom.boundaries:
for face in shell:
if face:
bound.append(tuple(face[0]))
- elif geom["type"] == "MultiSolid":
- for solid in geom["boundaries"]:
- for shell in solid:
- for face in shell:
- if face:
- bound.append(tuple(face[0]))
-
temp_vertices, temp_bound = clean_buffer(self.vertices, bound)
mats, values = self.material_factory.get_materials(
- cityobject=obj, geometry=geom
+ city_object=obj, geometry=geom
)
geom_obj = create_mesh_object(
@@ -145,14 +194,12 @@ def parse_geometry(self, theid: str, obj: dict, geom, index):
values,
)
- if "lod" in geom:
- geom_obj["lod"] = int(geom["lod"])
-
- geom_obj["type"] = geom["type"]
+ geom_obj["lod"] = str(geom.lod)
+ geom_obj["type"] = geom.type
return geom_obj
- def execute(self):
+ def execute(self) -> set[str]:
"""Execute the import process"""
if self.clear_scene:
@@ -164,31 +211,51 @@ def execute(self):
self.prepare_vertices()
+ if self.document is None:
+ raise RuntimeError("CityJSON data was not loaded")
+ doc = self.document
+
+ document_extras: dict[str, Any] = {}
+ if doc.extensions:
+ document_extras["extensions"] = doc.extensions
+ if doc.appearance is not None:
+ document_extras["appearance"] = doc.appearance.to_dict()
+ if doc.geometry_templates is not None:
+ document_extras["geometry-templates"] = doc.geometry_templates.to_dict()
+ if document_extras:
+ bpy.context.scene.world[CITYJSON_DOCUMENT_EXTRAS_PROPERTY] = json.dumps(
+ document_extras
+ )
+
# Storing the reference system
- metadata = self.data.get("metadata", {})
- if "referenceSystem" in metadata:
- bpy.context.scene.world["CRS"] = metadata["referenceSystem"]
+ metadata = doc.metadata
+ if metadata is not None and metadata.reference_system is not None:
+ bpy.context.scene.world["CRS"] = metadata.reference_system
new_objects = []
- cityobjs = {}
+ city_objects = {}
- progress_max = len(self.data["CityObjects"])
+ progress_max = len(doc.city_objects)
progress = 0
start_import = time.time()
# Creating empty meshes for every CityObjects and linking its
# geometries as children-meshes
- for progress, (objid, obj) in enumerate(
- self.data["CityObjects"].items(), start=1
+ for progress, (objid, obj_value) in enumerate(
+ doc.city_objects.items(), start=1
):
- cityobject = create_empty_object(objid)
- cityobject = assign_properties(cityobject, obj)
- new_objects.append(cityobject)
- cityobjs[objid] = cityobject
-
- for geometry_index, geometry in enumerate(obj["geometry"]):
+ obj = cast(ParsedCityObject, obj_value)
+ city_object = create_empty_object(objid)
+ city_object[CITYJSON_ID_PROPERTY] = objid
+ city_object = assign_properties(city_object, obj.to_dict())
+ new_objects.append(city_object)
+ city_objects[objid] = city_object
+
+ geometry_owner = cast(GeometryContainer, obj_value)
+ for geometry_index, geometry in enumerate(geometry_owner.geometry):
geom_obj = self.parse_geometry(objid, obj, geometry, geometry_index)
- geom_obj.parent = cityobject
+ geom_obj[CITYJSON_ID_PROPERTY] = objid
+ geom_obj.parent = city_object
new_objects.append(geom_obj)
percentage = progress / progress_max * 100
@@ -201,12 +268,13 @@ def execute(self):
# Assign child building parts to parent buildings.
print("\nBuilding hierarchy...")
- for progress, (objid, obj) in enumerate(
- self.data["CityObjects"].items(), start=1
+ for progress, (objid, obj_value) in enumerate(
+ doc.city_objects.items(), start=1
):
- if "parents" in obj:
- parent_id = obj["parents"][0]
- cityobjs[objid].parent = cityobjs[parent_id]
+ obj = cast(ParsedCityObject, obj_value)
+ if obj.parents:
+ parent_id = obj.parents[0]
+ city_objects[objid].parent = city_objects[parent_id]
percentage = progress / progress_max * 100
print(f"Building hierarchy: {percentage:.1f}% completed", end="\r")
@@ -242,225 +310,260 @@ def execute(self):
class CityJSONExporter:
- def __init__(self, filepath, check_for_duplicates=True, precision=3):
+ def __init__(
+ self,
+ filepath: str,
+ check_for_duplicates: bool = True,
+ precision: int = 3,
+ ) -> None:
self.filepath = filepath
self.check_for_duplicates = check_for_duplicates
self.precision = precision
@staticmethod
- def initialize_dictionary() -> CityJSON:
- return {
- "type": "CityJSON",
- "version": "1.0",
- # "extensions": {},
- "metadata": {},
- "CityObjects": {},
- "vertices": [],
- # "appearance":{}
- }
+ def initialize_document() -> CityJSONDocument:
+ doc = CityJSONDocument()
+ stored_extras = bpy.context.scene.world.get(CITYJSON_DOCUMENT_EXTRAS_PROPERTY)
+ if not isinstance(stored_extras, str):
+ return doc
+
+ extras = json.loads(stored_extras)
+ restored = CityJSONDocument.from_dict(
+ {
+ "type": "CityJSON",
+ "version": "2.0",
+ "CityObjects": {},
+ "vertices": [],
+ **extras,
+ }
+ )
+ doc.appearance = restored.appearance
+ doc.extensions = restored.extensions
+ doc.geometry_templates = restored.geometry_templates
+ return doc
@staticmethod
- def get_custom_properties(city_object, init_json, city_object_id):
- """Creates the required structure according to CityJSON and writes all the object's custom properties (aka attributes)"""
- init_json["CityObjects"].setdefault(city_object_id, {})
- init_json["CityObjects"][city_object_id].setdefault("geometry", [])
- cp = city_object.items()
- for prop in cp:
- # When a new empty object is added by user, Blender assigns some built in properties at the first index of the property list.
- # With this it is bypassed and continues to the actual properties of the object
- if prop[0] == "_RNA_UI":
+ def get_custom_properties(
+ city_object: BlenderObject, doc: CityJSONDocument, city_object_id: str
+ ) -> None:
+ """Creates a typed CityObject in doc and populates all its attributes from Blender custom properties."""
+ # Collect all custom properties first so we know the type before constructing
+ co_type = "GenericCityObject"
+ props: list[tuple[list[str], Any]] = []
+ for key, val in city_object.items():
+ if key in {
+ "_RNA_UI",
+ CITYJSON_ID_PROPERTY,
+ CITYJSON_GEOMETRY_PROPERTY,
+ }:
continue
- # Upon import into Blender the for every level deeper an attribute is nested the more a "." is used in the string between the 2 attributes' names
- # So to store it back to the original form the concatenated string must be split.
- # Split is the list containing the original attributes names.
- split = prop[0].split(".")
- # Check if the attribute is IDPropertyArray and convert to python list type because JSON encoder cannot handle type IDPropertyArray.
- if isinstance(prop[1], idprop.types.IDPropertyArray):
- attribute = prop[1].to_list()
+ if isinstance(val, idprop.types.IDPropertyArray):
+ val = val.to_list()
+ split = key.split(".")
+ if split[0] == "type" and isinstance(val, str):
+ co_type = val
else:
- attribute = prop[1]
- export_attributes(split, init_json, city_object_id, attribute)
+ props.append((split, val))
+
+ # Preserve any geometry already appended by a preceding MESH object
+ existing = doc.city_objects.get(city_object_id)
+ existing_geometry = (
+ existing.geometry
+ if (existing is not None and hasattr(existing, "geometry"))
+ else []
+ )
- @staticmethod
- def create_mesh_structure(city_object, objid, init_json):
- "Prepares the structure within the empty mesh for storing the geometries, stored the lod and accesses the vertices and faces of the geometry within Blender"
- # Create geometry key within the empty object for storing the LoD(s)
- city_object_id = objid.split(" ")[2]
- init_json["CityObjects"].setdefault(city_object_id, {})
- init_json["CityObjects"][city_object_id].setdefault("geometry", [])
- # Check if the user has assigned the custom properties 'lod' and 'type' correctly
- if "lod" in city_object and (
- type(city_object["lod"]) == float or type(city_object["lod"]) == int
- ):
- if "type" in city_object and (
- city_object["type"] == "MultiSurface"
- or city_object["type"] == "CompositeSurface"
- or city_object["type"] == "Solid"
- ):
- # Check if object has materials (in Blender) i.e semantics in real life and if yes create the extra keys (within_geometry) to store it.
- # Otherwise just create the rest of the tags
- if city_object.data.materials:
- init_json["CityObjects"][city_object_id]["geometry"].append(
- {
- "type": city_object["type"],
- "boundaries": [],
- "semantics": {"surfaces": [], "values": [[]]},
- "texture": {},
- "lod": city_object["lod"],
- }
- )
- else:
- init_json["CityObjects"][city_object_id]["geometry"].append(
- {
- "type": city_object["type"],
- "boundaries": [],
- "lod": city_object["lod"],
- }
- )
- else:
- print(
- "You either forgot to add `type` as a custom property of the geometry, ",
- city_object.name,
- ", or 'type' is not `MultiSurface`,`CompositeSurface` or `Solid`",
- )
- sys.exit(None)
+ if co_type.startswith("+"):
+ co = ExtensionObject(type=co_type)
else:
+ city_object_class = CITY_OBJECT_TYPES.get(co_type, GenericCityObject)
+ co = city_object_class()
+ if hasattr(co, "geometry"):
+ co.geometry = existing_geometry
+ doc.city_objects[city_object_id] = co
+
+ # Apply collected properties to the typed CityObject
+ for split, attribute in props:
+ if split[0] == "attributes":
+ target = co.attributes
+ for part in split[1:-1]:
+ target = target.setdefault(part, {})
+ target[split[-1]] = attribute
+ elif split[0] == "members" and hasattr(co, "members"):
+ if isinstance(attribute, list):
+ co.members = attribute
+ else:
+ co.members.append(attribute)
+ elif split[0] == "geographicalExtent":
+ co.geographical_extent = attribute
+ elif split[0] == "parents" and hasattr(co, "parents"):
+ if isinstance(attribute, list):
+ co.parents = attribute
+ elif split[0] == "children" and hasattr(co, "children"):
+ if isinstance(attribute, list):
+ co.children = attribute
+
+ @staticmethod
+ def create_mesh_structure(
+ city_object: BlenderObject, objid: str, doc: CityJSONDocument
+ ) -> tuple[str, VertexCollection, PolygonCollection]:
+ """Creates a typed geometry object and attaches it to the correct CityObject in doc."""
+ stored_cityjson_id = city_object.get(CITYJSON_ID_PROPERTY)
+ city_object_id = (
+ stored_cityjson_id
+ if isinstance(stored_cityjson_id, str)
+ else objid.split(" ", maxsplit=2)[2]
+ )
+
+ # Validate lod custom property
+ if "lod" not in city_object or not isinstance(city_object["lod"], str):
print(
"You either forgot to add `lod` as a custom property of the geometry, ",
city_object.name,
- ", or 'lod' is not a number",
+ ", or 'lod' is not a string",
+ )
+ sys.exit(None)
+
+ # Validate type custom property
+ co_type = city_object.get("type", "")
+ if co_type not in ("MultiSurface", "CompositeSurface", "Solid"):
+ print(
+ "You either forgot to add `type` as a custom property of the geometry, ",
+ city_object.name,
+ ", or 'type' is not `MultiSurface`, `CompositeSurface` or `Solid`",
)
sys.exit(None)
- # Accessing object's vertices
- object_verts = city_object.data.vertices
- # Accessing object's faces
- object_faces = city_object.data.polygons
+ geometry_class = GEOMETRY_PRIMITIVE_TYPES[co_type]
+ geom = geometry_class(lod=city_object["lod"])
+ if city_object.data.materials:
+ geom.semantics = GeometrySemantics(surfaces=[], values=[[]])
+
+ # Create a GenericCityObject placeholder if the EMPTY hasn't been processed yet
+ if city_object_id not in doc.city_objects:
+ doc.city_objects[city_object_id] = GenericCityObject()
- return city_object_id, object_verts, object_faces
+ city_object_model = cast(GeometryContainer, doc.city_objects[city_object_id])
+ city_object_model.geometry.append(geom)
+
+ return city_object_id, city_object.data.vertices, city_object.data.polygons
@staticmethod
def export_geometry_and_semantics(
- city_object,
- init_json,
- city_object_id,
- object_faces,
- object_verts,
- vertices,
- cj_next_index,
- ):
- # Index in the geometry list that the new geometry needs to be stored.
- index = len(init_json["CityObjects"][city_object_id]["geometry"]) - 1
+ city_object: BlenderObject,
+ doc: CityJSONDocument,
+ city_object_id: str,
+ object_faces: PolygonCollection,
+ object_verts: VertexCollection,
+ vertex_indices: dict[tuple[float, float, float], int],
+ cj_next_index: int,
+ ) -> int:
+ # Index in the geometry list that the new geometry needs to be stored
+ city_object_model = cast(GeometryContainer, doc.city_objects[city_object_id])
+ index = len(city_object_model.geometry) - 1
+ geom = city_object_model.geometry[index]
# Create semantic surfaces
semantic_surfaces = store_semantic_surfaces(
- init_json, city_object, index, city_object_id
+ doc, city_object, index, city_object_id
)
- if (
- city_object["type"] == "MultiSurface"
- or city_object["type"] == "CompositeSurface"
- ):
- # Browsing through faces and their vertices of every object.
+
+ if city_object["type"] in ("MultiSurface", "CompositeSurface"):
for face in object_faces:
- init_json["CityObjects"][city_object_id]["geometry"][index][
- "boundaries"
- ].append([[]])
+ geom.boundaries.append([[]])
for i in range(len(object_faces[face.index].vertices)):
original_index = object_faces[face.index].vertices[i]
get_vertex = object_verts[original_index]
- # Write vertex to CityJSON at this point so the mesh_object.world_matrix (aka transformation matrix) is always the
- # correct one. With the previous way it would take the last object's transformation matrix and would potentially lead to wrong final
- # coordinate to be exported.
- write_vertices_to_cityjson(city_object, get_vertex.co, init_json)
- vertices.append(get_vertex.co)
- init_json["CityObjects"][city_object_id]["geometry"][index][
- "boundaries"
- ][face.index][0].append(cj_next_index)
+ # Write vertex to CityJSON here so the world_matrix is always the
+ # correct one for each object.
+ write_vertices_to_cityjson(city_object, get_vertex.co, doc)
+ vertex_key = (
+ float(get_vertex.co[0]),
+ float(get_vertex.co[1]),
+ float(get_vertex.co[2]),
+ )
+ vertex_indices.setdefault(vertex_key, cj_next_index)
+ geom.boundaries[face.index][0].append(cj_next_index)
cj_next_index += 1
- # In case the object has semantics they are accordingly stored as well
link_face_semantic_surface(
- init_json,
- city_object,
- index,
- city_object_id,
- semantic_surfaces,
- face,
+ doc, city_object, index, city_object_id, semantic_surfaces, face
)
if city_object["type"] == "Solid":
- init_json["CityObjects"][city_object_id]["geometry"][index][
- "boundaries"
- ].append([])
+ geom.boundaries.append([])
for face in object_faces:
- init_json["CityObjects"][city_object_id]["geometry"][index][
- "boundaries"
- ][0].append([[]])
+ geom.boundaries[0].append([[]])
for i in range(len(object_faces[face.index].vertices)):
original_index = object_faces[face.index].vertices[i]
get_vertex = object_verts[original_index]
- if get_vertex.co in vertices:
- vert_index = vertices.index(get_vertex.co)
- init_json["CityObjects"][city_object_id]["geometry"][index][
- "boundaries"
- ][0][face.index][0].append(vert_index)
+ vertex_key = (
+ float(get_vertex.co[0]),
+ float(get_vertex.co[1]),
+ float(get_vertex.co[2]),
+ )
+ if vertex_key in vertex_indices:
+ vert_index = vertex_indices[vertex_key]
+ geom.boundaries[0][face.index][0].append(vert_index)
else:
- write_vertices_to_cityjson(
- city_object, get_vertex.co, init_json
- )
- vertices.append(get_vertex.co)
- init_json["CityObjects"][city_object_id]["geometry"][index][
- "boundaries"
- ][0][face.index][0].append(cj_next_index)
+ write_vertices_to_cityjson(city_object, get_vertex.co, doc)
+ vertex_indices[vertex_key] = cj_next_index
+ geom.boundaries[0][face.index][0].append(cj_next_index)
cj_next_index += 1
- # In case the object has semantics they are accordingly stored as well
+
link_face_semantic_surface(
- init_json,
- city_object,
- index,
- city_object_id,
- semantic_surfaces,
- face,
+ doc, city_object, index, city_object_id, semantic_surfaces, face
)
+
return cj_next_index
- def execute(self):
+ def execute(self) -> set[str]:
start = time.time()
print("\nExporting Blender scene into CityJSON file...")
- init_json: CityJSON = self.initialize_dictionary()
+ doc = self.initialize_document()
progress_max = len(bpy.data.objects)
cj_next_index = 0
- verts = []
-
- for progress, city_object in enumerate(bpy.data.objects, start=1):
- objid = city_object.name
+ vertex_indices: dict[tuple[float, float, float], int] = {}
+
+ objects = cast(Iterable[BlenderObject], bpy.data.objects)
+ for progress, city_object in enumerate(objects, start=1):
+ objid = get_cityjson_id(city_object)
+
+ if CITYJSON_GEOMETRY_PROPERTY in city_object:
+ serialized_geometry = city_object[CITYJSON_GEOMETRY_PROPERTY]
+ if not isinstance(serialized_geometry, str):
+ raise TypeError("Preserved CityJSON geometry must be a JSON string")
+ geometry_data = json.loads(serialized_geometry)
+ geometry: GeometryModel
+ if geometry_data.get("type") == "GeometryInstance":
+ geometry = GeometryInstance.from_dict(geometry_data)
+ else:
+ geometry = geom_primitive_from_dict(geometry_data)
+ if objid not in doc.city_objects:
+ doc.city_objects[objid] = GenericCityObject()
+ city_object_model = cast(GeometryContainer, doc.city_objects[objid])
+ city_object_model.geometry.append(geometry)
# Empty objects contain the CityJSON attributes.
- if city_object.type == "EMPTY":
- self.get_custom_properties(city_object, init_json, objid)
+ elif city_object.type == "EMPTY":
+ self.get_custom_properties(city_object, doc, objid)
# Mesh objects contain the actual CityJSON geometries.
elif city_object.type == "MESH":
- (
- city_object_id,
- object_verts,
- object_faces,
- ) = self.create_mesh_structure(
- city_object,
- objid,
- init_json,
+ city_object_id, object_verts, object_faces = self.create_mesh_structure(
+ city_object, objid, doc
)
cj_next_index = self.export_geometry_and_semantics(
city_object,
- init_json,
+ doc,
city_object_id,
object_faces,
object_verts,
- verts,
+ vertex_indices,
cj_next_index,
)
@@ -472,15 +575,14 @@ def execute(self):
)
if self.check_for_duplicates:
- remove_vertex_duplicates(init_json, self.precision)
- export_parent_child(init_json)
- export_transformation_parameters(init_json)
- export_metadata(init_json)
+ remove_vertex_duplicates(doc, self.precision)
+ export_parent_child(doc)
+ export_transformation_parameters(doc)
+ export_metadata(doc)
print("Writing to CityJSON file...")
- # Writing CityJSON file
with open(self.filepath, "w", encoding="utf-8") as f:
- json.dump(init_json, f, ensure_ascii=False)
+ json.dump(doc.to_dict(), f, ensure_ascii=False)
end = time.time()
timestamp = datetime.now(UTC)
@@ -490,7 +592,6 @@ def execute(self):
+ str(self.filepath)
+ "'.",
)
- # print("\nBlender scene successfully exported to CityJSON at '"+str(self.filepath)+"'.")
print("\nTotal exporting time: ", round(end - start, 2), "s")
return {"FINISHED"}
diff --git a/core/operator.py b/core/operator.py
index b833114..cf0115c 100644
--- a/core/operator.py
+++ b/core/operator.py
@@ -1,22 +1,19 @@
import bpy
+from .blender_types import BlenderContext
+
class Up3dateCityJsonfy(bpy.types.Operator):
bl_idname = "cityjson.cityjsonfy"
bl_label = "Convert to cityjson"
bl_context = "scene"
- def execute(self, context):
- scene = bpy.context.scene
+ def execute(self, context: BlenderContext) -> set[str]:
+ scene = context.scene
props = scene.cityjsonfy_properties
- # define properties
- lod_fullversion = props.lod
- if props.lod_version != 0:
- lod_fullversion = round(props.lod + (props.lod_version / 10), 1)
-
# loop through selected objects
- for geom_obj in bpy.context.selected_objects:
+ for geom_obj in context.selected_objects:
cityjson_id = geom_obj.name
geom_location = geom_obj.location
@@ -26,7 +23,7 @@ def execute(self, context):
cityjson_object.location = geom_location
# set names and attributes
- geom_obj.name = f"{props.lod}: [LOD{lod_fullversion}] {cityjson_id}"
+ geom_obj.name = f"{props.lod}: [LOD{props.lod}] {cityjson_id}"
geom_obj["type"] = props.geometry_type
geom_obj["lod"] = props.lod
cityjson_object.name = cityjson_id
diff --git a/core/prop.py b/core/prop.py
index ddf1fea..fd46008 100644
--- a/core/prop.py
+++ b/core/prop.py
@@ -2,8 +2,7 @@
class Up3dateCityJSONfyProperties(bpy.types.PropertyGroup):
- lod: bpy.props.IntProperty(name="LOD", default=2)
- lod_version: bpy.props.IntProperty(name="LODSubversion", default=0)
+ lod: bpy.props.StringProperty(name="LOD", default="2")
feature_type: bpy.props.StringProperty(
name="feature_type",
default="Building",
diff --git a/core/ui.py b/core/ui.py
index ca273f2..0cc7948 100644
--- a/core/ui.py
+++ b/core/ui.py
@@ -1,5 +1,7 @@
import bpy
+from .blender_types import BlenderContext
+
class Up3datePTgui(bpy.types.Panel):
"""Creates a Panel in the scene context of properties editor"""
@@ -10,7 +12,7 @@ class Up3datePTgui(bpy.types.Panel):
bl_region_type = "WINDOW"
bl_context = "scene"
- def draw(self, context):
+ def draw(self, context: BlenderContext) -> None:
layout = self.layout
scene = context.scene
@@ -20,8 +22,6 @@ def draw(self, context):
row = layout.row(align=True)
row.prop(props, "lod")
row = layout.row()
- row.prop(props, "lod_version")
- row = layout.row()
row.prop(props, "feature_type")
row = layout.row()
row.prop(props, "geometry_type")
diff --git a/core/utils.py b/core/utils.py
index eea3d71..63c4d13 100644
--- a/core/utils.py
+++ b/core/utils.py
@@ -1,30 +1,68 @@
"""Blender CityJSON plugin utils module
-This modules provides utitily methods for the importing/exporting
+This modules provides utility methods for the importing/exporting
processing of CityJSON files
"""
+from collections.abc import Sequence
+from typing import Any, Protocol, cast
+
import bpy
+from ..models.cityjson import CityJSONDocument, Metadata, Transform
+from ..models.geomprimitives import Semantics
+from .blender_types import (
+ BlenderCollection,
+ BlenderMaterial,
+ BlenderObject,
+ BlenderPolygon,
+ CustomPropertyOwner,
+ Vector,
+)
+
+
+class GeometryOwner(Protocol):
+ geometry: list[Any]
+
+
+CITYJSON_ID_PROPERTY = "cityjson_id"
+CITYJSON_GEOMETRY_PROPERTY = "cityjson_geometry"
+CITYJSON_DOCUMENT_EXTRAS_PROPERTY = "cityjson_document_extras"
+
+
+def blender_safe_name(name: str) -> str:
+ """Avoid numeric dot suffixes that Blender parses as duplicate counters."""
+ prefix, separator, suffix = name.rpartition(".")
+ if separator and suffix.isdigit():
+ return f"{prefix}_{suffix}"
+ return name
+
+
+def get_cityjson_id(city_object: BlenderObject) -> str:
+ """Return the preserved CityJSON identifier, falling back to the Blender name."""
+ cityjson_id = city_object.get(CITYJSON_ID_PROPERTY)
+ return cityjson_id if isinstance(cityjson_id, str) else city_object.name
+
+
########## Importer functions ##########
-def remove_scene_objects():
+def remove_scene_objects() -> None:
"""Clears the scenes of any objects and removes world's custom properties
and collections"""
# Delete world custom properties
if bpy.context.scene.world.keys():
for custom_property in list(bpy.context.scene.world.keys()):
del bpy.context.scene.world[custom_property]
- # Deleting previous objects every time a new CityJSON file is imported
- bpy.ops.object.select_all(action="SELECT")
- bpy.ops.object.delete()
+ # Remove all objects without relying on operator context (VIEW_3D not guaranteed)
+ for obj in list(bpy.data.objects):
+ bpy.data.objects.remove(obj, do_unlink=True)
# Deleting previously existing collections
- for collection in bpy.data.collections:
+ for collection in list(bpy.data.collections):
bpy.data.collections.remove(collection)
-def clean_list(values):
+def clean_list(values: list[Any]) -> list[Any]:
"""Creates a list of non list in case lists nested in lists exist"""
while isinstance(values[0], list):
@@ -33,7 +71,9 @@ def clean_list(values):
return values
-def assign_properties(obj, props, prefix=None):
+def assign_properties[PropertyOwner: CustomPropertyOwner](
+ obj: PropertyOwner, props: dict[str, Any], prefix: list[str] | None = None
+) -> PropertyOwner:
"""Assigns the custom properties to obj based on the props"""
if prefix is None:
@@ -52,7 +92,9 @@ def assign_properties(obj, props, prefix=None):
return obj
-def coord_translate_axis_origin(vertices):
+def coord_translate_axis_origin(
+ vertices: Sequence[Sequence[float]],
+) -> tuple[tuple[tuple[float, float, float], ...], float, float, float]:
"""Translates the vertices to the origin (0, 0, 0)"""
# Finding minimum value of x,y,z
minx = min(i[0] for i in vertices)
@@ -62,7 +104,9 @@ def coord_translate_axis_origin(vertices):
return coord_translate_by_offset(vertices, minx, miny, minz)
-def coord_translate_by_offset(vertices, offx, offy, offz):
+def coord_translate_by_offset(
+ vertices: Sequence[Sequence[float]], offx: float, offy: float, offz: float
+) -> tuple[tuple[tuple[float, float, float], ...], float, float, float]:
"""Translates the vertices by minx, miny and minz"""
# Calculating new coordinates
translated_x = [i[0] - offx for i in vertices]
@@ -72,7 +116,9 @@ def coord_translate_by_offset(vertices, offx, offy, offz):
return (tuple(zip(translated_x, translated_y, translated_z)), offx, offy, offz)
-def original_coordinates(vertices, minx, miny, minz):
+def original_coordinates(
+ vertices: Sequence[Sequence[float]], minx: float, miny: float, minz: float
+) -> tuple[tuple[float, float, float], ...]:
"""Translates the vertices from origin to original"""
# Calculating original coordinates
original_x = [i[0] + minx for i in vertices]
@@ -82,8 +128,10 @@ def original_coordinates(vertices, minx, miny, minz):
return tuple(zip(original_x, original_y, original_z))
-def clean_buffer(vertices, bounds):
- """Cleans the[]ces index from unused vertices3"""
+def clean_buffer(
+ vertices: Sequence[Any], bounds: Sequence[Sequence[int]]
+) -> tuple[list[Any], list[tuple[int, ...]]]:
+ """Cleans the vertex index buffer from unused vertices"""
new_bounds = []
new_vertices = []
@@ -101,31 +149,34 @@ def clean_buffer(vertices, bounds):
return new_vertices, new_bounds
-def get_geometry_name(objid, geom, index):
+def get_geometry_name(objid: str, geom: Any, index: int) -> str:
"""Returns the name of the provided geometry"""
- if "lod" in geom:
- return "{index}: [LoD{lod}] {name}".format(
- name=objid, lod=geom["lod"], index=index
- )
- else:
+ if geom.type == "GeometryInstance":
return f"{index}: [GeometryInstance] {objid}"
+ return f"{index}: [LoD{geom.lod}] {objid}"
-def create_empty_object(name):
+def create_empty_object(name: str) -> BlenderObject:
"""Returns an empty blender object"""
- new_object = bpy.data.objects.new(name, None)
+ new_object = bpy.data.objects.new(blender_safe_name(name), None)
return new_object
-def create_mesh_object(name, vertices, faces, materials: list, material_indices: list):
+def create_mesh_object(
+ name: str,
+ vertices: Sequence[Sequence[float]],
+ faces: Sequence[Sequence[int]],
+ materials: Sequence[BlenderMaterial],
+ material_indices: Sequence[int | None],
+) -> BlenderObject:
"""Returns a mesh blender object"""
mesh_data = None
if faces:
- mesh_data = bpy.data.meshes.new(name)
+ mesh_data = bpy.data.meshes.new(blender_safe_name(name))
for material in materials:
mesh_data.materials.append(material)
@@ -150,7 +201,14 @@ def create_mesh_object(name, vertices, faces, materials: list, material_indices:
mesh_data.polygons.foreach_set("loop_start", loop_starts)
mesh_data.polygons.foreach_set("loop_total", loop_totals)
if len(material_indices) == len(faces):
- mesh_data.polygons.foreach_set("material_index", material_indices)
+ safe_material_indices = [
+ material_index
+ if isinstance(material_index, int)
+ and 0 <= material_index <