Auto generate xsd images

CONTRIBUTING.adoc

@@ -48,6 +48,17 @@ where `<fmi-standard>` is the path to the cloned repository
 
 The generated `docs/index.html` can be viewed with any modern web browser.
 
+== Changing the XSD Schemas
+
+Some of the images used in the FMI Specification are automatically generated from the XSD Schemas used.
+When you make changes to the XSD Schema, it is your responsibility to ensure that the images displayed in the specification remain consistent.
+
+To re-generate the images, run the following:
++
+  PowerShell -Command "<fmi-standard>\bin\generate_figures.ps1"
++
+where `<fmi-standard>` is the path to the cloned repository.
+
 == Using the issue tracker
 
 The issue tracker is the preferred channel for <<Bug reports>>, <<Feature requests>> and submitting <<Pull requests>>, but please respect the following restrictions:

bin/.gitignore

@@ -0,0 +1 @@
+/xsddiagram

bin/generate_figures.ps1

@@ -0,0 +1,79 @@
+$pngOutDir = Resolve-Path (Join-Path $PSScriptRoot "..\docs\images\gen")
+$generatorDir = Join-Path $PSScriptRoot "xsddiagram"
+$generator = Join-Path $generatorDir "XSDDiagramConsole.exe"
+
+function Clear-Gen() {
+	# Get-ChildItem $pngOutDir\*
+	Remove-Item $pngOutDir\*
+}
+
+function Get-XSDDiagram() {
+	if (-Not (Test-Path $generator))
+	{
+		$uri = "https://github.com/clagms/xsddiagram/releases/download/XSDDiagram_1.2_FMI/XSDDiagram_1.2_FMI.zip"
+		$zipFile = "XSDDiagram-Binary.zip"
+		Invoke-WebRequest -Uri $uri -OutFile $zipFile
+		Expand-Archive -Path $zipFile -DestinationPath $generatorDir -Force
+		Remove-Item -Path $zipFile
+	}
+}
+
+function Check-Existing() {
+	Param(
+		$file
+	)
+	If (Test-Path $file -PathType Leaf) {
+		Write-Output "Error: File already exists."
+		Exit 1
+	}
+}
+
+function Export-Schema() {
+	Param(
+		$element,
+		$expand,
+		$schema = "fmi3ModelDescription.xsd",
+		$outName = $element + "_schema.png",
+		[switch] $preview = $false
+	)
+	Write-Output "Generating schema for $element..."
+	$out = Join-Path $pngOutDir $outName
+	Check-Existing $out
+	& $generator -o $out -r $element -e $expand -d -c -z 300 -a -no-gui -y (Resolve-Path (Join-Path $PSScriptRoot "..\schema\$schema"))
+	if ($preview) {
+		Start-Process $out
+	}
+}
+
+Clear-Gen
+Get-XSDDiagram
+
+Export-Schema fmiModelDescription 1
+Export-Schema UnitDefinitions 3
+Export-Schema BaseUnit 2
+Export-Schema DisplayUnit 2
+Export-Schema TypeDefinitions 2
+Export-Schema Float64 3 -schema fmi3Type.xsd
+Export-Schema Int32 3 -schema fmi3Type.xsd
+Export-Schema Boolean 3 -schema fmi3Type.xsd
+Export-Schema Binary 3 -schema fmi3Type.xsd
+Export-Schema Enumeration 3 -schema fmi3Type.xsd
+Export-Schema Clock 3 -schema fmi3Type.xsd
+Export-Schema LogCategories 3
+Export-Schema DefaultExperiment 1
+Export-Schema Terminals 2
+Export-Schema TerminalMemberVariable 1
+Export-Schema TerminalStreamMemberVariable 1
+Export-Schema GraphicalRepresentation 2
+Export-Schema VendorAnnotations 2
+Export-Schema ModelVariables 2
+Export-Schema fmi3VariableBase 1
+Export-Schema Float64 1 -schema fmi3Variable.xsd -outName "Variable_Float64_schema.png"
+Export-Schema Int32 1 -schema fmi3Variable.xsd -outName "Variable_Int32_schema.png"
+Export-Schema Boolean 1 -schema fmi3Variable.xsd -outName "Variable_Boolean_schema.png"
+Export-Schema Binary 1 -schema fmi3Variable.xsd -outName "Variable_Binary_schema.png"
+Export-Schema Enumeration 1 -schema fmi3Variable.xsd -outName "Variable_Enumeration_schema.png"
+Export-Schema Annotations 2
+Export-Schema ModelStructure 2
+Export-Schema ModelExchange 2
+Export-Schema BasicCoSimulation 2

