ARchi VR Extensions

Revision Info: Documentation for ARchi VR Version 2.3 - June 2020

Table of Contents

Up to ARchi VR Content Creation


Introduction to Custom App Extensions

ARchi VR supports five types of App extensions:

Catalog, Service, Workflow, and Curation extensions can be provided by third parties as custom expansions for end-users of ARchi VR.

URL Schemes for Extensions in ARchi VR

Universal links are used to reference ARchi VR content. When ARchi VR isn’t installed on the user's device, some (not necessarily all) information is presented as webpage. The following URL schema provides a way to reference custom extension resources inside the ARchi VR app with universal links.

https://service.metason.net/ar/ext/<path>

Checkout some examples of extensions and follow their Universal Links to see their representation as webpage while using a desktop browser.

App-specific URL

The following URL schema provides a way to reference customer-specific extension resources within ARchi VR.

archi://ext/<path>

The extension resources are managed centrally by Metason as references, but the content of the extensions is provided by third-party organizations via web URLs they manage themselves. Tapping such a URL on a website, in a message, or in an email will launch ARchi VR (when installed on the iOS device), then ask for permission to locally install the corresponding extensions.

Extension Resource

A custom extension resource will be provided as a JSON data structure. The following example is an extension for a custom catalog

[ { "id" : "com.company.archi.catalog", "type" : "Catalog", "name" : "Company Product Catalog", "desc" : "3D Catalog for product line XYZ", "orga" : "Company", "email" : "support@company.com", "orgaURL" : "https://www.company.com", "logoURL" : "https://www.company.com/images/logo.png", "dataURL" : "https://www.company.com/catalog/catalog.json", "dataTransfer" : "GET:JSON", "validUntil" : "2021-06-01", "ref" : "", "preCondition" : "" } ]

An extension resource is a list of extensions. It can therefore provide several catalogs, services, workflows, and curations within a single extension resource.

Individualization

The "ref" value can be used to set an individual reference to the extension, e.g., as version, country, session or customer reference. This reference can either be specified within the JSON data of the extension or can be set dynamically via a ref parameter in the calling URL, such as

https://service.metason.net/ar/ext/<path>?ref=___ archi://ext/<path>?ref=___

If the "ref" value of an extension is not empty, it will be added to the user's references on execution. The user's references can then later be used at the backend to resolve identification.

Static Content

The content for extensions has to be provided by the customer, and the content for each extension type (e.g. catalog, workflow, service, and curation) is explained in the chapters below. If the extension resource defines "dataTransfer" : "GET:JSON" or "dataTransfer" : "GET:HTML" (for curations) then the dataURL will be called to grab the corresponding content from a static Web URL (hosted by the customer).

Custom Application Logic for Individual Content

To generate individual content, your own Web service can react on data sent via an URL as multi-part POST request by the ARchi VR app. By defining "dataTransfer" : "POST:SPACE" for example, the call to the dataURL will provide the current room captured by ARchi VR as a JSON data structure.

The following data can be posted to Web services:

POST:SPACE, POST:USER, POST:CAM, POST:SVG, POST:OBJ, POST:WEB3D, POST:PHOTO, POST:DOCS

The different data types can be cumulated in the dataTransfer description:

You may use an URL request analyzer such as RequestBin to test the content your extension is sending via HTTP POST by temporarly pointing the dataURL to a request bin. (Hint: the free version of RequestBin has a size limit of 100 kB, therefore POST:PHOTO may fail.)

Preconditions

Workflows can define a precondition when they should be triggered automatically depending of the saved space data. Additionally Workflows may be triggered manually in a room's Meta View within ARchi VR.

Services should define preconditions whether they are valid to execute in the current situation of the captured space (if not the service is disabled).

Preconditions will evaluate in the app on the current space data structure (the same which is sent as JSON when POST:SPACE is defined as data transfer mode).

The data elements accessible from a precondition in the Space data structure are:

type // space type as string subtype // space subtype as string floor // material, ceiling height walls // array of wall elements cutouts // array of cutouts (openings such as doors and windows) items // array of items links // array of document links location // address, countryCode, longitude, latitude

If the precondition is evaluated during an AR session it has additionally access to the current AR session context info:

device // type, screen size user // position, rotation, id, refs, optional: name time // current time and date data // temporary data variables

If you install the Developer Extension you have access to two Services:

Check out available data elements and their values by analyzing the inspector or the saved context file.

