Created Documentation for CityDoctor Extensions

b0238c23 · Riegel · 1745865f · b0238c23 · b0238c23 · b0238c23
Commit b0238c23 authored 7 months ago by Riegel
Show whitespace changes
Inline Side-by-side

Showing

with 336 additions and 1 deletion
+336 -1
--- a/CityDoctorParent/Extensions/README.md
+++ b/CityDoctorParent/Extensions/README.md
+# CityDoctor2 Extensions
+Extension modules to the core functionality of CityDoctor2. 
+
+# Loading
+
+Except for CityDoctorGUI, all extension modules are not loaded into the Maven project by default.
+If you wish to load an extension, you can either import the respective Maven module directly, or adjust the CityDoctorParent
+pom.xml and move the respective modules out of the comment-block in the module list found at the end of the file.
+
+# Building
+
+All loaded modules will also be built upon building of the CityDoctorParent.
+
+# Module Information
+
+## CityDoctorAutoPro
+
+![Maintenance Level: Deprecated](../resources/Badges/MaintenanceLevel_Deprecated.svg)
+
+The AutoPro (short for automated processing) module is an interface for the conversion of the internal data model to a C++
+representation, to allow use of advanced functionalities of CGAL with CityDoctor2.
+
+### Usage
+
+The AutoPro module is deprecated and will be removed in a future release, once the C++ functionalities have been ported to Java.
+
+AutoPro requires a collection of .dll files to run, some of which are not available as open source projects. Access to the collection is only granted upon request. Contact a Maintainer for further information.
+
+## CityDoctorGUI
+![Maintenance Level: Actively Maintained](../resources/Badges/MaintenanceLevel_ActivelyMaintained.svg)
+
+The GUI module offers a graphical user interface for CityDoctor2, including a model viewer allowing for visual
+inspection of validation results and found errors.
+
+### View Plugins
+
+The GUI is expandable via plugins, enabling the creation of views for custom functionalities or extensions of the CityDoctor2 core.  
+Custom views can be created by extending the Abstract class `View` of the CityDoctorGUI and need to be registered by calling
+`ViewRegistration.registerView(View view);` before starting the GUI.
+
+### Usage
+
+> ⚠ CityDoctorGUI requires a JDK/JRE containing the JavaFX library to run.  
+
+Prebuilt binaries for the GUI are available in [CityDoctorReleases](https://transfer.hft-stuttgart.de/gitlab/citydoctor/citydoctorreleases).
+After extracting the archive the GUI can be started with **start.bat**.
+
+Binaries can be built with Maven using the create-binaries profile from the CityDoctorParent directory:  
+```
+mvn install -P create-binaries
+```   
+
+Lastly, the GUI can also be started by calling `MainWindow.main(args[])`.
+
+
+## CityDoctorHealer
+![Maintenance Level: Inactively Maintained](../resources/Badges/MaintenanceLevel_InactivelyMaintained.svg)
+
+CityDoctorHealer implements functionalities for the automated repair of geometries containing errors.
+The healer uses naive approaches to fix geometrical errors, and thus, it cannot be guaranteed that semantical
+correctness is maintained after the healing process.  
+
+
+### Usage
+
+Usage of CityDoctorHealer is similar to [CityDoctor](https://transfer.hft-stuttgart.de/gitlab/citydoctor/citydoctor2/-/tree/dev_GUI#usage).
+An example start command looks like this:
+```
+java -classpath libs/*;plugins/*;CityDoctorHealer-<version>.jar de.hft.stuttgart.citydoctor2.CityDoctorHealer -in <path-to-gml-file>.gml -config <path-to-validation-config>.yml -xmlReport <path-to-xml-output>.xml -pdfReport <path-to-pdf-output>.pdf -out <path-to-output-gml>.gml
+```
+Note: Unlike the CityDoctor core, the _-out_ argument is required
+
+To prevent infinite loops the `Healer` class has a limit for the number of healing iterations (default: 200). This limit
+can be changed by calling `Healer.setNumberOfIterations(int limit)`. 
+
+## CityDoctorHealerGenetic
+![Maintenance Level: Abandoned](../resources/Badges/MaintenanceLevel_Abandoned.svg)
+
+CityDoctorHealerGenetic uses a genetical algorithm to establish an optimal CityDoctorHealer healing-plan for geometries containing errors.
+
+### Usage
+> ⚠ This module has been abandoned. As of writing the module is still functional, but it may break at any time.
+>Issues, bug reports and suggestions for this module will not be processed. Use at your own discretion.
+
+Usage is nearly identical to CityDoctorHealer, only requiring changing the classpath to the HealerGenetic jar.
+
+A View for usage with CityDoctorGUI is included.
+
+## CityDoctorHealerGUI
+![Maintenance Level: Inactively Maintained](../resources/Badges/MaintenanceLevel_InactivelyMaintained.svg)
+
+CityDoctorGUI-view for CityDoctorHealer.
+
+### Usage
+
+See [CityDoctorGUI](#view-plugins)
+
+
+## CityDoctorWebService
+![Maintenance Level: Abandoned](../resources/Badges/MaintenanceLevel_Abandoned.svg)
+
+Web service API for CityDoctor.
+
+### Usage
+> ⚠ This module has been abandoned. As of writing the module is still functional, but it may break at any time.
+>Issues, bug reports and suggestions for this module will not be processed. Use at your own discretion.
+
+Run on a Tomcat Server.
+
+
+# Build
+
+Use [Maven](https://maven.apache.org/) to build CityDoctor2.
+
+```bash
+cd CityDoctorParent
+mvn install
+```
+
+
+## License
+[LGPL](http://www.gnu.org/licenses/lgpl-3.0.de.html)
--- a/CityDoctorParent/pom.xml
+++ b/CityDoctorParent/pom.xml
@@ -258,15 +258,20 @@
        </dependency>
    </dependencies>
    <modules>
+        <!--CityDoctor2 Core Modules-->
        <module>CityDoctorModel</module>
        <module>CityDoctorValidation</module>
        <module>CityDoctorEdge</module>
        <module>CityDoctorCheckResult</module>
+
+        <!--CityDoctor2 Extension Modules-->
        <module>Extensions/CityDoctorGUI</module>
+        <!--
        <module>Extensions/CityDoctorAutoPro</module>
        <module>Extensions/CityDoctorHealer</module>
        <module>Extensions/CityDoctorHealerGenetic</module>
        <module>Extensions/CityDoctorHealerGUI</module>
        <module>Extensions/CityDoctorWebService</module>
+        -->
    </modules>
 </project>
\ No newline at end of file
--- a/CityDoctorParent/resources/Badges/MaintenanceLevel_Abandoned.svg
+++ b/CityDoctorParent/resources/Badges/MaintenanceLevel_Abandoned.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="194" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="194" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#555" d="M0 0h121v20H0z"/>
+        <path fill="#FF0000" d="M121 0h73v20H121z"/>
+        <path fill="url(#b)" d="M0 0h194v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="61.5" y="15" fill="#010101" fill-opacity=".3">Maintenance Level</text>
+        <text x="60.5" y="14">Maintenance Level</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="158.5" y="15" fill="#010101" fill-opacity=".3">Abandoned</text>
+        <text x="157.5" y="14">Abandoned</text>
+    </g>
+</svg>
--- a/CityDoctorParent/resources/Badges/MaintenanceLevel_ActivelyDeveloped.svg
+++ b/CityDoctorParent/resources/Badges/MaintenanceLevel_ActivelyDeveloped.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="243" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="243" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#555" d="M0 0h121v20H0z"/>
+        <path fill="#228B22" d="M121 0h122v20H121z"/>
+        <path fill="url(#b)" d="M0 0h243v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="61.5" y="15" fill="#010101" fill-opacity=".3">Maintenance Level</text>
+        <text x="60.5" y="14">Maintenance Level</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="183.0" y="15" fill="#010101" fill-opacity=".3">Actively Developed</text>
+        <text x="182.0" y="14">Actively Developed</text>
+    </g>
+</svg>
--- a/CityDoctorParent/resources/Badges/MaintenanceLevel_ActivelyMaintained.svg
+++ b/CityDoctorParent/resources/Badges/MaintenanceLevel_ActivelyMaintained.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="248" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="248" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#555" d="M0 0h121v20H0z"/>
+        <path fill="#6B8E23" d="M121 0h127v20H121z"/>
+        <path fill="url(#b)" d="M0 0h248v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="61.5" y="15" fill="#010101" fill-opacity=".3">Maintenance Level</text>
+        <text x="60.5" y="14">Maintenance Level</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="185.5" y="15" fill="#010101" fill-opacity=".3">Actively Maintained</text>
+        <text x="184.5" y="14">Actively Maintained</text>
+    </g>
+</svg>
--- a/CityDoctorParent/resources/Badges/MaintenanceLevel_Deprecated.svg
+++ b/CityDoctorParent/resources/Badges/MaintenanceLevel_Deprecated.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="198" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="198" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#555" d="M0 0h121v20H0z"/>
+        <path fill="#800000" d="M121 0h77v20H121z"/>
+        <path fill="url(#b)" d="M0 0h198v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="61.5" y="15" fill="#010101" fill-opacity=".3">Maintenance Level</text>
+        <text x="60.5" y="14">Maintenance Level</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="160.5" y="15" fill="#010101" fill-opacity=".3">Deprecated</text>
+        <text x="159.5" y="14">Deprecated</text>
+    </g>
+</svg>
--- a/CityDoctorParent/resources/Badges/MaintenanceLevel_InactivelyMaintained.svg
+++ b/CityDoctorParent/resources/Badges/MaintenanceLevel_InactivelyMaintained.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="260" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="260" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#555" d="M0 0h121v20H0z"/>
+        <path fill="#A4A61D" d="M121 0h139v20H121z"/>
+        <path fill="url(#b)" d="M0 0h260v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="61.5" y="15" fill="#010101" fill-opacity=".3">Maintenance Level</text>
+        <text x="60.5" y="14">Maintenance Level</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="191.5" y="15" fill="#010101" fill-opacity=".3">Inactively Maintained</text>
+        <text x="190.5" y="14">Inactively Maintained</text>
+    </g>
+</svg>
--- a/CityDoctorParent/resources/Badges/MaintenanceLevel_NotMaintained.svg
+++ b/CityDoctorParent/resources/Badges/MaintenanceLevel_NotMaintained.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="219" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="219" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#555" d="M0 0h121v20H0z"/>
+        <path fill="#FF4500" d="M121 0h98v20H121z"/>
+        <path fill="url(#b)" d="M0 0h219v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="61.5" y="15" fill="#010101" fill-opacity=".3">Maintenance Level</text>
+        <text x="60.5" y="14">Maintenance Level</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="171.0" y="15" fill="#010101" fill-opacity=".3">Not Maintained</text>
+        <text x="170.0" y="14">Not Maintained</text>
+    </g>
+</svg>
--- a/CityDoctorParent/resources/Badges/MaintenanceLevel_Obsolete.svg
+++ b/CityDoctorParent/resources/Badges/MaintenanceLevel_Obsolete.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="185" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="185" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#555" d="M0 0h121v20H0z"/>
+        <path fill="#000000" d="M121 0h64v20H121z"/>
+        <path fill="url(#b)" d="M0 0h185v20H0z"/>
+    </g>
+    <g fill="white" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="61.5" y="15" fill="#010101" fill-opacity=".3">Maintenance Level</text>
+        <text x="60.5" y="14">Maintenance Level</text>
+    </g>
+    <g fill="white" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="154.0" y="15" fill="#010101" fill-opacity=".3">Obsolete</text>
+        <text x="153.0" y="14">Obsolete</text>
+    </g>
+</svg>
--- a/CityDoctorParent/resources/Badges/Project_CD2.svg
+++ b/CityDoctorParent/resources/Badges/Project_CD2.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="132" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="132" height="20" rx="10" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#FF0000" d="M0 0h132v20H0z"/>
+        <path fill="#262626" d="M53 2h70v16H53z"/>
+        <path fill="#262626" d="M122,18 a1,1 0 0,0 0,-16"/>
+        <path fill="url(#b)" d="M0 0h132v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="26.5" y="14">Project</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="92.5" y="14">CityDoctor2</text>
+    </g>
+</svg>
--- a/CityDoctorParent/resources/Badges/Project_UDigiT.svg
+++ b/CityDoctorParent/resources/Badges/Project_UDigiT.svg
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="144" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="144" height="20" rx="10" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#4169E1" d="M0 0h144v20H0z"/>
+        <path fill="#262626" d="M53 2h82v16H53z"/>
+        <path fill="#262626" d="M134,18 a1,1 0 0,0 0,-16"/>
+        <path fill="url(#b)" d="M0 0h144v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="26.5" y="14">Project</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="98.5" y="14">UDigiT-Doctor</text>
+    </g>
+</svg>
--- a/README.md
+++ b/README.md
 # CityDoctor2

-[![pipeline status](https://transfer.hft-stuttgart.de/gitlab/betzms/citydoctor2/badges/master/pipeline.svg)](https://transfer.hft-stuttgart.de/gitlab/betzms/citydoctor2/-/commits/master)
+[![pipeline status](https://transfer.hft-stuttgart.de/gitlab/betzms/citydoctor2/badges/master/pipeline.svg)](https://transfer.hft-stuttgart.de/gitlab/betzms/citydoctor2/-/commits/master) ![Maintenance Level: Actively Developed](/CityDoctorParent/resources/Badges/MaintenanceLevel_ActivelyDeveloped.svg)

 CityDoctor2 is a Java program for validating CityGML files. It checks whether certain criteria for e.g. geometries are met and outputs a report on the results.

@@ -42,6 +42,9 @@ java -classpath libs/*;plugins/*;CityDoctorValidation-<version>.jar de.hft.stutt
 Note:
 -xmlReport, -pdfReport and -out are optional

+## Extension
+
+Example extensions for CityDoctor are included in this repository, and can be found in the [Extensions subdirectory](./CityDoctorParent/Extensions)

 ## License
 [LGPL](http://www.gnu.org/licenses/lgpl-3.0.de.html)