Skip to content

Commit

Permalink
Various changes to documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
spaaaacccee committed May 16, 2024
1 parent 0238381 commit ad26c94
Show file tree
Hide file tree
Showing 27 changed files with 761 additions and 802 deletions.
4 changes: 2 additions & 2 deletions docs/0-get-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ import imageA from "./image-3.png";
import imageB from "./30531.png";
import imageC from "./image-9.png";

# Hey there!
# Greetings

We're excited to have you here. 😊

Posthoc is a way to build quick-and-dirty visualisations ✨ for sequential decision-making algorithms, such as search algorithms. 🚀 Just print logs as [search traces](./search-trace) and drop those into the [Posthoc visualiser](./visualiser/overview).
Posthoc is a way to build quick-and-dirty visualisations ✨ for sequential decision-making algorithms, such as search algorithms. Just print logs as [search traces](./search-trace) and drop those into the [Posthoc visualiser](./visualiser/overview).

<Stack direction="row" sx={{ ...grid(360), gap: 2, mb: 4 }}>
<Card
Expand Down
46 changes: 34 additions & 12 deletions docs/2-search-trace.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,37 @@ sidebar_position: 2

# Search trace

The search trace is a YAML log of your algorithm's decisions. What, and how much, you want to log is up to you. Here are some ideas.
This is the centrepiece of Posthoc. ✨

The search trace is a YAML log of your algorithm's decisions. What, and how much, you want to log is up to you.

<figure>
```yaml title="single-agent-search.trace.yaml"
version: 1.4.0
events:
- { type: source, id: 0 }
- { type: expand, id: 0, f: 0, g: 0 }
- { type: generate, id: 1, pId: 0, f: 1, g: 1 }
- { type: close, id: 0, f: 0, g: 0 }
- { type: source, id: 2 }
```
<figcaption>Generic search events</figcaption>
</figure>
Each line of the `events` was output by a solver program during the execution of a single-agent search. The `type` property records what the step should represent in the context of the algorithm. In this case, events like `generate`, `expand`, and `close` would make sense.

:::warning
For the [Posthoc visualiser](./visualiser/overview), it's required to declare `version: 1.4.0` because older versions have a slightly different schema.
:::

Here are some more ideas.

<figure>
```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 }
- { type: move, id: 47, x: 0, y: 0 }
- { type: move, id: 18, pId: 0, x: 5, y: 2 }
```
<figcaption>Multi-agent plan execution</figcaption>
</figure>
Expand Down Expand Up @@ -54,7 +66,17 @@ Since YAML is a superset of JSON, your traces can be in JSON too.
<figcaption>Generic search events (JSON)</figcaption>
</figure>

Search traces should have the extensions `.trace.yaml` or `.trace.json`. It's required to declare `version: 1.4.0`.
Search traces should have the extensions `.trace.yaml` or `.trace.json`.

## Creating search traces

Search traces are zero-configuration to get started. Log events via print statements. Copy and paste those into a file, and chuck that into [Posthoc](./visualiser/overview). Quick-and-dirty's the spirit!

```cpp
cout << "- { type: " << type << ", id: " << id << "}"
```

If you want to invest a little more into Posthoc, pick up a JSON or YAML serialiser, or use the [Visualiser Adapter Protocol](/docs/visualiser-adapter-protocol).

## Decision tree

