Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/piotrjustyna/drakon-renderer

svg drakon diagrams
https://github.com/piotrjustyna/drakon-renderer
diagram drakon drakon-diagrams haskell
Last synced: about 2 months ago
JSON representation
svg drakon diagrams
Host: GitHub
URL: https://github.com/piotrjustyna/drakon-renderer
Owner: PiotrJustyna
License: mit
Created: 2024-02-13T13:31:45.000Z (11 months ago)
Default Branch: main
Last Pushed: 2024-11-06T16:35:10.000Z (2 months ago)
Last Synced: 2024-11-06T17:20:36.908Z (2 months ago)
Topics: diagram, drakon, drakon-diagrams, haskell
Language: Haskell
Homepage:
Size: 11.2 MB
Stars: 2
Watchers: 2
Forks: 0
Open Issues: 14
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        # drakon-renderer

Reasonably portable drakon diagrams renderer. Development, compilation and execution are intended to take place in containers.

**Important:**

this is work in progress and, while progress is being made every week, the renderer is not yet guaraneed to render drakon-correct diagrams. Current focus is to render primitive diagrams according to drakon rules.

## terminology

* `Title` - first step of a diagram

* `End` - last step of a diagram

* `Action` - "do X" non-branching action, basic building block of a diagram

* `Question` - branching step with two possible outcomes:

  * yes

  * no

* Headline

* Address

* Cap

* Primitive

* Silhouette

## input syntax

```json

[

    {

        "iconDescription": "hello world title",

        "iconKind": "Title",

        "iconName": "1",

        "iconNamesOfDependentIcons": [

            "2"

        ]

    },

    {

        "iconDescription": "hello world icon 2",

        "iconKind": "Action",

        "iconName": "2",

        "iconNamesOfDependentIcons": [

            "3",

            "4"

        ]

    },

    ...

]

```

## output

### balanced paths

Balanced paths - WIP currently, but the plan is to make balanced paths the foundation of future layout engines. The idea is to trace all available paths from the title icon to the end icon and then alter them in such a way that all paths end up with the same number of icons/valent points (exact implementation not set in stone yet).

| path 1 | path 2 | path 3 | path 4 | path 5 | path 6 | path 7 | path 8 |

| --- | --- | --- | --- | --- | --- | --- | --- |

| **1** - transport | **1** - transport | **1** - transport | **1** - transport | **1** - transport | **1** - transport | **1** - transport | **1** - transport |

| **2** - Cryopreservation | **2** - Cryopreservation | **2** - Cryopreservation | **2** - Cryopreservation | **2** - Cryopreservation | **2** - Cryopreservation | **2** - Cryopreservation | **2** - Cryopreservation |

| **3** - perfusion | **3** - perfusion | **3** - perfusion | **3** - perfusion | **3** - perfusion | **3** - perfusion | **3** - perfusion | **3** - perfusion |

| **4** - perfuse the brain - 1 | **4** - perfuse the brain - 1 | **4** - perfuse the brain - 1 | **4** - perfuse the brain - 1 | **6** - remove brain | **6** - remove brain | **6** - remove brain | **6** - remove brain |

| **4'** - perfuse the brain - 2 | **4'** - perfuse the brain - 2 | **4'** - perfuse the brain - 2 | **4'** - perfuse the brain - 2 | **7** - remove alternative | **7** - remove alternative | **7** - remove alternative | **8** - remove the brain |

| **6** - remove brain | **6** - remove brain | **6** - remove brain | **6** - remove brain | **8** - remove the brain | **13** - embalm 2 | **13** - embalm 2 | **9** - place brain |

| **7** - remove alternative | **7** - remove alternative | **7** - remove alternative | **8** - remove the brain | **9** - place brain | **14** - Czech transit | **14** - Czech transit | **10** - freeze brain |

| **8** - remove the brain | **13** - embalm 2 | **13** - embalm 2 | **9** - place brain | **10** - freeze brain | **15** - transport Czech | **16** - transport Moscow | **11** - embalm 1 |

| **9** - place brain | **14** - Czech transit | **14** - Czech transit | **10** - freeze brain | **11** - embalm 1 | **100** - The end | **100** - The end | **12** - transport Finland |

| **10** - freeze brain | **15** - transport Czech | **16** - transport Moscow | **11** - embalm 1 | **12** - transport Finland | **0** - :x: | **0** - :x: | **100** - The end |

| **11** - embalm 1 | **100** - The end | **100** - The end | **12** - transport Finland | **100** - The end | **0** - :x: | **0** - :x: | **0** - :x: |

