diff --git a/docs/assets/images/grid-for-geometry-prop.png b/docs/assets/images/grid-for-geometry-prop.png new file mode 100644 index 000000000..8532b8935 Binary files /dev/null and b/docs/assets/images/grid-for-geometry-prop.png differ diff --git a/docs/dsp-tools-usage.md b/docs/dsp-tools-usage.md index 44d9b4f92..e44f3e1ed 100644 --- a/docs/dsp-tools-usage.md +++ b/docs/dsp-tools-usage.md @@ -89,18 +89,32 @@ dsp-tools xmlupload [options] xml_data_file.xml The following options are available: -- `-s` | `--server` _server_: URL of the DSP server (default: 0.0.0.0:3333) -- `-u` | `--user` _username_: username used for authentication with the DSP API (default: root@example.com) -- `-p` | `--password` _password_: password used for authentication with the DSP API (default: test) -- `-V` | `--validate`: If set, only the validation of the XML file is performed. -- `-i` | `--imgdir` _dirpath_: path to the directory where the bitstream objects are stored (default: .) -- `-S` | `--sipi` _SIPIserver_: URL of the SIPI IIIF server (default: http://0.0.0.0:1024) -- `-I` | `--incremental` : If set, IRIs instead of internal IDs are expected as reference to already existing resources on DSP -- `-v` | `--verbose`: If set, more information about the uploaded resources is printed to the console. +- `-s` | `--server` (optional, default: `0.0.0.0:3333`): URL of the DSP server +- `-u` | `--user` (optional, default: `root@example.com`): username used for authentication with the DSP API +- `-p` | `--password` (optional, default: `test`): password used for authentication with the DSP API +- `-i` | `--imgdir` (optional, default: `.`): path to the directory where the bitstream objects are stored +- `-S` | `--sipi` (optional, default: `http://0.0.0.0:1024`): URL of the SIPI IIIF server +- `-I` | `--incremental` (optional) : If set, IRIs instead of internal IDs are expected as reference to already existing resources on DSP +- `-V` | `--validate` (optional): If set, the XML file will only be validated, but not uploaded. +- `-v` | `--verbose` (optional): If set, more information about the process is printed to the console. + +The command is used to upload data defined in an XML file onto a DSP server. The defaults are intended for local +testing: +```bash +dsp-tools xmlupload xml_data_file.xml +``` + +will upload the XML file on `localhost` for local viewing. It assumes that DSP-API has been started up with the default +settings, and that potential `` tags contain file paths that are relative to the working directory from where +`dsp-tools` is called from. + +When uploading data to a remote DSP server, there are three relevant URLs you should know about: -The command is used to upload data defined in an XML file onto a DSP server. The following example shows how to upload -data from the XML file `xml_data_file.xml` to the DSP server `https://admin.dasch.swiss`: + - Subdomain `admin` stands for the DSP-APP frontend that you look at in your browser + - Subdomain `api` stands for the DSP-API (where dsp-tools sends its data to) + - Subdomain `iiif` stands for the SIPI-server interface (where dsp-tools sends the multimedia files to) +This means that for uploading data to a DSP server on the domain `dasch.swiss`, you have to type the following: ```bash dsp-tools xmlupload -s https://api.dasch.swiss -u root@example.com -p test -S https://iiif.dasch.swiss xml_data_file.xml ``` diff --git a/docs/dsp-tools-xmlupload.md b/docs/dsp-tools-xmlupload.md index 3ceea4dba..6356e97d2 100644 --- a/docs/dsp-tools-xmlupload.md +++ b/docs/dsp-tools-xmlupload.md @@ -221,17 +221,15 @@ A complete `` element may look as follows: ``` -The `` element contains a property element (e.g. ``) for each property class (i.e. data field) -describing the resource. The property element itself contains one or several value elements (e.g. ``) and must -have an attribute `name` with the name of the property as defined in the project specific ontology. - -Example for a property element of type text (``) with two value elements ``: +For every property that the ontology requires, the `` element contains one property +element (e.g. ` - Dies ist eine Übersetzung. - Dies ist eine weitere Übersetzung. - + + 4711 + 1 + ``` The following property elements exist: @@ -269,7 +267,7 @@ Supported file extensions: | Representation | Supported formats | |-----------------------------|----------------------------------------| | `ArchiveRepresentation` | ZIP, TAR, GZ, Z, TAR.GZ, TGZ, GZIP, 7Z | -| `AudioRepresentation` | MP3, MP4, WAV | +| `AudioRepresentation` | MP3, WAV | | `DocumentRepresentation` | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX | | `MovingImageRepresentation` | MP4 | | `StillImageRepresentation` | JPG, JPEG, PNG, TIF, TIFF, JP2 | @@ -281,10 +279,11 @@ Attributes: - `permissions` : Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) -Example: - +Example of a public image inside a `StillImageRepresentation`: ```xml -postcards/images/EURUS015a.jpg + + postcards/images/EURUS015a.jpg + ``` @@ -306,16 +305,12 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -Example: - +Example of a public and a hidden boolean property: ```xml - true + true -``` - -```xml - + 0 ``` @@ -340,10 +335,10 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -A property with two color values would be defined as follows: +Example of a property with a public and a hidden color value: ```xml - #00ff66 + #00ff66 #ff00ff ``` @@ -389,16 +384,10 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -Example: - -```xml - - GREGORIAN:CE:2014-01-31 - -``` - +Example of a property with a public and a hidden date value: ```xml + GREGORIAN:CE:2014-01-31 GREGORIAN:CE:1930-09-02:CE:1930-09-03 ``` @@ -422,11 +411,11 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -Example: - +Example of a property with a public and a hidden decimal value: ```xml - 3.14159 + 3.14159 + 2.71828 ``` @@ -476,11 +465,27 @@ The following example defines a polygon: } ``` -Example of a `` element: - +Example of a property with a public polygon and a hidden rectangle: ```xml - - {"status":"active","type"="circle","lineColor"="#ff0000","lineWidth"=2,"points":[{"x":0.5,"y":0.5}],"radius":{"x":0.1,"y":0.0}} + + + { + "status": "active", "type": "polygon", "lineColor": "#ff3333", "lineWidth": 2, "original_index": 0, + "points": [{"x": 0.1725239616613418, "y": 0.1597222222222222}, + {"x": 0.8242811501597445, "y": 0.1458333333333333}, + {"x": 0.8242811501597445, "y": 0.8310185185185185}, + {"x": 0.1757188498402556, "y": 0.8240740740740740}, + {"x": 0.1757188498402556, "y": 0.1597222222222222}, + {"x": 0.1693290734824281, "y": 0.1643518518518518}] + } + + + { + "status": "active", "type": "rectangle", "lineColor": "#ff3333", "lineWidth": 2, "original_index": 0, + "points": [{"x": 0.080985915492957750, "y": 0.16741071428571427}, + {"x": 0.739436619718309900, "y": 0.72991071428571430}] + } + ``` @@ -509,11 +514,11 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -Example (city of Vienna): - +Example of a property with a public link to Vienna and a hidden link to Basel: ```xml - 2761369 + 2761369 + 2661604 ``` @@ -536,11 +541,11 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -Example: - +Example of a property with a public and a hidden integer value: ```xml - 4711 + 4711 + 1 ``` @@ -566,12 +571,11 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -Example: - +Example of a property with a public and a hidden interval value: ```xml - 60.5:120.5 - 61:3600 + 60.5:120.5 + 61:3600 ``` @@ -597,11 +601,11 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -Example: - +Example of a property with a public and a hidden list value: ```xml - physics + physics + nature ``` @@ -626,14 +630,11 @@ Attributes: - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -Example: - -If there is a resource defined as `...`, it can -be referenced as: - +Example of a property with a public link to `` and a hidden link to and ``: ```xml - 238807 + res_1 + res_2 ``` @@ -652,48 +653,33 @@ Attributes: The `` element has the following attributes: - `encoding`: either "utf8" or "xml" (required) - - `utf8`: The element describes a simple text without markup. The text is a simple UTF-8 string. - - `xml`: The element describes a complex text containing markup. It must follow the XML format as defined by the + - `utf8`: simple text without markup + - `xml`: complex text with markup. It must follow the XML format as defined by the [DSP standard mapping](https://docs.dasch.swiss/latest/DSP-API/03-apis/api-v2/xml-to-standoff-mapping/). - `permissions`: Permission ID (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not even view rights) - `comment`: a comment for this specific value (optional) -There are two variants of text: Simple (UTF8) and complex (XML). Within a text property, multiple simple and -complex text values may be mixed. Both simple and complex text values can be used inside all gui_elements -that are defined in an ontology (SimpleText, Richtext, Textarea, see [here](dsp-tools-create-ontologies.md#textvalue)). -But typically, you would use UTF8 in a SimpleText, and XML in Richtext or Textarea. - - -#### Simple text (UTF-8) - -An example for simple text: +Within a text property, multiple simple (UTF8) and complex (XML) text values may be mixed. +Both simple and complex text values can be used inside all `gui_element`s that are defined in an ontology (`SimpleText`, +`Richtext`, `Textarea`, see [here](dsp-tools-create-ontologies.md#textvalue)). But typically, you would use UTF8 in a +`SimpleText`, and XML in `Richtext` or `Textarea`. +Example of a public simple text and a hidden complex text: ```xml - Probe bei "Wimberger". Lokal in Wien? + Probe bei "Wimberger". Lokal in Wien? + + Bold text and a link to an ID + and a link to an IRI + ``` -If your text is very long, it is not advised to add XML-"pretty-print" whitespaces after line breaks. These -whitespaces will be taken into the text field as they are. - - -#### Text with markup (XML) +The complex text above contains a link to the resource `obj_0003`, which is defined in the same XML file. +It also contains a link to the resource `http://rdfh.ch/4123/nyOODvYySV2nJ5RWRdmOdQ`, which already exists on the DSP server. -dsp-tools assumes that for markup (standoff markup), the -[DSP standard mapping](https://docs.dasch.swiss/latest/DSP-API/03-apis/api-v2/xml-to-standoff-mapping/) is used (custom mapping is not yet -implemented). - -Example of a text containing a link to another resource: - -```xml - - The third object and a link. - -``` - -Please note that the `href` option within the anchor tag (``) points to an internal resource of the DSP and has to -conform to the special format `IRI:[res-id]:IRI` where [res-id] is the resource id defined within the XML import file. +For simple texts, it is not advised to add XML-"pretty-print" whitespaces or line breaks, because they will be taken +into the text field as they are. ### <time-prop> @@ -707,8 +693,8 @@ Attributes: #### <time> -The ` @@ -854,8 +833,40 @@ Example: ``` -Technical note: A `` is in fact a ``. But it is mandatory to use the + +The circle and polygon are created with the following syntax: +```json +{ + "status": "active", + "type": "circle", + "lineColor": "#ff1100", + "lineWidth": 5, + "points": [{"x":0.5,"y":0.3}], + "radius": {"x":0.1,"y":0.1} // vector (0.1, 0.1) +}, +{ + "status": "active", + "type": "polygon", + "lineColor": "#ff1100", + "lineWidth": 5, + "points": [{"x": 0.4, "y": 0.6}, + {"x": 0.5, "y": 0.9}, + {"x": 0.8, "y": 0.9}, + {"x": 0.7, "y": 0.6}] +} +``` + +The underlying grid is a 0-1 normalized top left-anchored grid. The following coordinate system shows the three shapes +that were defined above: +![grid-for-geometry-prop](./assets/images/grid-for-geometry-prop.png) + + +Technical notes: + - A `` is in fact a ``. But it is mandatory to use the shortcut, so that the XML file can be validated more precisely. + - In the SALSAH data, there is also a key named `original_index` in the JSON format of all three shapes, but it doesn't + seem to have an influence on the shapes that TANGOH displays, so it can be omitted. + ### `` `` is a resource linking together several other resources of different classes. It must have the following diff --git a/testdata/test-data-systematic.xml b/testdata/test-data-systematic.xml index be00d50f7..8d3a34041 100644 --- a/testdata/test-data-systematic.xml +++ b/testdata/test-data-systematic.xml @@ -157,7 +157,7 @@ permissions="res-default"> Dies ist ein einfacher Text ohne Markup - Nochmals ein einfacher Text + Ein XML-formatierter Text mit Markup @@ -292,7 +292,7 @@ - @@ -305,20 +305,19 @@ { "status": "active", - "type": "rectangle", - "lineColor": "#ff3333", - "lineWidth": 2, - "points": [ - {"x":0.080985915492957750,"y":0.16741071428571427}, - {"x":0.739436619718309900,"y":0.72991071428571430} - ], - "original_index": 0 + "type": "polygon", + "lineColor": "#ff1100", + "lineWidth": 5, + "points": [{"x": 0.4, "y": 0.6}, + {"x": 0.5, "y": 0.9}, + {"x": 0.8, "y": 0.9}, + {"x": 0.7, "y": 0.6}] } - This is a rectangle-formed region of interest of an image. It is also displayed as Annotation. + This is a polygon-formed region of interest of an image. It is also displayed as Annotation. @@ -659,7 +658,7 @@ - @@ -675,13 +674,40 @@ { "status": "active", "type": "rectangle", - "lineColor": "#ff3333", - "lineWidth": 2, + "lineColor": "#ff1100", + "lineWidth": 5, "points": [ - {"x":0.080985915492957750,"y":0.16741071428571427}, - {"x":0.739436619718309900,"y":0.72991071428571430} - ], - "original_index": 0 + {"x":0.1,"y":0.7}, + {"x":0.3,"y":0.2} + ] + } + + + + image_thing_0 + + + #5d1f1e + + + + + + + This is a circle-formed region of interest of an image. It is also displayed as Annotation. + + + + + { + "status": "active", + "type": "circle", + "lineColor": "#ff1100", + "lineWidth": 5, + "points": [{"x":0.5,"y":0.3}], + "radius": {"x":0.1,"y":0.1} }