Expand Down Expand Up @@ -167,19 +189,19 @@ See the [search trace API reference](./search-trace#api) for a list of propertie

### `type`

The `type` property doesn't do anything, but it's used to drive some parts of **Posthoc**'s UI.
The `type` property should succinctly represent the kind of event that was recorded. It's used everywhere in **Posthoc**'s UI to identify events.

![Alt text](image-2.png)

### `clear`

Control when elements should be cleared.

| 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. |
| Value | Usage | Description |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `false` (default) | `clear: false` | Event remains visible until the end of the search trace. drawn. |
| `true` | `clear: true` | Event clears immediately after the step they're drawn. |
| `string` | `clear: close` | Event remains visible until another event of the same `id`, and the specified type (e.g. `close`), is encountered. This can also be an expression that evaluates to a string. |

```yaml title="clear.trace.yaml"
version: 1.4.0
Expand All @@ -200,7 +222,7 @@ events:

### `$for`

Repeat a view based on a value.
Repeat a view based on a value. This property is only evaluated at the time of the event.

```yaml {11-15} title="loop.trace.yaml"
version: 1.4.0
Expand All @@ -226,7 +248,7 @@ events:
### `$if`

Conditionally render a view.
Conditionally render a view. This property is only evaluated at the time of the event.

```yaml title="if.trace.yaml"
version: 1.4.0
Expand Down
9 changes: 1 addition & 8 deletions docs/3-visualiser/3-1-user-guide/extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,4 @@ Maps are an escape-hatch from search traces, and allows you to hard-code a visua

Posthoc supports the following map formats by default. This list also shows up in **Settings view > Extensions > Map support**. We'll soon let you define custom formats via extensions.

### Built-in map formats

| Format | Extension | Description |
| ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Grid | `*.grid`, `*.map` | Moving AI grid map format. [Learn about this format here.](https://movingai.com/benchmarks/formats.html) |
| Network | `*.xy` | A single-file alternative of the DIMACS network graph format, obtained using `dimacs2xy` of the Warthog library. [Learn about XY and `dimacs2xy` here.](https://bitbucket.org/dharabor/pathfinding/src/neomaster/warthog) |
| Mesh | `*.mesh` | [Learn about mesh maps here.](https://bitbucket.org/shortestpathlab/benchmarks/src/master/mesh-maps) |
| Poly | `*.poly` | [Learn about poly maps here.](https://bitbucket.org/shortestpathlab/benchmarks/src/master/poly-maps/) |
[Read about built-in map support here.](./layers#built-in-map-formats)
Binary file added docs/3-visualiser/3-1-user-guide/image-6.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 13 additions & 1 deletion docs/3-visualiser/3-1-user-guide/interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ Manage connected solvers, adapters, renderers, and map parsers. [Read more about

## Customising views

### Choosing content for a views
### Choosing content for views

You can choose what content to display in views by clicking the dropdown menu on the top left.

Expand All @@ -187,9 +187,11 @@ The titlebar gives you commands that control Posthoc as a whole.

| Item | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New window | Create a new [linked window](#linked-window). |
| Add panel to the right | Create an empty view on the far right edge. |
| Add panel below | Create an empty view on the bottom edge. |
| Reset layout | Reset the panels to the original configuration. Depending on the screen size, this could be a vertical two-panel layout or a horizontal three-panel layout. |
| Reload window | Reload the window, clearing any current work. |

### Workspace menu

Expand All @@ -205,6 +207,16 @@ The titlebar gives you commands that control Posthoc as a whole.

The sidebar gives you quick access to Explore and Settings. In the future, you'll be able to pin items to the sidebar for quick access, and pop sidebar panels out into the main area.

## Linked window

You can create linked windows via **View > New window**. This is helpful if you have multiple monitors.

To help you identify windows that belong to the same workspace, when multiple windows are open, they're labelled **Group [letter]** on the top left corner.

![Alt text](image-6.png)

When the main window is closed, the oldest linked window becomes the main one.

## Drag and drop

You can import any supported file by dropping them into Posthoc.
Expand Down
11 changes: 9 additions & 2 deletions docs/3-visualiser/3-1-user-guide/layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,20 @@ Trace layers are supported by **event**, **viewport**, **graph**, **source**, an

### Map

Maps are a separate list of filetypes that we thought deserved first-class support. Typically, these represent domains for pathfinding search, like grids, networks, and meshes.
Maps typically represent domains &mdash; or operating environments &mdash; for pathfinding search, like grids, networks, and meshes. This is a separate list of filetypes that we thought deserved first-class support.

![Alt text](image-4.png)

It's optional to use maps because you might not be doing pathfinding search. We recommend you to use search traces for visualisation. But if you have files in a supported map format, it might be more convenient to use a map layer. You can import map files a map layer via **Source > Choose Map > Import Map**.

[Read about built-in map support here.](./extensions#map-support)
#### Built-in map formats

| Format | Extension | Description |
| ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Grid | `*.grid`, `*.map` | Moving AI grid map format. [Learn about this format here.](https://movingai.com/benchmarks/formats.html) |
| Network | `*.xy` | A single-file alternative of the DIMACS network graph format, obtained using `dimacs2xy` of the Warthog library. [Learn about XY and `dimacs2xy` here.](https://bitbucket.org/dharabor/pathfinding/src/neomaster/warthog) |
| Mesh | `*.mesh` | [Learn about mesh maps here.](https://bitbucket.org/shortestpathlab/benchmarks/src/master/mesh-maps) |
| Poly | `*.poly` | [Learn about poly maps here.](https://bitbucket.org/shortestpathlab/benchmarks/src/master/poly-maps/) |

### Query

Expand Down
1 change: 1 addition & 0 deletions docs/3-visualiser/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ Posthoc visualises [search traces](/docs/search-trace). It gives you a variety o
tools to help you analyse and debug your algorithm. It's quick to get started and
install-free &mdash; even better, it's robust and performant enough to support the
largest of problem instances.

![Complex view](../complex-view.png)

## Get Posthoc
Expand Down
2 changes: 1 addition & 1 deletion docs/4-visualiser-adapter-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: Visualiser Adapter Protocol ⚠️

# Visualiser Adapter Protocol

The **Visualiser Adapter Protocol** defines a communication interface between a solver and a visualiser.
The **Visualiser Adapter Protocol** connects solvers directly to the visualiser to enable interactivity and integrations that would otherwise not be possible with search trace files.

**Visualiser Adapter Protocol** goes beyond simple solution-based visualisations. It allows visualisers to interactively run queries on solvers, and solvers to return expressive visualisations as search traces, to help you understand, debug, and experiment with your code.

Expand Down
149 changes: 149 additions & 0 deletions src/components/AppBar.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
import {
CloseOutlined as CloseIcon,
DarkModeOutlined,
LightModeOutlined,
DragHandleOutlined as MenuIcon,
LaunchOutlined as OpenIcon,
} from "@mui/icons-material";
import {
Box,
Button,
Fade,
IconButton,
Stack,
Typography,
useScrollTrigger,
} from "@mui/material";
import PopupState, { bindTrigger } from "material-ui-popup-state";
import { createPortal } from "react-dom";
import l10n from "../pages/en-au.json";
import { space } from "../pages/space";
import { Logo } from "./Logo";
import { useMode } from "./ModeContext";
import { usePaper } from "./theme";
import { useSm } from "./useSm";

export function AppBar() {
const [mode, setMode] = useMode();
const sm = useSm();
const paper = usePaper();
const top = useScrollTrigger({ threshold: 0, disableHysteresis: true });
const menu = l10n.sections.map(({ url, label }) => (
<Button
sx={{ py: 1.5, px: 2, borderRadius: 32 }}
onClick={() => (location.href = url)}
>
<Typography color="text.primary" variant="button">
{label}
</Typography>
</Button>
));
const openPosthoc = (
<Button
startIcon={<OpenIcon sx={{ color: "primary.main" }} />}
sx={{ py: 1.5, px: 2, borderRadius: 32 }}
onClick={() => window.open(l10n.appUrl)}
>
<Typography color="text.primary" variant="button">
{l10n.openAppLabel}
</Typography>
</Button>
);
const darkToggle = (
<IconButton
sx={{ color: "text.primary" }}
onClick={() => setMode(mode === "dark" ? "light" : "dark")}
>
{mode === "dark" ? <LightModeOutlined /> : <DarkModeOutlined />}
</IconButton>
);
return (
<Box
sx={{
width: "100vw",
position: "fixed",
px: 2,
zIndex: (t) => t.zIndex.appBar,
}}
>
<Fade in>
<Stack
gap={1}
alignItems="center"
direction="row"
sx={{
p: 2,
mx: "auto",
mt: sm ? 2 : 4,
...(top ? paper(1) : {}),
width: 1000 + 8 * 4,
maxWidth: "100%",
height: 64,
borderRadius: 32,
}}
>
<Box sx={{ mr: 2, height: 32, minWidth: 32 }}>
<Logo />
</Box>
{sm ? (
<>
<Box sx={{ flex: 1 }}></Box>
{openPosthoc}
<PopupState variant="popover">
{(state) => (
<>
<IconButton {...bindTrigger(state)}>
<MenuIcon />
</IconButton>
{createPortal(
<Box
sx={{
...(state.isOpen
? { opacity: 1 }
: {
opacity: 0,
pointerEvents: "none",
}),
...paper(0),
transition: (t) =>
t.transitions.create([
"opacity",
"backdrop-filter",
]),
position: "fixed",
zIndex: (t) => t.zIndex.modal,
top: 0,
left: 0,
width: "100vw",
height: "100vh",
borderRadius: 0,
}}
>
<Stack gap={4} p={3.5} alignItems="flex-end">
<IconButton onClick={state.close}>
<CloseIcon />
</IconButton>
{darkToggle}
{menu}
{openPosthoc}
</Stack>
</Box>,
document.body
)}
</>
)}
</PopupState>
</>
) : (
<>
{menu}
{space()}
{openPosthoc}
{darkToggle}
</>
)}
</Stack>
</Fade>
</Box>
);
}
29 changes: 29 additions & 0 deletions src/components/Card.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
import { Box, Stack, StackProps, Typography } from "@mui/material";
import { ReactNode as RN } from "react";
import { usePaper } from "./theme";

export function Card({
image,
title,
subtitle,
...props
}: {
image?: RN;
title?: RN;
subtitle?: RN;
} & Omit<StackProps, "title">) {
const paper = usePaper();
return (
<Stack
justifyContent="center"
alignItems="center"
gap={1}
{...props}
sx={{ ...paper(1), p: 8, textAlign: "center", ...props.sx } as any}
>
{image ?? <Box height={64}></Box>}
<Typography variant="h3">{title ?? "Title"}</Typography>
<Typography variant="subtitle2">{subtitle ?? "Subtitle"}</Typography>
</Stack>
);
}
Loading

0 comments on commit ad26c94

Please sign in to comment.