| **12** - transport Finland | **0** - :x: | **0** - :x: | **100** - The end | **0** - :x: | **0** - :x: | **0** - :x: | **0** - :x: |

| **100** - The end | **0** - :x: | **0** - :x: | **0** - :x: | **0** - :x: | **0** - :x: | **0** - :x: | **0** - :x: |

### positioned icons

Serialized list of `PositionedIcon` which are regular `Icon` supplemented with their post-layout cartesian coordinates:

```json

[

    {

        "icon": {

            "iconDescription": "hello world title",

            "iconKind": "Title",

            "iconName": "1",

            "iconNamesOfDependentIcons": [

                "2"

            ]

        },

        "iconPositionX": 0,

        "iconPositionY": 0

    },

    {

        "icon": {

            "iconDescription": "hello world icon 2",

            "iconKind": "Action",

            "iconName": "2",

            "iconNamesOfDependentIcons": [

                "3",

                "4"

            ]

        },

        "iconPositionX": 0,

        "iconPositionY": -1

    },

    ...

]

```

* an svg diagram:

![real life diagram 1](./diagrams/real-life-diagram-1.svg)

## method

1. read serialized collection of `Icon`s & deserialize

2. validate Icons (only one title icon per diagram, correct numbers of dependencies, etc.) - sample validation:

    ```bash

    Input validation did not succeed for following reasons:

    * Error: Icons identified with following names contain incorrect number of dependencies: "8", "3", "2". Hint: Make sure your icons have the expected number of dependencies. For reference: "Title" and "Action" icons should have 1 depdenency, "Question" icon should have 2 dependencies and "End" should have no dependencies.

    * Error: Diagram is required to have exactly one icon of kind "End". Hint: Make sure your input diagram contains an icon of kind "End" and that it is the only icon of that kind.

    * Error: Diagram is required to have exactly one icon of kind "Title". Hint: Make sure your input diagram contains an icon of kind "Title" and that it is the only icon of that kind.

    ```

3. if validation is successful, attempt to position the directed graph's nodes on a cartesian plane:

    * positive integer x coordinates only

    * negative integer y coordinates only

4. serialize the product (`[PositionedIcon]`) to a file where:

    * input: `file.json`

    * output: `file-drakon-layout.json`

5. Render the collection of `PositionedIcon`s into the final svg diagram.

6. Render the connections between the collection of `PositionedIcon`s into the final svg diagram.

## development environment

| command | description |

| --- | --- |

| `./start-development-environment.sh` or `.\start-development-environment.ps1` | starts a fully dockerized development environment |

| `./build.sh` | builds and lints code - preferrably while development environment docker container is running, otherwise local installation of cabal and hlint is required) |

| `./run.sh` | runs code - just like the build script, the preferred way to use it is while the development environment is running |

| `./format.sh` | formats all `*.hs` files located in the `./app` directory using [hindent](https://github.com/mihaimaruseac/hindent) |

| `exit` | terminates development environment |

## project status

You can see into the bigger ideas I have for the project (past, present, future) here: [dev-log.md](./dev-log.md).

## community

* [youtube](https://www.youtube.com/playlist?list=PL9-WsOrOzOxSqWNqzhzyBGZsN0sOxEF6Q)

* [discord](https://discord.gg/eaJ7e4jF)

## resources

* [drakon whitepaper](https://drakon.su/_media/video_i_prezentacii/graphical_syntax_.pdf)

* [drakon wiki](https://en.m.wikipedia.org/wiki/DRAKON)

* [drakon.su](https://drakon.su/start)

* [drakon](https://drakonhub.com/read/docs)

* [diagrams](https://archives.haskell.org/projects.haskell.org/diagrams/doc/quickstart.html#introduction)

* [diagrams - user manual](https://archives.haskell.org/projects.haskell.org/diagrams/doc/manual.html)

* [colours](https://www.colourlovers.com)

* [colorkit](https://colorkit.co/)

  * [default palette](https://colorkit.co/palette/642915-963e20-c7522a-e5c185-fbf2c4-74a892-008585-006464-004343/)

* useful haskell modules:

  * [GHC.Data.Graph.Directed](https://hackage.haskell.org/package/ghc-9.4.7/docs/GHC-Data-Graph-Directed.html)

  * [GHC.Utils.Outputable](https://hackage.haskell.org/package/ghc-9.4.7/docs/GHC-Utils-Outputable.html)

* if you struggle with `.git` permissions, try:

  ```bash

  # Note: Use this command with caution as it changes file ownership. Only run it if you understand the security implications.

  sudo chown -R yourusername .git

  ```