├── Diagrams.pdf ├── LICENSE ├── README.md └── docs ├── .gitignore ├── 404.html ├── Gemfile ├── Gemfile.lock ├── _config.yml ├── _posts └── 2019-09-20-welcome-to-jekyll.markdown ├── definitions.markdown ├── deltaspec.markdown ├── index.markdown └── requirements.markdown /Diagrams.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/aecdeltas/aec-deltas-spec/eec37eadb775590daa54ec3f1a97ca11b4170459/Diagrams.pdf -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 AEC ∆ 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![AEC_DELTA](https://user-images.githubusercontent.com/3008807/56821254-b6c66c00-6845-11e9-908d-b2f4c6bc68ec.jpg) 2 | 3 | # AEC Deltas Specification 4 | 5 | AEC Delta Mobility is an Innovate UK funded project under the [Increase productivity, performance and quality in UK construction](https://apply-for-innovation-funding.service.gov.uk/competition/203/overview#scope) grant No. 104799 as part of £12.5 million public contribution from the [Industrial Strategy Challenge Fund](https://www.gov.uk/government/news/ai-and-digital-design-to-transform-future-of-uk-construction). 6 | 7 | [![Dr Al Fisher explains the AEC Deltas project](https://user-images.githubusercontent.com/3008807/62527154-87ef6700-b832-11e9-814f-9c951e797957.png)](https://www.youtube.com/watch?v=ogfyzbeEZvc "Dr Al Fisher explains the AEC Deltas project") 8 | British Information Modelling June 2019 Al Fisher - BuroHappold 9 | 10 | ## Description 11 | The aim of this project is to engage manufacturing in the earliest possible stages of design by streamlining data workflow from consultants to factory. This is currently difficult due to proprietary file formats and commercial vendor lock-in causing significant overheads especially in design for manufacturing. Even though open standards such as IFC, COINS and BCF paved the way for collaboration, they are neither suitable for manufacturing nor scalable to large architectural and infrastructure projects. IFC, for instance, requires enormous amounts of memory to process (a single 1GB IFC file will easily consume 32GB of RAM over several hours of processing on a powerful server), not to mention inconsistent support across different applications. To address such shortcomings, this project is developing a novel open source micro-services web framework that will enable the industry to exchange individual object-level changes across various applications regardless of the underlying data format. Instead of exporting a whole file, our aim is to stream individual design changes (a.k.a. deltas) to whichever application is conformant with our newly proposed “AEC Delta Mobility” specification. 12 | 13 | ![aec-deltas](https://user-images.githubusercontent.com/3008807/53182999-77379580-35f2-11e9-93e5-98086647c0bf.png) 14 | 15 | To achieve this we are going to: 16 | 1. Define a new common delta interchange schema that is open and shared across various systems, 17 | 2. Specify a new REST API micro-services layer so that different AEC applications can communicate easily, and 18 | 3. Validate the proposed specification by creating a working reference implementation that connects open source Speckle Works and 3D Repo with proprietary systems. This will cover the basis of CRUD commands, i.e. Create, Read, Update and Delete with the addition of a built-in security specification to ensure encrypted data transmission but also verification of authorship. 19 | 20 | This new and open ecosystem is a collaboration between the most famous and internationally renowned architectural and engineering practices with the standardisation support from [Building Smart International](https://www.buildingsmart.org) and the [UK BIM Alliance](http://www.ukbimalliance.org). The project will deliver an open specification and an open source reference implementation but also support further development of paid for services that will drive adoption, commercialisation and long-term support. Ultimately, our unique approach is expected to streamline the design processes for manufacturing, reduce delays and thus directly increase productivity on a wide variety of multidisciplinary projects. Such a solution will help engage manufacturers in the early design stages resulting in increased pre-manufactured value of build assets across the sector. 21 | 22 | ## Project Partners 23 | * [BuroHappold Engineering](https://www.burohappold.com) - [BHoM](https://bhom.xyz) 24 | * [3D Repo](https://3drepo.com) 25 | * [Speckle Works](https://speckle.works) 26 | * [UCL Bartlett School of Construction and Project Management](https://www.ucl.ac.uk/bartlett/construction/) 27 | * [Rhomberg Sersa Rail Group (UK)](https://rhomberg-sersa.com) 28 | 29 | ## Events 30 | 31 | * 20 March 2019 - [7th British Information Modelling](https://3drepo.com/british-information-modelling-march-2019/) at TOG King's Cross, London, UK 32 | * 30 April 2019 - [The Future of Design Collaboration](https://3drepo.com/event-the-future-of-design-collaboration/) at BuroHappold, London, UK 33 | * 24 June 2019 - IFC Revision Meetup at HOK, London, UK 34 | * 25 June 2019 - [8th British Information Modelling](https://www.eventbrite.co.uk/e/3d-repo-british-information-modelling-june-2019-tickets-60297667948) at Bryden Wood, London, UK 35 | * 26-28 July 2019 - [Web3D 2019](http://web3d2019.web3d.org/) at Hotel Indigo, Los Angeles, US 36 | * 8 October 2019 - 9th British Information Modelling at Crypt on the Green, London, UK 37 | * 16-17 October 2019 - [Digital Construction Week](https://www.digitalconstructionweek.com/) at Excel, London, UK 38 | 39 | ## Project Pages 40 | * [Software Requirements](https://github.com/aecdeltas/aec-deltas-spec/wiki/Software-Requirements) 41 | * [Delta Specification](https://github.com/aecdeltas/aec-deltas-spec/wiki/Delta-Specification) 42 | * [Comparison between Speckle Diff API Endpoint & AEC∆ Spec](https://github.com/aecdeltas/aec-deltas-spec/wiki/Comparison-between-Speckle-Diff-API-Endpoint-&-AEC%E2%88%86-Spec) 43 | 44 | # License 45 | This project is Copyright of respective project partners, and is released under the open source MIT license. All contributors are required to sign either the Individual or the Entity Contributor License Agreement (CLA). 46 | 47 | # Contributing 48 | We very much encourage contributions to the AEC Deltas project. 49 | 50 | We are currently in the User Requirements gathering stage. Please contribute any requirements, suggestions, etc. into the Wiki section here: https://github.com/aecdeltas/aec-deltas-spec/wiki 51 | 52 | For code contributions, fork the desired repository and commit your modifications there. Once happy with the changes, you can generate a pull request and our team will integrate it upstream after a review. 53 | 54 | Your pull requests should: 55 | 1. Follow the style of the existing code 56 | 2. One commit should just do one thing, and one thing only 57 | 3. Rebase your branch against upstream's master so that we don't pull redundant commits 58 | 4. Sign our Individual CLA or if you are representing a legal entity, sign the Entity CLA 59 | 60 | ## Contact 61 | If you need any help or want to contribute please contact: deltas.internal@3drepo.org We look forward to hearing from you. 62 | -------------------------------------------------------------------------------- /docs/.gitignore: -------------------------------------------------------------------------------- 1 | _site 2 | .sass-cache 3 | .jekyll-cache 4 | .jekyll-metadata 5 | vendor 6 | -------------------------------------------------------------------------------- /docs/404.html: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: /404.html 3 | layout: default 4 | --- 5 | 6 | 19 | 20 |
21 |

404

22 | 23 |

Page not found :(

24 |

The requested page could not be found.

25 |
26 | -------------------------------------------------------------------------------- /docs/Gemfile: -------------------------------------------------------------------------------- 1 | source "https://rubygems.org" 2 | # Hello! This is where you manage which Jekyll version is used to run. 3 | # When you want to use a different version, change it below, save the 4 | # file and run `bundle install`. Run Jekyll with `bundle exec`, like so: 5 | # 6 | # bundle exec jekyll serve 7 | # 8 | # This will help ensure the proper Jekyll version is running. 9 | # Happy Jekylling! 10 | gem "jekyll", "~> 3.8.5" 11 | # This is the default theme for new Jekyll sites. You may change this to anything you like. 12 | 13 | gem "minima", "~> 2.5" 14 | 15 | # If you want to use GitHub Pages, remove the "gem "jekyll"" above and 16 | # uncomment the line below. To upgrade, run `bundle update github-pages`. 17 | 18 | # gem "github-pages", group: :jekyll_plugins 19 | # If you have any plugins, put them here! 20 | 21 | group :jekyll_plugins do 22 | gem "jekyll-feed", "~> 0.12" 23 | end 24 | 25 | # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem 26 | # and associated library. 27 | install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do 28 | gem "tzinfo", "~> 1.2" 29 | gem "tzinfo-data" 30 | end 31 | 32 | # Performance-booster for watching directories on Windows 33 | gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform? 34 | 35 | -------------------------------------------------------------------------------- /docs/Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | addressable (2.7.0) 5 | public_suffix (>= 2.0.2, < 5.0) 6 | colorator (1.1.0) 7 | concurrent-ruby (1.1.5) 8 | em-websocket (0.5.1) 9 | eventmachine (>= 0.12.9) 10 | http_parser.rb (~> 0.6.0) 11 | eventmachine (1.2.7) 12 | ffi (1.11.1) 13 | forwardable-extended (2.6.0) 14 | http_parser.rb (0.6.0) 15 | i18n (0.9.5) 16 | concurrent-ruby (~> 1.0) 17 | jekyll (3.8.6) 18 | addressable (~> 2.4) 19 | colorator (~> 1.0) 20 | em-websocket (~> 0.5) 21 | i18n (~> 0.7) 22 | jekyll-sass-converter (~> 1.0) 23 | jekyll-watch (~> 2.0) 24 | kramdown (~> 1.14) 25 | liquid (~> 4.0) 26 | mercenary (~> 0.3.3) 27 | pathutil (~> 0.9) 28 | rouge (>= 1.7, < 4) 29 | safe_yaml (~> 1.0) 30 | jekyll-feed (0.12.1) 31 | jekyll (>= 3.7, < 5.0) 32 | jekyll-sass-converter (1.5.2) 33 | sass (~> 3.4) 34 | jekyll-seo-tag (2.6.1) 35 | jekyll (>= 3.3, < 5.0) 36 | jekyll-watch (2.2.1) 37 | listen (~> 3.0) 38 | kramdown (1.17.0) 39 | liquid (4.0.3) 40 | listen (3.1.5) 41 | rb-fsevent (~> 0.9, >= 0.9.4) 42 | rb-inotify (~> 0.9, >= 0.9.7) 43 | ruby_dep (~> 1.2) 44 | mercenary (0.3.6) 45 | minima (2.5.1) 46 | jekyll (>= 3.5, < 5.0) 47 | jekyll-feed (~> 0.9) 48 | jekyll-seo-tag (~> 2.1) 49 | pathutil (0.16.2) 50 | forwardable-extended (~> 2.6) 51 | public_suffix (4.0.1) 52 | rb-fsevent (0.10.3) 53 | rb-inotify (0.10.0) 54 | ffi (~> 1.0) 55 | rouge (3.11.0) 56 | ruby_dep (1.5.0) 57 | safe_yaml (1.0.5) 58 | sass (3.7.4) 59 | sass-listen (~> 4.0.0) 60 | sass-listen (4.0.0) 61 | rb-fsevent (~> 0.9, >= 0.9.4) 62 | rb-inotify (~> 0.9, >= 0.9.7) 63 | thread_safe (0.3.6) 64 | tzinfo (1.2.5) 65 | thread_safe (~> 0.1) 66 | tzinfo-data (1.2019.3) 67 | tzinfo (>= 1.0.0) 68 | wdm (0.1.1) 69 | 70 | PLATFORMS 71 | ruby 72 | 73 | DEPENDENCIES 74 | jekyll (~> 3.8.5) 75 | jekyll-feed (~> 0.12) 76 | minima (~> 2.5) 77 | tzinfo (~> 1.2) 78 | tzinfo-data 79 | wdm (~> 0.1.1) 80 | 81 | BUNDLED WITH 82 | 2.0.2 83 | -------------------------------------------------------------------------------- /docs/_config.yml: -------------------------------------------------------------------------------- 1 | # Welcome to Jekyll! 2 | # 3 | # This config file is meant for settings that affect your whole blog, values 4 | # which you are expected to set up once and rarely edit after that. If you find 5 | # yourself editing this file very often, consider using Jekyll's data files 6 | # feature for the data you need to update frequently. 7 | # 8 | # For technical reasons, this file is *NOT* reloaded automatically when you use 9 | # 'bundle exec jekyll serve'. If you change this file, please restart the server process. 10 | # 11 | # If you need help with YAML syntax, here are some quick references for you: 12 | # https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml 13 | # https://learnxinyminutes.com/docs/yaml/ 14 | # 15 | # Site settings 16 | # These are used to personalize your new site. If you look in the HTML files, 17 | # you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. 18 | # You can create any custom variable you would like, and they will be accessible 19 | # in the templates via {{ site.myvariable }}. 20 | 21 | title: AEC∆ 22 | email: deltas.internal@3drepo.org 23 | description: >- # this means to ignore newlines until "baseurl:" 24 | AEC Delta Mobility is an Innovate UK funded project under the Increase productivity, performance and quality in UK construction grant No. 104799 as part of £12.5 million public contribution from the Industrial Strategy Challenge Fund. 25 | baseurl: "aec-deltas-spec" # the subpath of your site, e.g. /blog 26 | url: "https://aecdeltas.github.io/" # the base hostname & protocol for your site, e.g. http://example.com 27 | # twitter_username: jekyllrb 28 | # github_username: jekyll 29 | 30 | # Build settings 31 | remote_theme: pmarsceill/just-the-docs 32 | plugins: 33 | - jekyll-feed 34 | 35 | aux_links: 36 | "AEC∆ on GitHub": 37 | - "//github.com/aecdeltas" 38 | 39 | footer_content: "Copyright © 2017-2019 AEC∆ Project Partners. Licensed under the MIT Licence." 40 | 41 | # Exclude from processing. 42 | # The following items will not be processed, by default. 43 | # Any item listed under the `exclude:` key here will be automatically added to 44 | # the internal "default list". 45 | # 46 | # Excluded items can be processed by explicitly listing the directories or 47 | # their entries' file path in the `include:` list. 48 | # 49 | # exclude: 50 | # - .sass-cache/ 51 | # - .jekyll-cache/ 52 | # - gemfiles/ 53 | # - Gemfile 54 | # - Gemfile.lock 55 | # - node_modules/ 56 | # - vendor/bundle/ 57 | # - vendor/cache/ 58 | # - vendor/gems/ 59 | # - vendor/ruby/ 60 | 61 | theme: jekyll-theme-cayman -------------------------------------------------------------------------------- /docs/_posts/2019-09-20-welcome-to-jekyll.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | layout: post 3 | title: "Welcome to Jekyll!" 4 | date: 2019-09-20 11:39:15 +0100 5 | categories: jekyll update 6 | --- 7 | You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated. 8 | 9 | Jekyll requires blog post files to be named according to the following format: 10 | 11 | `YEAR-MONTH-DAY-title.MARKUP` 12 | 13 | Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. After that, include the necessary front matter. Take a look at the source for this post to get an idea about how it works. 14 | 15 | Jekyll also offers powerful support for code snippets: 16 | 17 | {% highlight ruby %} 18 | def print_hi(name) 19 | puts "Hi, #{name}" 20 | end 21 | print_hi('Tom') 22 | #=> prints 'Hi, Tom' to STDOUT. 23 | {% endhighlight %} 24 | 25 | Check out the [Jekyll docs][jekyll-docs] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll Talk][jekyll-talk]. 26 | 27 | [jekyll-docs]: https://jekyllrb.com/docs/home 28 | [jekyll-gh]: https://github.com/jekyll/jekyll 29 | [jekyll-talk]: https://talk.jekyllrb.com/ 30 | -------------------------------------------------------------------------------- /docs/definitions.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | layout: page 3 | title: Definitions 4 | permalink: /definitions/ 5 | nav_order: 4 6 | --- 7 | 8 | # Definitions (Glossary) 9 | 10 | The following table debunks some of the terminology used within the research documents. 11 | 12 | |id |Concept description|Example|AECdeltas naming |Speckle naming | 3D Repo naming | BHoM naming | Other proposed namings | Notes | 13 | |---|--------|--------|-------|--------|--------|-------|---------|--------| 14 | |1 |Container for the objects|Part of a building (e.g. a portal frame; mep pipes) |Stream |Stream |Model |- |Container, Project || 15 | |2 |Given state in time of the Container (1) | |Revision |(Parent) Stream| | |Version, Revision, State, Snapshot, LampPost, Checkpoint|| 16 | |3 |Container for the "containers" (1) (collection of collections of objects) |An entire building |Project|Project|Project (/federation?)|- ||| 17 | |4 |Upload on the online "container" (3) | |Upload | | |Push |POST, PUT || 18 | |5 |Download from the online "container" (3) | |Download | | |Pull |GET || 19 | |6 |Delta: Objects added in the UI |E.g. an user creates a new object; that object will then be pushed online on the container |OnlyA | | |ToBeCreated|New, Created, OnlySetA, AOnly |In BHoM, the point of view for the object status is looking from the external software. E.g. Created = it's been added in the external software | 20 | |7 |Delta: Objects deleted from UI | |OnlyB | | |ToDelete |Old, Deleted, OnlySetB, BOnly || 21 | |8 |Delta: Objects modified in UI| |Modified | | |ToModify |Modified, Intersection-Modified || 22 | |9 |Delta: Objects not changed in UI | |Unmodified | | |- |Unchanged, NotModified, Intersection-NotModified|| 23 | |10 |User choice in front of a conflict status emerged from his upload action |User pushed some change, but server responds with an error, e.g. because the user did not pull the lastest changes in a while|Conflict resolution| | | |Conflict resolution, Pick&Choose, Modify, Merging || 24 | |11 |Id of an object; this id does not change when the object changes (it's maintained between different revisions) | |Persistent ID | | | ||| 25 | |12 |Id of an object; this id changes when the object changes (it's always unique at any point in time) | |Unique ID | | | ||Is it an GUID or a hash? Does not matter| 26 | |13 |Delta message, used to transfer the information. Should be as stripped down as possible, minimum amount of information needed| | | | | |DeltaMessage, DeltaPayload, || 27 | |14 |Delta as result of the collection level diffing | | | | | |Delta, DeltaDiff|| 28 | |15 |Delta as result of the property level diffing| |DeltaStream| | | |DeltaStream, HistoricalDelta, DeltaHistory, DeltaTracked|| 29 | -------------------------------------------------------------------------------- /docs/deltaspec.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | layout: page 3 | title: Delta Specification 4 | permalink: /deltaspec/ 5 | nav_order: 3 6 | --- 7 | 8 | # Introduction 9 | {: .no_toc } 10 | In our definition, the smallest unit of change is an **AEC object**. Such an object is simply a collection of key-value pairs describing an AEC-specific entity such as a _steel beam_, _window_, _slab_ etc., with its respective properties such as an `id`, `length`, `fire_rating`, etc. However, we do not subscribe to any one specific data representation or encoding. That implies that the definition of an object can be based on anything such as an IFC Object but also a BHoM Object, a 3D Repo Object, a Speckle Object or any other representation as required. Ultimately, an object is simply a **binary blob** that some but not necessarily all applications would be able to decode, interpret and convert into their native representation of what the respective properties relate to. 11 | 12 | Therefore, there is a need to maintain a set of **converters** that provide the necessary linkage between various representations of objects and their properties within the native applications. This will be achieved via a **look-up table** which defines the one-to-one mapping between the properties. For simplicity, we assume that each property only maps to one counterpart property in the receiving application and that not all properties necessarily need to be mapped across. After all, it is often the case that the receiving application is only interested in a subset of the object properties to achieve its specific function. Note that the [BHoM library](https://bhom.xyz/) by BuroHappold Engineering already contains such converters known as toolkits, see [https://github.com/BHoM](https://github.com/BHoM) for details. 13 | 14 | # Table Of Contents 15 | {: .no_toc } 16 | 17 | 1. TOC 18 | {:toc} 19 | 20 | ## Base Principles 21 | * **A single object is the smallest unit of change.** Even if the smallest of properties on an object has been changed, the whole object needs to be flagged accordingly. For instance, a single vertex in a mesh change would require the whole mesh object to be updated. 22 | * **All objects are immutable.** Any change on an object means the object has been modified, and thus a new object with a new ID/hash needs to be created to replace it and advance the revision further. 23 | * **Each object has a unique and a shared ID.** Each object by definition requires a unique ID (UID) in order to uniquely identify it. In addition, it also requires a shared ID (SID) which is shared across various instances/revisions of the same object over time. 24 | * **Not all objects have to have a visual representation.** There are objects that simply have no visual representation such as a renderable mesh attached. For instance, a steel beam can be represented by its `load capacity` and `length` in order to perform structural analysis calculations even though it would not be renderable directly as is. 25 | 26 | ## Deltas 27 | 28 | A **Delta (∆)** is a set of objects that have been identified as either `created`, `deleted` or `updated` between two applications. The trivial example is an empty set `{}` whereby no change has been detected. **Differencing** or **_"diffing"_** for short is then the process of establishing the delta set of objects between two revisions or states of host applications holding the AEC information in memory. 29 | 30 | In mathematical notation, we would write: 31 | ``` 32 | ∆ = { C, D, U }, 33 | ``` 34 | where `C`, `D` and `U` are sets of created/added, deleted and updated/modified AEC objects respectively. The naming convention was selected to closely follow the [CRUD (create, read, update and delete)](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) principles of persistent storage manipulation. 35 | 36 | However, it is important to note that differencing itself can be implemented at two levels: 37 | - **Level 1: Collection/object-level differencing.** Input are two collections and the result is a list of changed objects. This happens at the AEC Deltas middleware layer and is integral to our definition; 38 | - **Level 2: Property-level differencing.** Differencing of individual line-by-line properties only happens at the application layer and is left open to implementation as required by the receiving application. This, therefore, is not part of the AEC Deltas middleware but can be delivered on top. 39 | 40 | Here, we only concentrate on the object-level differencing (Level 1). Objects are being freely exchanged but it is the application's responsibility to determine what happens with this information on the client side. For instance, the receiving application might decide to consume only some of the updates, ignore all of them or pass them on unmodified depending on the user requirements and input. Note that the source application is the one responsible for notifying what the deltas/changes are between itself and the receiving application. 41 | 42 | ### Delta Definition 43 | > _Delta definition is currently a work in progress and will be updated over the next two quarters._ 44 | 45 | Each delta set should have the following base fields in order to properly identify the authorship and ownership of the information that is carried within. 46 | - **Project ID** - `uuid` unique ID in [RFC 4122 v4](https://tools.ietf.org/html/rfc4122) format (unique to each project) 47 | - **Author** - `string` 48 | - **Timestamp** - `time_t` timestamp in seconds from the Unix epoch 49 | - **Payload** - `string` or `binary` 50 | - **Cryptographic signature** - signed by a private key of the author, i.e. an [RSA cryptosystem](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) of the delta itself 51 | 52 | In a JavaScript notation, the encoding of a delta would look like this: 53 | ``` 54 | delta = { 55 | "stream_id": , 56 | "created": [ 57 | [ uid_1, sid_1, mesh_1, material/colour_1, metadata_1, authoring_tool_1, ... ], 58 | [ uid_2, sid_2, mesh_2, material/colour_2, metadata_2, authoring_tool_2, ... ], 59 | [ uid_3, sid_3, mesh_3, material/colour_3, metadata_3, authoring_tool_3, ... ], 60 | ... 61 | ], 62 | "deleted": [ sid_4, sid_5, sid_6, ... ], 63 | "updated": [ 64 | [ uid_7, sid_7, mesh_7, material/colour_7, metadata_7, authoring_tool_7, ... ], 65 | [ uid_8, sid_8, mesh_8, material/colour_8, metadata_8, authoring_tool_8, ... ], 66 | [ uid_9, sid_9, mesh_9, material/colour_9, metadata_9, authoring_tool_9, ... ], 67 | ... 68 | ] 69 | "revision_A": from_id, 70 | "revision_B": to_id, 71 | "timestamp": , 72 | "signature": , 73 | "sender": // E.g. BHoM, 3D Repo, Speckle, etc. 74 | } 75 | ``` 76 | 77 | # Dataflow 78 | > _Dataflow is currently a work in progress and will be updated over the next two quarters._ 79 | 80 | Establishing the correct dataflow between various applications and servers is essential to proper design of the delta set and the subsequent communication protocol. 81 | 82 | A naïve protocol would look like this: 83 | 84 | 1. The status of the latest revision is checked; 85 | 1. Revision ID is obtained: 86 | 1. ID is recognised, or 87 | 1. ID is not recognised, a list of all revision IDs is requested: 88 | 1. Overlap is found with some earlier revision, or 89 | 1. Overlap is not found, all object IDs of the latest revision are requested; 90 | 1. Diff is calculated; 91 | 1. Delta updated is sent across. 92 | 93 | ## Delta Sequence Diagrams 94 | 95 | > _A sequence diagram shows, as parallel vertical lines (lifelines), different processes or objects that live simultaneously, and, as horizontal arrows, the messages exchanged between them, in the order in which they occur. This allows the specification of simple runtime scenarios in a graphical manner._ -[Wikipedia](https://en.wikipedia.org/wiki/Sequence_diagram) 96 | 97 | Our proposed protocol can be translated into five different sequence flow scenarios as follows: 98 | 1. **Push of a new model.** The base case is to send a new model/project to the server and/or client application for the very first time. 99 | 1. **Server is behind.** When the server is behind the latest revision, the client calculates the differences and sends a delta upstream. 100 | 1. **Conflict:** 101 | 1. **Client is behind.** Client is working on a revision which becomes out of date. It then calculates the differences and sends the delta upstream. 102 | 1. **Two clients are pushing the same revision.** Two clients update the same revision simultaneously which leads to one of them being out of sync. The affected client then calculates the differences and sends a delta upstream. 103 | 1. **Client is pushing an existing revision.** Client pushing an existing revision to the server results in a `null` delta. 104 | 105 | ![scenario1](https://user-images.githubusercontent.com/3008807/61866584-550db080-aecd-11e9-8733-49a6bfe199f3.png) 106 | ### Scenario 1 107 | In Scenario 1, a new project with its first revision gets established on the server. This is the base case whereby the user creates a new project and _"pushes"_ it to the server. Since the server does not recognise this project in its database (because it is new), it obtains the revision data and stores it accordingly. The return message then indicates the transaction completed successfully. In this case, the delta is the entire model. 108 | 109 | *** 110 | 111 | ![scenario2](https://user-images.githubusercontent.com/3008807/61866701-900fe400-aecd-11e9-9496-74abe2e8e67b.png) 112 | ### Scenario 2 113 | In Scenario 2, the client performs changes locally and thus advances the revision forward meaning the server is left behind. Thus, the client retrieves the latest revision, enacts changes locally and pushes a new advanced revision back to the server. Since the server is behind, it responds with its latest revision number which is used by the client to calculate the delta in order to send it upstream to the server. The return message then indicates the transaction completed successfully. 114 | 115 | *** 116 | 117 | ![scenario3a](https://user-images.githubusercontent.com/3008807/62529096-e23df700-b835-11e9-86c7-7be5956b7f08.png) 118 | ### Scenario 3a 119 | In Scenario 3a, two different clients, say `A` and `B`, retrieve the same revision from the server and perform their respective changes locally independently of each other. Then, client `B` pushes their changes to the server by enacting Scenario 2. Client `A` attempts to achieve the same, however is in conflict since their revision is now behind the server. Thus, client `A` calculates the differences and pushes the delta to the server or decides to postpone the action to a later date. The return message then indicates the transaction completed successfully. 120 | 121 | *** 122 | 123 | ![scenario3b](https://user-images.githubusercontent.com/3008807/62529206-1e715780-b836-11e9-91e0-078037a95edc.png) 124 | ### Scenario 3b 125 | 126 | > _This scenario will be updated and expanded upon in the next two quarters._ 127 | 128 | In Scenario 3b, two different clients, say `A` and `B`, retrieve the same revision potentially from different sources and then attempt to push their respective changes enacting Scenario 2 and 3a. However, instead of concluding with sending a delta back to the server, client `A` performs local updates and then enacts Scenario 1 in order to advance the revision further. The return message then indicates the transaction completed successfully. 129 | 130 | *** 131 | 132 | ![scenario4](https://user-images.githubusercontent.com/3008807/62529407-7c05a400-b836-11e9-9a96-fec27e8bb752.png) 133 | ### Scenario 4 134 | In Scenario 4, a client is passing a revision from server `01` to server `02`. However, `02` is already at the latest revision, thus the delta calculated by the client is `null` and no further data needs to be exchanged. The return message then indicates the transaction completed successfully. 135 | 136 | -------------------------------------------------------------------------------- /docs/index.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | layout: page 3 | title: Introduction 4 | --- 5 | 6 | 7 | 8 | # AEC Deltas 9 | 10 | AEC Delta Mobility is an Innovate UK funded project under the [Increase productivity, performance and quality in UK construction](https://apply-for-innovation-funding.service.gov.uk/competition/203/overview#scope) grant No. 104799 as part of £12.5 million public contribution from the [Industrial Strategy Challenge Fund](https://www.gov.uk/government/news/ai-and-digital-design-to-transform-future-of-uk-construction). 11 | 12 | [![Dr Al Fisher explains the AEC Deltas project](https://user-images.githubusercontent.com/3008807/62527154-87ef6700-b832-11e9-814f-9c951e797957.png)](https://www.youtube.com/watch?v=ogfyzbeEZvc "Dr Al Fisher explains the AEC Deltas project") 13 | 14 | British Information Modelling June 2019 Al Fisher - BuroHappold 15 | 16 | # Table Of Contents 17 | {: .no_toc } 18 | 19 | 1. TOC 20 | {:toc} 21 | 22 | ## Description 23 | The aim of this project is to engage manufacturing in the earliest possible stages of design by streamlining data workflow from consultants to factory. This is currently difficult due to proprietary file formats and commercial vendor lock-in causing significant overheads especially in design for manufacturing. Even though open standards such as IFC, COINS and BCF paved the way for collaboration, they are neither suitable for manufacturing nor scalable to large architectural and infrastructure projects. IFC, for instance, requires enormous amounts of memory to process (a single 1GB IFC file will easily consume 32GB of RAM over several hours of processing on a powerful server), not to mention inconsistent support across different applications. To address such shortcomings, this project is developing a novel open source micro-services web framework that will enable the industry to exchange individual object-level changes across various applications regardless of the underlying data format. Instead of exporting a whole file, our aim is to stream individual design changes (a.k.a. deltas) to whichever application is conformant with our newly proposed “AEC Delta Mobility” specification. 24 | 25 | ![aec-deltas](https://user-images.githubusercontent.com/3008807/53182999-77379580-35f2-11e9-93e5-98086647c0bf.png) 26 | 27 | To achieve this we are going to: 28 | 1. Define a new common delta interchange schema that is open and shared across various systems, 29 | 2. Specify a new REST API micro-services layer so that different AEC applications can communicate easily, and 30 | 3. Validate the proposed specification by creating a working reference implementation that connects open source Speckle Works and 3D Repo with proprietary systems. This will cover the basis of CRUD commands, i.e. Create, Read, Update and Delete with the addition of a built-in security specification to ensure encrypted data transmission but also verification of authorship. 31 | 32 | This new and open ecosystem is a collaboration between the most famous and internationally renowned architectural and engineering practices with the standardisation support from [Building Smart International](https://www.buildingsmart.org) and the [UK BIM Alliance](http://www.ukbimalliance.org). The project will deliver an open specification and an open source reference implementation but also support further development of paid for services that will drive adoption, commercialisation and long-term support. Ultimately, our unique approach is expected to streamline the design processes for manufacturing, reduce delays and thus directly increase productivity on a wide variety of multidisciplinary projects. Such a solution will help engage manufacturers in the early design stages resulting in increased pre-manufactured value of build assets across the sector. 33 | 34 | ## Project Partners 35 | * [BuroHappold Engineering](https://www.burohappold.com) - [BHoM](https://bhom.xyz) 36 | * [3D Repo](https://3drepo.com) 37 | * [Speckle Works](https://speckle.works) 38 | * [UCL Bartlett School of Construction and Project Management](https://www.ucl.ac.uk/bartlett/construction/) 39 | * [Rhomberg Sersa Rail Group (UK)](https://rhomberg-sersa.com) 40 | 41 | ## Events 42 | 43 | * 20 March 2019 - [7th British Information Modelling](https://3drepo.com/british-information-modelling-march-2019/) at TOG King's Cross, London, UK 44 | * 30 April 2019 - [The Future of Design Collaboration](https://3drepo.com/event-the-future-of-design-collaboration/) at BuroHappold, London, UK 45 | * 24 June 2019 - IFC Revision Meetup at HOK, London, UK 46 | * 25 June 2019 - [8th British Information Modelling](https://www.eventbrite.co.uk/e/3d-repo-british-information-modelling-june-2019-tickets-60297667948) at Bryden Wood, London, UK 47 | * 26-28 July 2019 - [Web3D 2019](http://web3d2019.web3d.org/) at Hotel Indigo, Los Angeles, US 48 | * 14 October 2019 - 9th British Information Modelling at Atkins, London, UK 49 | * 16-17 October 2019 - [Digital Construction Week](https://www.digitalconstructionweek.com/) at Excel, London, UK 50 | 51 | # License 52 | This project is Copyright of respective project partners, and is released under the open source MIT license. All contributors are required to sign either the Individual or the Entity Contributor License Agreement (CLA). 53 | 54 | # Contributing 55 | We very much encourage contributions to the AEC Deltas project. 56 | 57 | We are currently in the User Requirements gathering stage. Please contribute any requirements, suggestions, etc. into the Wiki section here: https://github.com/aecdeltas/aec-deltas-spec/wiki 58 | 59 | For code contributions, fork the desired repository and commit your modifications there. Once happy with the changes, you can generate a pull request and our team will integrate it upstream after a review. 60 | 61 | Your pull requests should: 62 | 1. Follow the style of the existing code 63 | 2. One commit should just do one thing, and one thing only 64 | 3. Rebase your branch against upstream's master so that we don't pull redundant commits 65 | 4. Sign our Individual CLA or if you are representing a legal entity, sign the Entity CLA 66 | 67 | ## Contact 68 | If you need any help or want to contribute please contact: deltas.internal@3drepo.org We look forward to hearing from you. -------------------------------------------------------------------------------- /docs/requirements.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | layout: page 3 | title: Requirements 4 | permalink: /requirements/ 5 | nav_order: 1 6 | --- 7 | # Requirements 8 | {: .no_toc } 9 | 10 | > _Requirements are descriptions of the services that a software system must provide and the constraints under which it must operate. Requirements can range from high-level abstract statements of services or system constraints to detailed mathematical functional specifications. [Source](http://www.inf.ed.ac.uk/teaching/courses/cs2/LectureNotes/CS2Ah/SoftEng/se02.pdf)_ 11 | 12 | The AEC Delta Mobility project aims to define a new middle-ware layer to support exchange of small incremental changes between AEC-specific software packages either locally or within the cloud. This document lists the end-user requirements as well as individual system requirements to drive the software specification going forward. 13 | 14 | # Table Of Contents 15 | {: .no_toc } 16 | 17 | 1. TOC 18 | {:toc} 19 | # User Requirements 20 | 21 | > _User requirements are defined using natural language, tables and diagrams._ 22 | 23 | ## Actors 24 | 1. Admin 25 | 1. User (any user): Planner, Design Coordinator/Project Manager, Consultant/Engineer, Contractor, Architect, Field Operator 26 | 1. Software Developer 27 | 1. Observer (can see data but cannot commit) 28 | 29 | 30 | ## User Stories 31 | 32 | 33 | > _As a **\**, I want **\** so that **\**._ 34 | 35 | 36 | 37 | ### US1.1: Planner 38 | 39 | _As a **Planner**, I want to **associate planning activities to design objects** so that I can **plan activities in planning software** (e.g. Tilos, Primavera P6, Bentley Synchro, Microsoft Project, etc.)._ 40 | 41 | ![planner](https://user-images.githubusercontent.com/3008807/56722740-96ac8500-673f-11e9-8542-9a5d734adf48.png) 42 | 43 | This includes quantities take off, object definitions, schedules and plans in software such as Tilos, Primavera P6, Synchro, etc. Ultimately, the user wants to see how model changes affect the activities. 44 | 45 | 1. Planner opens all the BIM models and federates them (most likely in Solibri or Navisworks or 3D Repo); 46 | 1. Create a planning view from the given federated models; 47 | 1. Create relevant planning activities; 48 | 1. Export into a sub-plan and save the configuration in order to be able to re-apply. 49 | 50 | 51 | ![planner-detailed](https://user-images.githubusercontent.com/3008807/56723264-86e17080-6740-11e9-8953-8472e6edaa7c.png) 52 | 53 | ### US1.2: Estimator 54 | _As an **Estimator**, I want to **create a model view on the design scope** so that I can **bring it into an estimation software and create a cost estimate**._ 55 | 56 | ![estimator](https://user-images.githubusercontent.com/3008807/56723456-e63f8080-6740-11e9-9925-204496aaaa16.png) 57 | 58 | Software such as CostX and Ribi2. 59 | 60 | ![costing](https://user-images.githubusercontent.com/3008807/56737642-c456f580-6762-11e9-82fe-bda37c8d04d0.png) 61 | 62 | --- 63 | 64 | ### US2.1: Design Coordinator/Project Manager 65 | 66 | _As a **Design Coordinator/Project Manager**, I want to **collect and federate the latest BIM models** so that I can **assign design tasks/issues back to the individual Consultants/Contractors to resolve**._ 67 | 68 | ![information-manager](https://user-images.githubusercontent.com/3008807/56736686-b30ce980-6760-11e9-96a7-30e9ca159a7e.png) 69 | 70 | ### US2.2: Consultant/Contractor 71 | 72 | _As a **Consultant/Contractor**, I want to **be told what issues to resolve** so that **I can improve my design and deliver a new iteration**._ 73 | 74 | This user requirement effectively defines a design feedback loop whereby the models are regularly updated and federated in systems like 3D Repo. There, the issues are collected and passed back onto the Consultants/Contractors to resolve and then the whole process is reiterated. 75 | 76 | ![design-coordinator](https://user-images.githubusercontent.com/3008807/56735843-8061f180-675e-11e9-8691-594ab21bb74f.png) 77 | 78 | --- 79 | 80 | ### US3: Design Coordinator/Project Manager 81 | 82 | _As a **Design Coordinator/Project Manager**, I want to **define data compliance checks** so that **individual Consultants/Contractors can self-validate Deltas before sharing**._ 83 | 84 | ![validation](https://user-images.githubusercontent.com/3008807/56736511-3c6fec00-6760-11e9-8821-a3b421637022.png) 85 | 86 | Standard approach especially in the contractor world is to define Employers Information Requirements (EIRs) and BIM Execution Plan which specify the BIM data requirements on a project. Currently, there is no automated way to validate these have been met when exchanging data. 87 | 88 | --- 89 | 90 | ### US4: Consultant 91 | 92 | _As a **Consultant**, I want to **define the accuracy/certainty/LOD of data/options** so that **other actors know to what degree to rely on the information**._ 93 | 94 | This reflects the Levels of Detail and Levels of Information in BIM projects. For instance, many objects could be labelled as placeholders at the early design stages. However, if this gets implemented, then we also need the ability to automatically validate that all placeholders have been replaced by the end of the project. 95 | 96 | --- 97 | 98 | ### US5.1: Consultant 99 | 100 | _As a **Consultant**, I want to **have multiple representations of the same object** so that **I can run different analysis for different purposes**._ 101 | 102 | ![conception-stages](https://user-images.githubusercontent.com/3008807/56736839-172fad80-6761-11e9-9a3e-6799a38edf01.png) 103 | 104 | It is important that the system records the relationships between the objects, be it siblings or parent-child relationships. 105 | Often there would be different representations of the same object for different purposes. A steel beam in architecture would be represented differently to a structural analysis calculation for lateral stress vs top load, etc. 106 | 107 | ### US5.2: User 108 | 109 | _As a **User**, I want to **have different view of the same data** so that I can **concentrate only what is important to me at any given time**._ 110 | 111 | ![multi-modeling](https://user-images.githubusercontent.com/3008807/56737169-b8b6ff00-6761-11e9-8c62-0cab20c6c921.png) 112 | 113 | --- 114 | 115 | ### US6: User 116 | 117 | _As a **User**, I want to **set notifications trigger that is specific to me** so that **I get only notified of the changes that I care of**._ 118 | 119 | ![modeling](https://user-images.githubusercontent.com/3008807/56737418-4b579e00-6762-11e9-8826-1b187315c17b.png) 120 | 121 | --- 122 | 123 | ### US7: Field Operative 124 | 125 | _As a **Field Operative**, I want to **update progress on site within the model** so that **the project can be controlled and monitored transparently by all other stakeholders/Users**._ 126 | 127 | ![field-operative](https://user-images.githubusercontent.com/3008807/56737711-eb152c00-6762-11e9-818c-429aeb941395.png) 128 | 129 | This should help with invoicing (cash turns) and also having _As Installed Model_ ready made. 130 | 131 | --- 132 | 133 | ### US8.1: User 134 | 135 | _As a **User**, I want to **decide when I receive updates and when I synchronise with the master data** so that **I am in control of my workflow**._ 136 | 137 | We need to ensure that the system is not synchronising everything all the time. For instance, if a user actively works on a design moving and creating objects, most other users would not want to get real-time updates whenever a the smallest change occurred. Thus, the user should have the ability to decide if to synchronise manually or receive maybe daily or weekly digest of the latest changes / playback. 138 | 139 | ### US8.2: User 140 | 141 | _As a **User** I want to **have the capacity to get a preview of the changes before synchronising** so that I **do not damage my working copy, should the proposed update not be applicable**._ 142 | 143 | --- 144 | 145 | ### US9.1: Admin 146 | 147 | As an **Admin**, I want to **ensure Developers adhere to the standard** so that **all new software is being interoperable**. 148 | 149 | ### US9.2: Software Developer 150 | 151 | _As a **Software Developer**, I want to **have good documentation** so that **it is easy to adhere to the standard and develop**._ 152 | 153 | --- 154 | 155 | ### US10: User 156 | 157 | _As a **User**, I want to **have different branches/streams/options** so that **I can be in control of the architecture of data sharing** (e.g. in order to mirror the scope of works on a project)._ 158 | 159 | # System Requirements 160 | > _A structured document setting out detailed descriptions of the system services written as a contract between client and contractor._ 161 | 162 | ## Functional Requirements 163 | 164 | > _Statements of services that the system should provide, how the system should react to particular inputs and how the system should behave in particular situation._ 165 | 166 | **3D Repo** 167 | 168 | * Ability to share updates to the server without sharing with other actors until a permission to share project-wide is given. 169 | * Files to be decomposed into object level components that define individual deltas across applications. Each change should be recorded and streamed to the server. There is the possibility that for a peer-to-peer implementation the local application would store all deltas in a sequence locally as a shadow copy (to be discussed) that can be synchronised to; 170 | * Individual changes (deltas) to be streamed one at a time in a sequence. This is to ensure synchronised delivery since the order matters, unlike the time when a change has occurred. 171 | * End-to-end data encryption including at rest. This is the ensure that data is available only to those users that have the appropriate decryption key; 172 | * Ability to identify the author of each change via cryptographic signature. Every delta should be attributable to an individual working on the project as an undeniable proof; 173 | * Permissions-based access control. Only users with the right access privileges are allowed to access data. The question is whether we should account for access to some but not all data such as federations of multiple disciplines, exclusion of sensitive information (eg CCTV models), etc; 174 | * Centralised mapping of fields/elements across different applications with in-built versioning. Each mapping API should be properly versioned and distributed to all parties form a centralised location so that new inputs can be tracked and audited. 175 | 176 | --- 177 | 178 | **HOK** 179 | 180 | * The format to support versioning or not? 181 | * Random access, read parts of the dataset (jump to a specific location or just the latest updates); 182 | * A file (local) representation and a server-side representation; 183 | * USD file with a random access, is it useful? Works well for huge datasets. See https://graphics.pixar.com/usd/docs/Usdz-File-Format-Specification.html 184 | 185 | See also: https://www.nic.org.uk/wp-content/uploads/Data-for-the-Public-Good-NIC-Report.pdf 186 | 187 | --- 188 | 189 | **BuroHappold** 190 | 191 | * Any new adapter interface/protocol will need to provide both server/client and also server-less behaviour as required by the end user. Requires replicated architecture of the server for when off-line (queuing of CRUD/IO operations to then be pushed when back online); 192 | * Object History is recorded; 193 | * Infrastructure to enable (and not preclude) full version control must also be possible; 194 | * Object level diffing (reduction of payload) combined with Object property level comparisons the combination of which allows the potential for efficient comparisons/diffing with inclusion of tolerances also; 195 | * data format for protocol should be flexible and allow completely schema-less data - minimal requirements on header/diff for each data packet to be a technical implementation requirement and thus no such formatting requirements should be imposed as a bare minimum for the end user; 196 | * However in addition - possibility that conforming to a defined schema will enable further capability of system (i.e. extraction of a geometry property(s) or predefined metadata schema?!); 197 | * The format for diffing/comparison maybe dependent on the data type? See above; 198 | * objective to minimise payload on each push; 199 | * store snapshots vs diffs vs actions of user; 200 | * Following the latter of the above - storing actions of user, combined with data source etc. to enable "Data flow tracking/query/viz"; 201 | 202 | ## Non-functional Requirements 203 | 204 | > _Constraints on the services or functions offered by the system such as timing constraints, constraints on the development process, standards, etc._ 205 | 206 | * The system shall process a large BIM federation (i.e. a skyscraper with full architecture, structure and MEP) within 30 minutes. For instance, uploading such a model to 3D Repo will take 5 minutes when loading from Navisworks where the geometry is pre-defined versus 2 hours from direct file uploads where the geometry has to be generated on the fly. 207 | * Two end-points to be able to synchronise over time to the latest state. The most difficult part will be the order of actions and the need to either implement locking or conflict resolution, see here: [3D Diff](https://3drepo.com/publications/3d-diff-an-interactive-approach-to-mesh-differencing-and-conflict-resolution-asia/) 208 | 209 | ## Domain Requirements 210 | 211 | > _Requirements that come from the application domain of the system that reflect the characteristics of that domain_ 212 | 213 | **3D Repo** 214 | 215 | - The System shall have the ability to pull only partial information from the source. I.e. quantities only, not the whole geometric BIM model; 216 | - Structure the model and subdivide according to contractual obligation; 217 | - Provide ability to split the model objects in new ways (i.e. a side of a building slab into individual floors); 218 | - File-format independent delta definition that can support IFC but also any other data representation such as [BHoM](https://bhom.xyz/); 219 | - Scalability to large infrastructure projects. The proposed solution needs to be applicable equally to buildings as well as linear assets. After all, on the data model level, a highway is like a skyscraper, just sideways; 220 | - Ability to exchange either object definitions or triangulated meshes where required. 3D Repo provides some functionality to generate geometry on the fly from object definitions thanks to the [IFCOpenShell library](http://www.ifcopenshell.org/) but assuming authoring tools provide access to generated meshes, those should be a preferred way of retrieving data (due to computational overhead and time constraints); 221 | 222 | --- 223 | 224 | **Rhomberg** 225 | 226 | Defining scope of project: 227 | - Horizontal asset delivery (design & construction phase) as per RSRG work in Rail: traditional or Slabtrack - design information 228 | * Focus on new build, with lesser priorities on the "Operate phase"; De- prioritise Re-furbish; these will be dealt in the Project evaluation 229 | * Must include pre-construction and construction workflows, including the simulation of construction 230 | processes. 231 | 232 | Process and data needs will be detailed as part of the WP2 in M2 and M3: 233 | * Designing to tender level & planning approval (Grip stage 3 to 4) 234 | * Designing to construction level & construction approval (Grip Stage 4 to 5) 235 | * Enabling grip 5 information into Grip 3 stage - design for fabrication / early contractor involvement 236 | * Quantifying of material quantities, temporary works, and labour content during GRIP stages 2 to 6 by enabling data exchange between design tools and estimation tools (Bentley and Autodesk to CostX, Tylos and Rib) 237 | * Planning of timescales, site access, material flows during GRIP stage 4, 5, 6 by enabling information exchange between desing tools and planning tools (Bentley and Autodesk to Synchro and Tylos) 238 | * Linking of tool outputs to dashboarding and visualisation tools to present / optioneering outcomes at global KPI level 239 | 240 | See https://www.transwilts.org/images/pdf/Guide_to_Rail_Investment_Process-1.pdf for GRIP stages definition 241 | 242 | --- 243 | 244 | **HOK** 245 | 246 | * Revit, Archicad, SketchUp, Rhino, CityEngine. Low priority: Tekla, Catia, 3ds Max, Blender 247 | 248 | --- 249 | 250 | **BuroHappold** 251 | 252 | * User is in control to work locally or push to server for remote access; 253 | 254 | ### Side Effects 255 | Results that are not necessarily functional requirements but would be the expected side effects of the project implementation. 256 | 257 | - The software connected to AEC Deltas should eventually have the ability to recalculate whatever analysis, design, planning, etc. it is doing automatically/under the control of users, whenever a single change occurs and a delta event is triggered to keep up to date as appropriate. 258 | 259 | 260 | # Software Specification 261 | 262 | > _A detailed software description which can serve as a basis for a design or implementation._ 263 | 264 | As a knowledge provider partner, UCL puts forward the following that can serve as a base/prior work for the future development of the user requirements above & those mentioned in the grant work packages. The below are not "user requirements" per se, but more "technical requirements/background" based on the [speckle platform](http://github.com/speckleworks) which was previously developed as part of UCL within an H2020 grant. 265 | 266 | ## Delta Container Specification (WP3) 267 | - Authorship: the speckle server implements a [discretionary access control](https://en.wikipedia.org/wiki/Discretionary_access_control) layer that assigns an owner to each created resource (object, object collection, etc.). This is implemented via the speckle's api authentication mechanism. 268 | - Encryption (SSL) is usually handled by the proxy server using standard `letsencrypt` certificates (and is not part of the implementation) 269 | - Encryption at rest is usually handled by the database (mongodb) deployment (and is not part of the implementation). See the [following documentation](https://docs.mongodb.com/manual/core/security-encryption-at-rest/). 270 | - Regarding container specification: see below. 271 | 272 | ## REST API Specification (WP4) 273 | 274 | Speckle already has an api contract written in OpenApi v3, coupled with generated documentation of the endpoints. 275 | - CRUD definitions: 276 | - Objects can be found [here](https://speckleworks.github.io/SpeckleSpecs/#speckle-objects) 277 | - Streams (object collections) can be found [here](https://speckleworks.github.io/SpeckleSpecs/#speckle-streams) 278 | 279 | Delta updates and diffing is currently managed at the client level and operate on the object collection rather than individual objects. These can be enhanced to contain more granular update notifications about single/multiple delta updates. 280 | 281 | Nevertheless, it is important to note that various client (CAD software) implementations will require different types of diffing to occur based, hence we recommend not implementing these behaviours server-side beyond a common-sense approach. 282 | 283 | 284 | ## Server Architecture (WP5) 285 | 286 | Publisher-subscriber design: 287 | - The speckle server exposes both the REST API mentioned above, as well as a WS server 288 | - All clients connect as either publishers or subscribers to the WS server on a resource-based classification, given permission access levels. 289 | - The server propagates messages to all subscribers, but is also able to handle individual client-to-client messages. 290 | 291 | Distributed architecture: The speckle server is stateless - all api calls are authenticated and WS messages are coordinated across all server instances. 292 | 293 | ### Other notes: 294 | 295 | #### Data Schemas/Standards 296 | 297 | - Speckle is [schema agnostic](https://speckle.works/log/schemasandstandards/), supporting out of the box several object models developed internally by various companies. 298 | - Furthermore, there is a planned integration with the [BHoM](http://bhom.xyz) object model. 299 | 300 | ### Links: 301 | - [Speckle Server](https://github.com/speckleworks/SpeckleServer) 302 | - [Speckle Api Specifications](https://speckleworks.github.io/SpeckleSpecs/#speckle) 303 | - Speckle Client Integrations: 304 | - [Rhino & Grasshopper](https://github.com/speckleworks/SpeckleRhino) 305 | - [Dynamo](https://github.com/speckleworks/SpeckleDynamo) 306 | - Revit, Unity, GSA, and others are WIP 307 | 308 | 309 | # Test Cases Specification 310 | 311 | As identified in the User Story definitions above, the AECDelta specifications will need to be designed to be compatible, support or facilitate a wide range of data sets, model formats and types of information. 312 | 313 | As a high level specification - data types ranging from schema-less raw data, through well defined proprietary formats, to API exposed object models - are required. 314 | 315 | Depending on the data type. The scale at which a meaningful Delta/Change can, or is appropriate to, be detected will vary. For instance 316 | - Unstructured - file or entire stream level deltas may be possible 317 | - Structured - object level deltas may be possible 318 | 319 | 320 | List of potential data sets and test cases: 321 | 322 | 1. Raw data, e.g. csv, .txt , unstructured primitive data 323 | 1. Custom schemas, JSON 324 | 1. Geometry formats 325 | 1. IFC 326 | 1. Analysis model representations (e.g. Structural FEM, CFD model, Thermal Environmental models) 327 | 1. Multidisciplinary BIM models - building scale 328 | 1. Multidisciplinary GIS models - infrastructure scale 329 | 1. Fabrication model representation 330 | 331 | 332 | A deliberate (and possible separate) consideration will need to be made for __"large"__ data sets. Test sets to consider: 333 | 334 | 335 | I. Point Cloud from laser scan 336 | II. Bulk simulation results 337 | --------------------------------------------------------------------------------