From 7331e7381025d6f392983396ef7ea1e3fff6a883 Mon Sep 17 00:00:00 2001 From: spaaaacccee Date: Fri, 26 Apr 2024 13:59:36 +1000 Subject: [PATCH] Minor doc changes --- docs/1-overview.md | 10 +++---- docs/2-search-trace.md | 30 +++++++++++++------ docs/3-visualiser/2-visualiser.md | 15 ---------- docs/3-visualiser/3-1-user-guide/debugger.mdx | 15 ++++++---- docs/3-visualiser/3-1-user-guide/interface.md | 2 +- docs/3-visualiser/3-1-user-guide/layers.mdx | 14 ++++----- docs/3-visualiser/3-1-user-guide/settings.mdx | 2 +- docs/3-visualiser/3-1-user-guide/steps.md | 2 +- docs/3-visualiser/3-1-user-guide/tree.md | 2 +- docs/3-visualiser/3-1-user-guide/viewport.md | 6 ++-- docs/3-visualiser/overview.md | 25 ++++++++++++++++ docs/4-tutorials/overview.md | 3 -- docs/6-api/overview.md | 3 -- 13 files changed, 73 insertions(+), 56 deletions(-) delete mode 100644 docs/3-visualiser/2-visualiser.md create mode 100644 docs/3-visualiser/overview.md delete mode 100644 docs/4-tutorials/overview.md delete mode 100644 docs/6-api/overview.md diff --git a/docs/1-overview.md b/docs/1-overview.md index 1a9167f..e65ff46 100644 --- a/docs/1-overview.md +++ b/docs/1-overview.md @@ -40,16 +40,16 @@ Identify where your algorithm has deviated from a known good baseline by compari ### Discuss ideas with your team -### Help students learn - -The Posthoc could be use as an learning tool in for learners' understanding of complex algorithms by providing a conducive environment for visualisation. Consider the example of the weighted [A\* search](https://en.wikipedia.org/wiki/A*_search_algorithm) problem. Students often find it challenging to conceptualize how various weights assigned to different grid cells or walkable paths can influence the algorithm's decision-making process. The Posthoc bridges this gap, enabling learners to visually comprehend the impact of these weights on the algorithm's pathfinding capabilities. +Present your ideas to your team and problem-solve together. -![weighted a star](educational.png) +### Help students learn -In the illustration provided, the map is designed to mimic a video game environment, depicting a desert interspersed with patches of forest. The intensity of the green color indicates the weight of the walkable paths, with darker shades representing heavier weights. Through this visualization, it becomes evident how the A\* algorithm strategically selects a path from the source to the target. It does so by navigating through areas with the least amount of green, effectively avoiding paths with heavier weights to find the shortest and most efficient route. This visual demonstration not only clarifies the concept of weighted pathfinding but also showcases the algorithm's adeptness at incorporating path weights into its calculations, leading to an optimized solution. +Walk through algorithms and techniques visually with students. ### Share your work +Let the world discover your work. + ## Why we built Posthoc We're a team of optimisation researchers at Monash University. diff --git a/docs/2-search-trace.md b/docs/2-search-trace.md index d13190b..2450791 100644 --- a/docs/2-search-trace.md +++ b/docs/2-search-trace.md @@ -8,6 +8,7 @@ The search trace is a YAML log of your algorithm's decisions. What, and how much
```yaml title="single-agent-search.trace.yaml" + version: 1.4.0 events: - { type: expand, id: 0, f: 0, g: 0 } - { type: generate, id: 1, pId: 0, f: 1, g: 1 } @@ -18,6 +19,7 @@ The search trace is a YAML log of your algorithm's decisions. What, and how much
```yaml title="agent-moves.trace.yaml" + version: 1.4.0 events: - { type: move, agent: 47, id: 0, x: 0, y: 0 } - { type: move, agent: 18, id: 0, pId: 0, x: 5, y: 2 } @@ -27,6 +29,7 @@ The search trace is a YAML log of your algorithm's decisions. What, and how much
```yaml title="rayscan.trace.yaml" + version: 1.4.0 events: - { type: raycast, id: 1, x: 1, y: 2, rayX: 3, rayY: 4 } - { type: raycast, id: 1, x: 1, y: 2, rayX: 1, rayY: 4 } @@ -39,6 +42,7 @@ Since YAML is a superset of JSON, your traces can be in JSON too.
```yaml title="single-agent-search.trace.json" + version: 1.4.0 { "events": [ { "type": "expand", "id": 0, "f": 0, "g": 0 }, @@ -50,13 +54,14 @@ Since YAML is a superset of JSON, your traces can be in JSON too.
Generic search events (JSON)
-Search traces should have the extensions `.trace.yaml` or `.trace.json`. +Search traces should have the extensions `.trace.yaml` or `.trace.json`. It's required to declare `version: 1.4.0`. ## Decision tree View your sequential decision-making processes as a tree or directed graph. Just provide `id` and `pId`(parent ID) properties in your log. ```yaml title="simple-tree.trace.yaml" +version: 1.4.0 events: - { type: decision, id: a, pId: null } - { type: decision, id: b, pId: a } @@ -71,7 +76,8 @@ The `type` property is optional, but should be a descriptive name of the kind of Give your search trace a custom visual representation by adding a `views` section to it. -```yaml {1-8} title="custom-view.trace.yaml" +```yaml {2-9} title="custom-view.trace.yaml" +version: 1.4.0 views: main: - $: rect # Show a rectangle... @@ -103,6 +109,7 @@ See the [2D renderer API reference](category/renderer) for a list of primitives Nesting allows you to create copies of some element without having to repeat yourself. ```yaml title="nesting.trace.yaml +version: 1.4.0 views: // highlight-next-line marker: # A marker is defined here, which just draws a circle @@ -136,6 +143,7 @@ Nest views by referencing other views with the `$` property. You can also pass p You can write expressions inside `${{ }}` brackets to reference event information or values passed from a parent view. ```yaml title="expression.trace.yaml +version: 1.4.0 views: main: - $: rect @@ -161,13 +169,14 @@ See the [search trace API reference](api/search-trace) for a list of properties Control when elements should be cleared. -| Value | Example | Description | -| ----------------- | ---------------- | -------------------------------------------------------------------------- | -| `false` (default) | `clear: false` | Elements will remain once drawn. | -| `true` | `clear: true` | Elements will clear immediately after the step they're drawn. | -| `string` | `clear: closing` | Clear once the event of a particular type (e.g. `closing`) is encountered. | +| Value | Usage | Description | +| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------- | +| `false` (default) | `clear: false` | Event will remain once drawn. | +| `true` | `clear: true` | Event will clear immediately after the step they're drawn. | +| `string` | `clear: close` | Event clears once another event of the same `id`, and the specified type (e.g. `close`), is encountered. | ```yaml title="clear.trace.yaml" +version: 1.4.0 views: main: - $: circle @@ -187,7 +196,8 @@ events: Repeat a view based on a value. -```yaml {10-14} title="loop.trace.yaml" +```yaml {11-15} title="loop.trace.yaml" +version: 1.4.0 views: main: - $: circle @@ -213,6 +223,7 @@ events: Conditionally render a view. ```yaml title="if.trace.yaml" +version: 1.4.0 views: main: - $: circle @@ -239,7 +250,8 @@ events: By default, clicking on elements in the viewport will show you info about the event that rendered it. However, you can define information that will only be shown when a specific part of the event was clicked. -```yaml {8-11,17-20} title="info.trace.yaml +```yaml {9-11,17-19} title="info.trace.yaml +version: 1.4.0 views: main: - $: circle diff --git a/docs/3-visualiser/2-visualiser.md b/docs/3-visualiser/2-visualiser.md deleted file mode 100644 index 10bd3cf..0000000 --- a/docs/3-visualiser/2-visualiser.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Overview - -Open the visualiser [here](https://path-visualiser.github.io/app/). - -## Install Posthoc as a Progressive Web App - -You can install the visualiser as a progressive web app, so that it runs in its own window. - -## Standalone Builds - -Check the [releases](https://github.com/path-visualiser/app/releases) page for a list of latest Windows and Linux releases. diff --git a/docs/3-visualiser/3-1-user-guide/debugger.mdx b/docs/3-visualiser/3-1-user-guide/debugger.mdx index 6b76aa0..a9d1887 100644 --- a/docs/3-visualiser/3-1-user-guide/debugger.mdx +++ b/docs/3-visualiser/3-1-user-guide/debugger.mdx @@ -1,12 +1,13 @@ -# Debugger Panel +# Debugger Visualiser's Debugger panel is able to set breakpoints which stops the search trace or query at a specified condition. ![Alt text](debugger.png) ## Adding a Breakpoint + - click on the + Breakpoint button, this gives you a new breakpoint like below. -![Alt text](breakpoint.png) + ![Alt text](breakpoint.png) - Event dropdown: This filters the events based on the event types. - Property: The value that is being compared with. - Condition: The condition for comparison, (changed mean that the value have changed compared to the previous value) @@ -16,6 +17,7 @@ Visualiser's Debugger panel is able to set breakpoints which stops the search tr A demonstration [video](https://youtu.be/1iRMrrw9Dl0) shows on how to set a standart breakpoint and stepping thhrough the breakpoints ## Adding an Advance breakpoint + - Go on the Advanced tab. - Within this tab is a function snippet where the parameters can be used to make a customised breakpoint. @@ -27,11 +29,12 @@ A demonstration [video](https://youtu.be/1iRMrrw9Dl0) shows on how to set a stan A demonstration [video](https://youtu.be/Pe50r0x4xFk) shows a use case for the advanced breakpoint editor. ## Stepping through the breakpoints -- To step through the trace and jump to the next breakpoint, make a new steps panel by splitting an existing panel, + +- To step through the trace and jump to the next breakpoint, make a new steps panel by splitting an existing panel, - Scroll the header of the panel sideways to reveal the jump to next breakpoint button. - Red dots on the steps indicates that the breakpoint will hit on that step. -![Alt text](jump-to-next-breakpoint.png) - + ![Alt text](jump-to-next-breakpoint.png) ## Changing traces for the debugger -- Change the trace by choosing it through the dropdown on the debugger panel. \ No newline at end of file + +- Change the trace by choosing it through the dropdown on the debugger panel. diff --git a/docs/3-visualiser/3-1-user-guide/interface.md b/docs/3-visualiser/3-1-user-guide/interface.md index 49f5a1e..49d21d4 100644 --- a/docs/3-visualiser/3-1-user-guide/interface.md +++ b/docs/3-visualiser/3-1-user-guide/interface.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -# User Interface +# UI Posthoc's interface is made of composable panels. You can add, remove, and rearrange the UI to your desire. This allows Posthoc to support a range of tasks, whether you're using it to learn, showcase, or debug algorithms. diff --git a/docs/3-visualiser/3-1-user-guide/layers.mdx b/docs/3-visualiser/3-1-user-guide/layers.mdx index 50f42e1..d77b048 100644 --- a/docs/3-visualiser/3-1-user-guide/layers.mdx +++ b/docs/3-visualiser/3-1-user-guide/layers.mdx @@ -2,29 +2,27 @@ sidebar_position: 4 --- -# Layers Panel +# Layers Visualiser's layers panel shows all layers that are present. Each layer could either be a [trace](../6-api/search-trace.md), [map, or query](../5-tutorials/single-agent-grid). ![Alt text](layer-highligthed.png) this is the layers panel. -## Adding a Layer +## Adding a Layer + - Click the + Layer button within the layers panel. - A untitled Trace Layer will be added to the layers panel. ## Editing the Layer + - Click the edit (pencil) icon. - A modal will come up like down below. -![Alt text](layer-edit-modal.png) + ![Alt text](layer-edit-modal.png) - Within this modal, there are options to change the layer it self such as the transperancy and the display mode. - There is also an option to change the type of the layer. A more detailed example is available in the [single agent search tutorial](../5-tutorials/single-agent-grid.mdx) ## Other additional features + - To adjust the orders of the layers, drag the 2 stripes icon of the layer to the desired order, this affects on how the layers are shown within the viewport panel. - To fit the layer to the viewport panel, click on the options (3 dots) on each individual layer and click on Fit Layer. - - - - - diff --git a/docs/3-visualiser/3-1-user-guide/settings.mdx b/docs/3-visualiser/3-1-user-guide/settings.mdx index de88dcf..4729e3d 100644 --- a/docs/3-visualiser/3-1-user-guide/settings.mdx +++ b/docs/3-visualiser/3-1-user-guide/settings.mdx @@ -1,4 +1,4 @@ -# Settings Panel +# Settings Visualiser's setting panel gives the flexibillity to customise the web application. diff --git a/docs/3-visualiser/3-1-user-guide/steps.md b/docs/3-visualiser/3-1-user-guide/steps.md index 1b0ca14..58d28c8 100644 --- a/docs/3-visualiser/3-1-user-guide/steps.md +++ b/docs/3-visualiser/3-1-user-guide/steps.md @@ -2,7 +2,7 @@ sidebar_position: 5 --- -# Steps Panel +# Steps Posthoc's steps panel shows a list of steps of the current chosen trace. ![Alt text](steps.png) diff --git a/docs/3-visualiser/3-1-user-guide/tree.md b/docs/3-visualiser/3-1-user-guide/tree.md index 0b0a32a..eab0536 100644 --- a/docs/3-visualiser/3-1-user-guide/tree.md +++ b/docs/3-visualiser/3-1-user-guide/tree.md @@ -1,3 +1,3 @@ -# Tree Panel +# Tree [TODO] diff --git a/docs/3-visualiser/3-1-user-guide/viewport.md b/docs/3-visualiser/3-1-user-guide/viewport.md index b46d5d3..cd7db51 100644 --- a/docs/3-visualiser/3-1-user-guide/viewport.md +++ b/docs/3-visualiser/3-1-user-guide/viewport.md @@ -2,16 +2,16 @@ sidebar_position: 3 --- -# Viewport Panel +# Viewport [TODO] Pipe Adapter -Weighted A* +Weighted A\* -> Map support --> Edit Layer options to specify color of tile --> Make changes to grid parser -> Multiple solution -Layer name bug \ No newline at end of file +Layer name bug diff --git a/docs/3-visualiser/overview.md b/docs/3-visualiser/overview.md new file mode 100644 index 0000000..b2cd15f --- /dev/null +++ b/docs/3-visualiser/overview.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 2 +--- + +# Overview + +Posthoc visualises [search traces](./search-trace). It gives you a variety of tools to help you analyse and debug your algorithm. It's quick to get started and install-free — even better, it's robust and performant enough to support the largest of problem instances. + +![Complex view](../complex-view.png) + +## Get Posthoc + +### Posthoc Web + +You can use Posthoc directly in a browser. + +[Open Posthoc](https://posthoc.pathfinding.ai) + +### Posthoc PWA + +Optionally, you can [install Posthoc as a web app](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Installing) so that it runs in its own window. + +### Standalone Builds + +Check the [releases](https://github.com/path-visualiser/app/releases) page for a list of latest Windows and Linux releases. diff --git a/docs/4-tutorials/overview.md b/docs/4-tutorials/overview.md deleted file mode 100644 index 0d2060c..0000000 --- a/docs/4-tutorials/overview.md +++ /dev/null @@ -1,3 +0,0 @@ -# Overview - -[TODO] diff --git a/docs/6-api/overview.md b/docs/6-api/overview.md deleted file mode 100644 index 0d2060c..0000000 --- a/docs/6-api/overview.md +++ /dev/null @@ -1,3 +0,0 @@ -# Overview - -[TODO]