Preconditions are formulated as predicates according to the specification of the Predicate Format String Syntax by Apple. If precondition is empty it will evaluate as true. Strings in preconditions should be single quoted. See the following examples.

The following predicate checks that the space is a single room (and not multiple rooms):

"preCondition" : "subtype == 'Single Room'"

The following predicate checks that the space contains at least one wall with concrete as material:

"preCondition" : "ANY walls.material == 'Concrete'"

The following predicate checks that the space contains at least one item of type "Zone" with subtype "Damaged Area":

"preCondition" : "ANY items.subtype == 'Damaged Area'"

The following predicate checks for two conditions using the AND clause:

"preCondition" : "walls.@count > 2 AND walls[0].floorId BEGINSWITH 'D96B5F4A'"

Save Content to iCloud Drive

The following data can be saved to iCloud Drive and will be shared with your other devices:

POST:SPACE, POST:SVG, POST:OBJ, POST:WEB3D, POST:PHOTO

In your extension, set "dataURL" : "https://www.icloud.com/iclouddrive/" to declare iCloud Drive as the target for storing the corresponding files. The ARchi VR app has preinstalled workflow extensions for exporting the 2D floor plan as SVG, and for exporting the 3D model as OBJ (Wavefront geometry) and MTL (Wavefront material) files.

Howto create and publish ARchi VR Extensions

If you want to provide customer-specifc extensions for ARchi VR, please contact support@metason.net for negotiating the terms and conditions to host a reference to your extension resources. Your extension may be published on an extensions listing that allows users to activate extensions from within ARchi VR.

You can start creating AR content using the free Developer extension.

If you need professional support to develop your specific catalog, workflow, service, or curation for ARchi VR, please contact one of the partners listed on the ARchi VR Web Site.


Catalog Extension

Catalogs are typically referenced by static URLs defined in the dataURL parameter and return a JSON data structure listing all catalog elements such as:

[ { "name": "Haller Table 1750x750", "manufacturer": "USM", "category": "Interiour", "subtype": "Table", "tags": "design furniture office table", "modelURL": "https://archi.metason.net/catalog/3D/Haller%20Table%201750x750.usdz", "imgURL": "https://archi.metason.net/catalog/img/Haller%20Table%201750x750.png", "webURL": "https://www.usm.com", "source": "3d.io", "srcRef": "7740c380-0ade-48cc-98d9-665be984c4ae", "wxdxh": "1.75x0.75x0.76", "scale": "0.01" }, { "name": "Refrigerator", "manufacturer": "", "category": "Equipment", "subtype": "Machine", "tags": "fridge", "modelURL": "https://archi.metason.net/catalog/3D/Refridgerator.usdz", "imgURL": "https://archi.metason.net/catalog/img/Refridgerator.png", "webURL": "", "source": "Sketchup 3D Warehouse", "srcRef": "https://3dwarehouse.sketchup.com/model/ad6bd7e24e5bc25f3593835fe348a036/Siemens-Refrigerator", "wxdxh": "0.60x0.59x1.85", "scale": "0.0001" } ]

3D Catalog Item

The catalog selector filters catalog entries by category (Any / Interiour / Equipment / Commodity) and to search by name, manufacturer, and tags. The category (type) of 3D catalog items include:

"Building" // immobile element that belongs to building structure "Equipment" // immobile, stationary equipment "Interiour" // furniture "Commodity" // daily used items

The image referenced by imgURL should be 128x128 pixels. This image is used in the catalog selector within the app. The catalog selector is available in the main view and in the AR view of the ARchi VR app.

   

The 3D file referenced by modelURL will be used in the AR view of the ARchi VR app and should be in one of the following formats:

There are a number of useful tools to create content for catalogs:

To support the visualization of catalog models in 3D and VR (in addition to AR), provide a ../gltf/filename.glb file in parallel to the ../3D/filename.usdz file.

Steps for converting 3D models from Sketchup 3D Warehouse:

Image-based Catalog Element

If modelURL references an image (instead of a 3D file) and defines "subtype": "Panel", the catalog item will be interpreted as an image panel (see 3rd image above). An image-based catalog item does look like this:

{ "name": "Information", "manufacturer": "", "category": "Equipment", "subtype": "Panel", "tags": "sign", "modelURL": "https://service.metason.net/ar/content/signs/img/info.png", "imgURL": "https://service.metason.net/ar/content/signs/img/info.png", "source": "", "wxdxh": "0.2x0.0x0.2" }