docs/2_2_common_schema.adoc

@@ -111,7 +111,7 @@ This is the root-level schema file and contains the following definition (the fi
 Data is defined by attributes to these elements):
 
 [[system_overview]]
-image::images/fmiModelDescription_schema.png[]
+image::images/gen/fmiModelDescription_schema.png[]
 
 On the top level, the schema consists of the following elements (see xref:system_overview[figure above]).
 _[Note that elements `<ModelVariables>` and `<ModelStructure>` are mandatory, whereas `<UnitDefinitions>`, `<TypeDefinitions>`, `<LogCategories>`, `<DefaultExperiment>`, and `<VendorAnnotation>` are optional._
@@ -163,8 +163,6 @@ The details of these elements are defined in <<ModelExchange>> and <<fmi-for-bas
 
 The XML attributes of `fmiModelDescription` are:
 
-image::images/fmiModelDescription_schema_2.png[width=80%, align="center"]
-
 [cols="1,3",options="header"]
 |====
 |Attribute-Name
@@ -366,7 +364,7 @@ _The approach used here is slightly different than FMI 1.0 to reduce the need fo
 
 Element `UnitDefinitions` of `fmiModelDescription` is defined as:
 
-image::images/UnitDefinitions_schema.png[]
+image::images/gen/UnitDefinitions_schema.png[]
 
 It consists of zero or more `Unit` definitions.
 _[If no units are defined, element `<UnitDefinitions>` must not be present._
@@ -378,7 +376,7 @@ _Since there is no standard to represent units in strings, and there are differe
 
 Optionally, a value given in unit `Unit` can be converted to a value with respect to unit `BaseUnit` utilizing the conversion `factor` and `offset` attributes:
 
-image::images/BaseUnit_schema.png[width=50%, align="center"]
+image::images/gen/BaseUnit_schema.png[width=50%, align="center"]
 
 Besides `factor` and `offset`, the `BaseUnit` definition consists of the exponents of the 7 SI base units `kg`, `m`, `s`, `A`, `K`, `mol`, `cd`, and of the exponent of the SI derived unit `rad`.
 _[Depending on the analysis/operation carried out, the SI derived unit `rad` is or is not utilized, see discussion below._
@@ -537,7 +535,7 @@ _]_
 
 Additionally to the unit definition, optionally a set of display units can be defined that can be utilized for <<input>> / <<output>> of a value:
 
-image::images/DisplayUnit_schema.png[width=80%, align="center"]
+image::images/gen/DisplayUnit_schema.png[width=80%, align="center"]
 
 A `DisplayUnit` is defined by `name`, `factor` and `offset`.
 The attribute `name` must be unique with respect to all other `names` of the `DisplayUnit` definitions of the same `Unit` [(different `Unit` elements may have the same `DisplayUnit` names)].
@@ -571,20 +569,27 @@ The schema definition is present in a separate file `fmi3Unit.xsd`.
 
 Element `TypeDefinitions` of `fmiModelDescription` is defined as:
 
-image::images/TypeDefinitions_schema.png[width=90%, align="center"]
+image::images/gen/TypeDefinitions_schema.png[width=90%, align="center"]
 
+// TODO: This description is outdated.
 This element consists of a set of `SimpleType` definitions according to schema `fmi3SimpleType` in file `fmi3Type.xsd`.
 One `SimpleType` has a type `name` and `description` as attributes.
 Attribute `name` must be unique with respect to all other elements of the `TypeDefinitions` list.
 Furthermore, `name` of a `SimpleType` must be different to all `name` attributes of variables _[if the same names would be used, then this would nearly always give problems when importing the FMU in an environment such as Modelica, where a type name cannot be used as instance name]_.
 Additionally, one variable type element must be present.
-They have the following definitions:
+Each variable type has its own attributes which can be consulted in the schema.
+The following are representative examples:
+
+image::images/gen/Float64_schema.png[width=60%, align="center"]
+
+image::images/gen/Int32_schema.png[width=60%, align="center"]
 
-image::images/Real_schema.png[width=50%, align="center"]
+image::images/gen/Boolean_schema.png[width=60%, align="center"]
 
-image::images/Integer_schema.png[width=50%, align="center"]
+image::images/gen/Binary_schema.png[width=60%, align="center"]
+
+image::images/gen/Enumeration_schema.png[width=60%, align="center"]
 
-image::images/Enumeration_schema.png[width=80%, align="center"]
 
 These definitions are used as default values in variable elements _[in order that, say, the definition of a `Torque` type does not have to be repeated over and over again]_.
 The attributes and elements have the following meaning:
@@ -733,13 +738,13 @@ If `strict = true` it is required to provide values for `intervalCounter`, `shif
 |====
 
 [#TypeDefinitions]
-image::images/clock_variable.png[]
+image::images/gen/Clock_schema.png[width=60%, align="center"]
 
 ==== Definition of Log Categories (LogCategories) [[definition-of-log-categories]]
 
 Element `LogCategories` of `fmiModelDescription` is defined as:
 
-image::images/LogCategories_schema.png[width=70%, align="center"]
+image::images/gen/LogCategories_schema.png[width=70%, align="center"]
 
 `LogCategories` defines an unordered set of category strings that can be utilized to define the log output via function <<logMessage>>, see <<creation-destruction-and-logging>>.
 A tool is free to use any `normalizedString` for a category value.
@@ -797,7 +802,7 @@ _The approach introduced in FMI 2.0 is therefore much more efficient.]_
 
 Element `DefaultExperiment` of `fmiModelDescription` is defined as:
 
-image::images/DefaultExperiment_schema.png[width=70%, align="center"]
+image::images/gen/DefaultExperiment_schema.png[width=70%, align="center"]
 
 `DefaultExperiment` consists of the optional default start time, stop time, relative tolerance, and step size for the first simulation run.
 A tool may ignore this information.
@@ -834,11 +839,9 @@ _This `connectorKind` is not related to the `terminalKind` or `variableKind` des
 
 Element `Terminals` of `fmiModelDescription` is defined as:
 
-image::images/fmiModelDescription_Terminals_Schema.png[width=40%, pdfwidth=40%, align="center"]
-
-All instances of `Terminal` have the type `fmi3Terminal` and are listed in the `Terminals` sequence:
+image::images/gen/Terminals_schema.png[width=80%, align="center"]
 
-image::images/fmiModelDescription_Terminals_Terminal_Schema.png[width=60%, pdfwidth=60%, align="center"]
+All instances of `Terminal` have the type `fmi3Terminal` and are listed in the `Terminals` sequence.
 
 The normalized string attribute `name` of the `Terminal` element is the instance name of the terminal. The terminal name must be unique on each level.
 //_[The terminal name may contain dots, to enable structured terminals.]_
@@ -890,7 +893,7 @@ _A tool may choose to connect terminals with a different or unknown `terminalKin
 
 The `TerminalMemberVariable` is defined as:
 
-image::images/fmi3Terminal_TerminalMemberVariable_Schema.png[width=50%, pdfwidth=50%, align="center"]
+image::images/gen/TerminalMemberVariable_schema.png[width=80%, pdfwidth=50%, align="center"]
 
 The normalized string `variableKind` is used to provide general information about the variable.
 This information defines how the connection of this variable has to be implemented (e.g. Kirchhoff's current law or common signal flow).
@@ -985,7 +988,7 @@ _Connecting a single <<output>> `outflow` to a single <<input>> `inflow`, or vic
 
 The `TerminalStreamMemberVariable` is defined as:
 
-image::images/fmi3Terminal_TerminalStreamMemberVariable_Schema.png[width=60%, pdfwidth=60%, align="center"]
+image::images/gen/TerminalStreamMemberVariable_schema.png[width=70%, pdfwidth=60%, align="center"]
 
 This element is used for variables which fulfill the balance equation for transported quantities.
 It is restricted to <<input>> and <<output>>, <<parameter>> and <<calculatedParameter>>.
@@ -1042,12 +1045,10 @@ There are three optional elements in the `GraphicalRepresentation`:
 . The `Icon` defines an image source for the FMU.
 . The `Terminal` sequence contains the graphical representation of the visible terminals.
 
-image::images/fmiModelDescription_GraphicalRepresentation_Schema.png[width=60%, pdfwidth=60%, align="center"]
+image::images/gen/GraphicalRepresentation_schema.png[width=80%, align="center"]
 
 ===== CoordinateSystem
 
-image::images/fmiModelDescription_GraphicalRepresentation_CoordinateSystem_Schema.png[width=60%, pdfwidth=60%, align="center"]
-
 The `CoordinateSystem` element and its defined extent is used as reference for other graphical items. It also provides a scaling factor to millimeter.
 
 The coordinate system is defined by the coordinates of two points, the lower left (`x1`, `y1`) corner and the upper right (`x2`, `y2`) corner, where the coordinates of the first point shall be less than the coordinates of the second point _[a first quadrant coordinate system]_.
@@ -1069,8 +1070,6 @@ Flipping of the FMU icon or a terminal can be realized by setting its attributes
 
 ===== Icon
 
-image::images/fmiModelDescription_GraphicalRepresentation_Icon_Schema.png[width=30%, pdfwidth=30%, align="center"]
-
 In the `Icon` element the FMU icon without terminals is defined, its extent and position.
 
 The `iconSource_PNG` attribute is mandatory to simplify the import in other tools, so a PNG file has to be provided in any case.
@@ -1082,8 +1081,6 @@ The point (`x2`, `y2`) maps to the right upper corner of the PNG image or SVG vi
 
 ===== Terminals
 
-image::images/fmiModelDescription_GraphicalRepresentation_Terminal_Schema.png[width=50%, pdfwidth=50%, align="center"]
-
 For `fmi3Terminals` (terminals which are listed in the `Terminals` element) the name of the terminal in the `GraphicalRepresentation` is equal to the name of the terminal in the `Terminals` element (e.g. `port_a`).
 _[If the graphical representation is used for an <<input>> or <<output>> (e.g. a `fmi3Float64` <<input>> `u`), then a `Terminal` has to be added to the `Terminals` element which has one `TerminalMemberVariable`._
 _The name of the `Terminal` and the name of the `TerminalMemberVariable` should be equal to the name of the <<input>> / <<output>>.]_
@@ -1117,7 +1114,7 @@ _[So the FMU icon should be placed first in the XML file, terminal below.]_
 
 Element `VendorAnnotations` of `fmiModelDescription` is defined as:
 
-image::images/VendorAnnotations_schema.png[width=80%, align="center"]
+image::images/gen/VendorAnnotations_schema.png[width=80%, align="center"]
 
 `VendorAnnotations` consist of an ordered set of annotations that are identified by the name of the tool that can interpret the `any` element.
 The `any` element can be an arbitrary XML data structure defined by the tool.
@@ -1128,7 +1125,7 @@ The attribute `name` must be unique with respect to all other elements of the `V
 The `ModelVariables` element of `fmiModelDescription` is the central part of the model description.
 It provides the static information of all exposed variables and is defined as:
 
-image::images/ModelVariables_schema.png[width=100%, align="center"]
+image::images/gen/ModelVariables_schema.png[width=100%, align="center"]
 
 The `ModelVariables` element consists of an ordered set of variable elements (see figure above).
 Variable elements can uniformly represent variables of primitive (atomic) types, like single floating point or integer variables, or as well as arrays of an arbitrary (but fixed) number of dimensions. The schema definition is present in a separate file `fmi3Variable.xsd`.
@@ -1172,7 +1169,7 @@ include::examples/alias_example.xml[tags=VariableAliases]
 
 The attributes of variables are:
 
-image::images/ScalarVariable_schema.png[width=90%, align="center"]
+image::images/gen/fmi3VariableBase_schema.png[width=90%, align="center"]
 
 [cols="1,5a",options="header"]
 |====
@@ -1773,17 +1770,18 @@ _FMI for Co-Simulation:_
 _Changing of <<tunable>> <<parameter,`parameters`>> is allowed before an <<fmi3DoStep>> call (so, whenever an <<input>> can be set with `fmi3Set{VariableType}`) and before <<fmi3ExitInitializationMode>> is called (that is before and during *Initialization Mode*)._
 _The FMU internally carries out event handling if necessary.]_
 
-Type specific properties are defined in the required choice element, where exactly one of the numeric types or an Enumeration must be present in the XML file:
+Type specific properties are defined in the required choice element, where exactly one of the numeric types or an Enumeration must be present in the XML file.
+The following are representative examples:
 
-image::images/Real_Schema_large.png[width=50%, align="center"]
+image::images/gen/Variable_Float64_schema.png[width=50%, align="center"]
 
-image::images/Integer_Schema_large.png[width=50%, align="center"]
+image::images/gen/Variable_Int32_schema.png[width=50%, align="center"]
 
-image::images/Boolean_Schema_large.png[width=50%, align="center"]
+image::images/gen/Variable_Boolean_schema.png[width=50%, align="center"]
 
-image::images/String_Schema_large.png[width=50%, align="center"]
+image::images/gen/Variable_Binary_schema.png[width=50%, align="center"]
 
-image::images/Enumeration_Schema_large.png[width=50%, align="center"]
+image::images/gen/Variable_Enumeration_schema.png[width=50%, align="center"]
 
 The attributes are defined in <<definition-of-types>> (`TypeDefinitions`), except:
 
@@ -1855,7 +1853,7 @@ _[If, for example, an `Enumeration` is defined with `name1 = -4`, `name2 = 1`, `
 
 With element `Annotations` additional, tool specific data can be defined:
 
-image::images/Annotations_schema.png[width=80%]
+image::images/gen/Annotations_schema.png[width=80%]
 
 With `Tool.name` the name of the tool is defined that can interpret the `any` element.
 The `any` element can be an arbitrary XML data structure defined by the tool.
@@ -1883,11 +1881,7 @@ _[A simulation environment can utilize this information to improve the efficienc
 
 `ModelStructure` has the following definition:
 
-image::images/ModelStructure_schema.png[width=80%]
-
-`fmi3Unknown` is defined as:
-
-image::images/Unknown_schema.png[width=80%]
+image::images/gen/ModelStructure_schema.png[width=80%]
 
 Note that attribute <<dependenciesKind>> for element <<InitialUnknown>> has less enumeration values as <<dependenciesKind>> in the other lists, see below.
 

docs/3_3_model_exchange_schema.adoc

@@ -8,9 +8,7 @@ Additionally, the Model Exchange-specific element `ModelExchange` is defined in
 If the XML file defines an FMU for Model Exchange, element `ModelExchange` must be present.
 It is defined as:
 
-image::images/model_exchange_schema_1.png[width=80%, align="center"]
-
-image::images/model_exchange_schema_2.png[width=70%, align="center"]
+image::images/gen/ModelExchange_schema.png[width=80%, align="center"]
 
 The following attributes are defined (all of them are optional, with exception of `modelIdentifier`):
 

docs/4_3_basic_co-simulation_schema.adoc

@@ -6,13 +6,10 @@ Additionally, the Co-Simulation specific element `Implementation` is defined in
 //TODO: find better place for attribute description!
 //TODO: check wording "slave"
 
-If the XML file defines an FMU for Co-Simulation, element `CoSimulation` must be present.
+If the XML file defines an FMU for Co-Simulation, element `BasicCoSimulation_schema` must be present.
 It is defined as:
 
-//TODO: update XML images
-image::images/cs_xml_1.png[width=80%, align="center"]
-
-image::images/cs_xml_2.png[width=70%, align="center"]
+image::images/gen/BasicCoSimulation_schema.png[width=80%, align="center"]
 
 These attributes have the following meaning (all attributes are optional with exception of `modelIdentifier`):
 

schema/fmi3InterfaceType.xsd

@@ -37,7 +37,7 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 	<xs:include schemaLocation="fmi3Annotation.xsd"/>
 	<xs:complexType name="fmi3InterfaceType" abstract="true">
 		<xs:sequence minOccurs="0">
-			<xs:element name="VendorAnnotations" type="fmi3Annotation" minOccurs="0"/>
+			<xs:element ref="VendorAnnotations" minOccurs="0"/>
 		</xs:sequence>
 		<xs:attribute name="modelIdentifier" type="xs:normalizedString" use="required"/>
 		<xs:attribute name="needsExecutionTool" type="xs:boolean" default="false"/>
@@ -67,4 +67,5 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 			</xs:extension>
 		</xs:complexContent>
 	</xs:complexType>
+	<xs:element name="VendorAnnotations" type="fmi3Annotation"/>
 </xs:schema>