README.md

*This repository is part of the outcomes of the Specialist Task Force 620 focusing on the authoring of a World Representation as part of the ETSI ISG Augmented Reality Framework architecture (https://www.etsi.org/deliver/etsi_gs/ARF/001_099/003/01.01.01_60/gs_ARF003v010101p.pdf).*
*The set of the World Representation authoring components includes:*

*•	The C++ and C# source code for servers and clients  generated from OpenAPI available here (https://forge.etsi.org/rep/arf/arf005)*

*•	A Unity plugin and a Unity editor for authoring and accessing a World Representation hosted on a World Storage server.*

*All these components are available under the ETSI Labs group “World Storage API Helpers”: https://labs.etsi.org/rep/arf/world-storage-api-helpers*

*If you wish to contribute to this project or any other projects in the context of the [ETSI ISG Augmented Reality Framework architecture](https://www.etsi.org/committee/1420-arf), please refer to the ["How to get involved in an ISG" section on the ETSI website](https://www.etsi.org/how-to-get-involved-in-an-isg)*

---

# Description

This is a small project generating the C# client code and DLLs for the ISG ARF World Storage.

# How to checkout

This project contains a submodule. This submodule contains the OpenAPI specification of the ISG ARF World Storage. To correctly compile the project you also need to checkout the submodule. See git submodules (https://git-scm.com/book/en/v2/Git-Tools-Submodules) for more information.

The simplest way to check out the project including the submodule is to use the following command:

    git clone --recurse-submodules https://labs.etsi.org/rep/arf/world-storage-api-helpers/world-storage-csharp-client.git

# How to update the API specification

The referenced submodule contains the OpenAPI specification of the ISG ARF World Storage. To checkout the newest version of it use the following commands:

    cd openapi
    git checkout master
    cd ..

# Preparing the yaml file (merging)

Before generating the code you must put all referenced YAML file together, otherwies you will get an error in NSwag.For this, we uses a custom tool 'openapi-merger'. This tool only includes file-referenced ref shemas, and do not change local ones (as 'swagger-merger' will do!).

    npm install -g openapi-merger 

## Patching the openfile JS command

If you have some white char in your path/filename, openapi-merger will failed because of an error with the %20 (white pace) in the pathname. To avoid this, please add a line to the js script 'yaml.js' located in your npm path e.g. 

    C:\Users\<YOU>\AppData\Roaming\npm\node_modules\openapi-merger\src

In the readYAML function, the first line:

```c#
function readYAML(filePath) {
    filePath = filePath.replace ("%20", " ");  // White-space bug fixe provided by SylR (FraunhoferHHI)
    const str = "" + fs.readFileSync(filePath, "utf8");
    return yaml.load(str);
}
```
## Using it

To start the merging go into the definition folder of the API and execute this:

    cd openapi/API/worldstorage
    npx openapi-merger -i worldstorageopenapi.yaml -o worldstorageopenapi_merged.yaml 

and also here:

    cd openapi/API/worldanalysis
    npx openapi-merger -i worldanalysisopenapi.yaml -o worldanalysisopenapi_merged.yaml 

Don't forget to change the filename in the JSON config file for NSwag to the merged one!!!

# Installing NSwag

    npm install nswag -g

You can check the version with

    nswag version

# Code Generation

To generate the c# code use the following commands:

    nswag run WorldStorageNSwag.json
    nswag run WorldAnalysisNSwag.json

The generated C# modules (one per definition file) are then contained in the folder `client/csharp-nswag`.

# How to proceed then?

Copy the cs file(s) to your CSharp project or Unity asset folder

## Unity

Add the NewtonSoft package:
"com.unity.nuget.newtonsoft-json": "3.2.1",

Change the Unity prefs to use the NET Framework (not only 2.1)

Add a file "csc.rsp":
-r:System.ComponentModel.DataAnnotations.dll