A file referenced by modelURL for an image panel should be in one of the following formats:


Service Extension

A service extension facilitates adding interactive or animated items to the AR scene. A service is specified as an action that executes one or more tasks. A service can be selected by the user during an AR session by wiping the gear wheel from right to left. A service selector will appear that lists all installed AR services.

 

A service extension looks like this:

[ { "type" : "Service", "id" : "net.metason.service.test1", "name" : "Test 1 Service", "desc" : "Test static GET:JSON service", "orga" : "Metason", "email" : "support@metason.net", "dataURL" : "https://service.metason.net/ar/content/test1/action.json", "logoURL" : "https://www.metason.net/images/Metason_128x128.png", "orgaURL" : "https://www.metason.net", "validUntil" : "2021-12-30", "preCondition" : "", "dataTransfer" : "GET:JSON" } ]

The image referenced by logoURL should have be 128x128 pixels.

Action

A service call results in an Action with the following JSON data structure:

{ "items" : [ { "id" : "com.company.archi.meter", "vertices" : [ [ 0.0, 0.0, 0.0 ], [ 1.0, 0.0, 0.0 ] ], "type" : "Route", "subtype" : "Distance", } ], "tasks" : [ { "do" : "add", "id" : "com.company.archi.meter", "ahead" : "-0.5 0.0 -1.0" } ] }

The definition of items and tasks that can be used in Actions are declared in ARchi VR Actions.


Workflow Extension

The result of a workflow call is a link to a webpage. The result of a workflow could present:

The result of a workflow is returned to the ARchi VR app as a web link in the following JSON data structure:

{ "id" : "com.company.archi.offer.12345", "title" : "Offer", "orga" : "Company", "extensionId" : "com.company.archi.offer", "webURL" : "https://www.company.com/archi/workflow/offer?spaceId=1234&customerId=2345", "logoURL" : "https://www.company.com/archi/workflow/logo.png", "validUntil" : "2021-05-25" }

The image referenced by logoURL should be 128x128 pixels.

The user can then view the webpage within the app. Additionally, the web URL to the workflow result can be sent to the customer as a link via email, for example.

The following example shows the output of the "Space Analysis" worlflow as a webpage including meta data and 2D floorplan of a space captured by ARchi VR:


Curation Extension

An AR curation is a coherent set of webpages and AR sessions which can be followed by tapping the corresponding links.

Curated AR content can be initiated via universal links provided by registered organisations.

A curation extension looks like this:

[ { "type" : "Curation", "id" : "com.company.archi.intro", "name" : "Introduction", "desc" : "Introduction to something", "orga" : "Company Inc.", "email" : "support@company.com", "dataURL" : "https://www.company.com/ar/intro/index.html", "logoURL" : "https://www.company.com/ar/images/logo.png", "orgaURL" : "https://www.company.com", "validUntil" : "2021-12-30", "preCondition" : "", "dataTransfer" : "GET:HTML" } ]

The image referenced by logoURL should have be 128x128 pixels.

The HTML webpage referenced by dataURL is the start page shown for the curation.

Within a HTML webpage, an AR session can be opened via a archi://openwith/_ link. The referenced path after openwith/ is relative to the dataURL of the curation.

<a href="archi://openwith/start.json"> Start an AR Session. </a>

Example of an AR Curation

ARchi VR comes with a pre-installed AR Curation called "Welcome".


Developer Extension

The Developer extension enables the creation of extensions via iCloud Drive without needing a web server. It also allows for local, on-device testing. You can implement static Catalogs, Services, Workflows, and Curations on your desktop Mac/PC using your favourite JSON editor while all coresponding files are automatically synchronized to ARchi VR on your own iOS device for immediate testing. Non-Mac users may install iCloud for Windows.

If you want to get a free Developer extension to start developing extensions for ARchi VR, please send an email to support@metason.net with the following information:

The person referenced by the email will be considered the official contact person and/or facilitator concerning technical support.

You will then get an email that includes an app-specific URL which you should open on an iOS device with ARchi VR already installed. This will then install your Developer extension and you will find two files in iCloud Drive/ARchi VR/dev/ (on your iOS device as well as synchronized on your Mac/PC iCloud Drive):

In order to start creating your own AR content also check out the sample extensions at examples.

For the deployment of locally-developed extensions, you have to transfer your files to a web server and register your content for the ARchi VR App.


Back to ARchi VR Content Creation


Copyright © 2020 Metason - All rights reserved.