Skip to content

tudelft3d/cityjson-versioning-prototype

main
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

CityJSON versioning prototype

A prototype implementation of interaction with versioned CityJSON files.

This tool implements versioning as initially proposed in Vitalis et al, 2019.

Requirements

  • Python 3 with virtualenv

Installation

Clone this repository and install Python 3 with virtualenv.

To install the script and necessary dependencies:

virtualenv venv
. venv/bin/activate
pip install --editable .

Then you can use the application by calling cjv.

Usage

General syntax is:

cjv versionedCityJson.json <command> [<args>]

Instead of versionedCityJson.json you can just type init to start with an empty file (useful in combination with the commit command to create a versioned CityJSON).

Call cjv with no arguments to list all commands. Help for an individual command is available with:

cjv <command_name> --help

The available commands are (a ref can be a version, branch or tag):

log

Shows the history of the project starting from a ref (default is master):

cjv vCityJson.json log [<ref>]

You may use the --graph option to show the history as a graph.

checkout

Extracts a regular CityJSON from a specific version:

cjv vCityJson.json checkout <ref> <output.json>

diff

Shows the changes between two refs:

cjv vCityJson.json diff <new_ref> <old_ref>

commit

Adds a new version from a CityJSON (input.json) with base_ref as parent:

cjv vCityJson.json commit <input.json> [<base_ref>] [-a <author>] [-m <message>] [-o <output.json>]

If a base_ref is not provided, then the master branch is implied.

Available options:

  • -a or --author: name of the commit's author (if not provided, user will be prompted),
  • -m or --message: description of the commit's changes (if not provided user will be prompted),
  • -o or --output: the output filename (if not provided the original versioned CityJSON file will be written)

branch

Creates a branch at a given base_ref (default is master):

cjv vCityJson.json branch <branch_name> [<base_ref>]

or deletes a branch using the -d or --delete flag:

cjv vCityJson.json branch -d <branch_name>

merge

Merges source_ref to dest_ref:

cjv vCityJson.json merge <source_ref> <dest_ref>

Normally you'd use branches for refs.

rehash

Converts all city object and version ids to hash (SHA-1):

cjv vCityJson.json rehash <output.json>

Examples

You can create a new versioned CityJSON using init and commit:

cjv init commit input_file.json master -a "John Doe" -m "Initial commit" -o new_vcityjson.json

You can show the log of master branch:

cjv Examples/buildingBeforeAndAfter.json log master

You can checkout a version to a regular CityJSON as follows:

cjv Examples/buildingBeforeAndAfter.json checkout v30 buildingAtVersion30.json

Tutorial

Let's do this together. We have an example dataset from Rotterdam Delfshaven.

  1. Create a versioned CityJSON file:

    cjv init commit Examples/rotterdam/initial.json -m "Initial commit" -o rotterdam.json
    
  2. Create a new branch called test-branch:

    cjv rotterdam.json branch test-branch
    
  3. Add the version with the moved roof in master:

    cjv rotterdam.json commit Examples/rotterdam/inital_moved_roof.json -m "Move a building's roof"
    
  4. Add the version with the deleted building in test-branch:

    cjv rotterdam.json commit Examples/rotterdam/initial_deleted_building.json test-branch -m "Delete a building"
    
  5. You can check if everything is okay with:

    cjv rotterdam.json log master test-branch --graph
    
  6. Merge test-branch into master:

    cjv rotterdam.json merge test-branch master
    
  7. Checkout the merged version:

    cjv rotterdam.json checkout master rotterdam_master.json
    
  8. Use the plethora of CityJSON viewers to investigate the new model. And submits the bugs you'll find as issues. :)

TODO

  • Add support for compressed CityJSONs.
  • Add support for geometry-templates, textures and materials.
  • Add option to append objects except for just replacing current ones?

About

A prototype implementation of interaction with versioned CityJSON files

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages