Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Stencil3 Manual

Last updated for: v3.0.0-alpha.7

This manual is best viewed in MdBook: [https://mrt-map.github.io/stencil3/docs]. (It is also still available on GitHub Wiki for historical purposes.)

Stencil3 is an application maintained and built by MRT Mapping Services to edit PLA3 map data for the street map of the MRT City Map.

Installation

  • Universal
    • Cargo
      • Run cargo install --git https://github.com/MRT-Map/stencil3
      • Launch stencil3 with stencil3
  • Windows
    • Scoop (untested)
      • scoop install "https://raw.githubusercontent.com/MRT-Map/stencil3/master/build/windows/scoop.json"
    • msi
      • Download the .msi file in the assets folder of the latest GitHub release
      • Open the .msi file and follow the instructions
      • Launch stencil3 in file explorer in [Drive]:\Program Files\stencil3\bin
      • Remember to pin it to start/taskbar if it isn’t indexed in the search bar ;)
  • MacOS
    • dmg
      • Download the .dmg file in the assets folder of the latest GitHub release
      • Open the .dmg file and drag the application into the folder
      • Launch stencil3
    • Homebrew
      • brew install --cask mrt-map/mrt-map/stencil3
  • Linux
    • deb
      • Download the .deb file in the assets folder of the latest GitHub release
      • Extract & install the file… TODO write instructions
    • Arch PKGBUILD
      • Add to /etc/pacman.conf: 
        [arch-mrt-map]
Server = https://mrt-map.github.io/arch-mrt-map/x86_64
SigLevel = Optional TrustAll
      • sudo pacman -Sy stencil3

FAQ & Troubleshooting

  1. Can I use Stencil3 for general purpose map annotating?
    • You technically can, though it’s not recommended
  2. I found a bug / problem! / Stencil3 crashed on me!
    • Check the logs folder for the latest panic log.
      • Check here (TODO) to see where your logs folder is.
      • If it’s to do with toml deserialisation, check that your toml files are syntactically correct.
    • Otherwise, open an issue in this repository, and check if your issue is a duplicate of another one
    • (You can also DM me on Discord, but if you have a GitHub account please use issues)
  3. CJK characters aren’t showing / I see black boxes as text
    • The default font only supports Latin, Greek and Cyrillic letters. You may need to import custom fonts from your system at Settings > UI > Custom Fonts.
      • Set your custom font as Lowest if you do not want your custom font to override the default font.

Quickstart

Input

This page describes the behaviour of and notation used for keyboard and mouse inputs in Stencil3.

Keyboard

  • X: one key
  • Modifier+X: hold down Modifier while pressing the key
    • Ctrl is the control key on Windows and Linux and the command key on macOS
    • Alt is the alt key on Windows and Linux and the option key on macOS
    • Shift is the shift key

Mouse

  • L-Click, M-Click and R-Click refer to the left, middle and right mouse buttons
    • If you do not have access to a middle mouse button, Alt+L-Click is the substitute for M-Click
  • Dbl-X-Click refers to double-clicking a mouse button.
  • Scroll refers to scrolling with the mouse wheel. This mostly refers to vertical scrolling, but horizontal scrolling is possible with mice that support it.

Layout

layout

  1. The menu bar contains menu items in the order of Information, File, Edit, View, as well as a status message.
    • The Information category contains windows to show information about Stencil3 as well as settings and an option to quit.
    • The File category contains functionality for manipulating projects and namespaces.
    • The Edit category contains functionality for manipulating components.
    • The View category contains options to open windows or move the tilemap.
    • The status message shows help and/or status information about your current mode or recently done action.
  2. The average milliseconds per frame is shown here. On a good computer, this should be under 16.7ms/frame (60fps).
  3. The tilemap takes up most of the window and is your primary work area.
  4. The toolbar lets you switch between modes.
    • Select Mode allows selecting of components.
    • Nodes Mode allows selecting of nodes.
    • There are 3 Create Modes for point, line and area. It will also show options for the namespace new components will be under as well as its skin type.
    • If the current project is not attached to any folder on disk, “NOT SAVED” will show here.
  5. The X and Z coordinate of your mouse cursor as well as your current zoom and an option to reset the map view.
  6. The Component Editor lets you edit the component data. It also shows the coordinates of the nodes of the component.
  7. The Project Editor lets you configure the project’s skin, basemap and namespaces. It also contains a list of components where you can select them, move them into view and delete them.
  8. The History Viewer shows your project history.
  9. You may find notifications showing up here. These are usually related to projects or namespaces. Any errors or warnings will also show here.

Tilemap

The Tilemap is on the centre of the window by default. It automatically loads the basemap specified in the project configuration to the screen such that components can be plotted over it.

Panning

M-click and drag to move the map. You can also use arrow keys.

With the scroll wheel, Scroll to pan vertically, and Shift+Scroll to pan horizontally. The directions can be inverted in the settings.

On a supported trackpad, drag with two fingers.

Zooming

Ctrl+Scroll to zoom. You can also use Alt+Plus and Alt+Minus. Note that Ctrl+Plus/Minus doesn’t work and zooms the UI instead. This is an eframe feature which I have no clue how to disable.

On a supported trackpad, pinch with two fingers.

Reset View

Press Alt+0 to reset the view to the default position and zoom. You can do the same with the button on the top-right.

Select Mode

The Select Mode allows selecting of components.

Selecting

To select a component, L-Click it. Shift+L-click to select multiple components. If you have multiple components, Shift+L-Clicking selected components also deselects them one by one.

Select a point by clicking within its hitbox. Select a line by clicking near its outline.

For areas, zooming in will reveal a transparent body which is not selectable. This is so that other components within the footprint of this area are selectable. The selectable area is instead the opaque area around the edges.

After selecting, the Component Editor will show information about the selected components.

Marquee Select

L-Clicking and dragging will show a dashed box. When the mouse is released, any components fully within this box will be selected. You can also Shift+L-Click and drag to add to the existing selection.

Moving

To move a component, hold Ctrl and drag the component.

Clipboard

Ctrl+C to copy and Ctrl+X to cut the selected components, and Ctrl+V to paste them. Note that components will be pasted into the namespace where the last component was created in.

Deleting

Delete to delete the selected components.

Context Menu

R-Click a component to view its context menu where you can copy, cut, paste and delete the component using your mouse.

Component Editing

The Component Editor is on the left of the window by default.

When no components are selected, it shows the number of components in your clipboard.

Information

Below is the information that will be shown. Note that some fields are only editable when only one component is selected, or if all values are the same.

  • The namespace the components are under. To create new namespaces, see the Project Editor.
  • The ID of the components. This is typically randomly-generated and not editable.
  • The display name of the components. This will show on the rendered map.
  • The layer of the components.
  • The skin type of the components.
  • A list of attributes. This will be serialised into TOML inside the PLA3 file.
    • The Description and Tags fields from PLA2 show up here. Description can be stored as a string in the top level. Each tag can be stored as a True boolean in the top level.
      • For example, the oneWay tag from PLA2 shows up as oneWay = true in the attributes table of PLA3.
  • The list of nodes the component has. This shows both ending coordinate and Bézier control points.
    • A simple line to a coordinate shows a simple coord entry.
    • A quadratic curve shows ctrl and coord.
    • A cubic curve shows ctrl1, ctrl2 and coord.
    • Labels are also shown. This is a future feature to prevent components with nodes on the same coordinate from joining together, and is useful for roads at different levels. Functionality to edit the label will be implemented in the future.
    • If the component is a line, there is also a button to reverse the node order.

Create Mode

The Create Modes allow creating of components.

Before creating any components, you will need to select a namespace to create components under as well as the skin type of the new components.

Point

L-Click on the map to create a new point.

Line

L-Click on the map to start a new line and add nodes to it. Hold Ctrl to snap to angle. Shift+L-Click to create control points for Bézier curves.

Dbl-L-Click to finish the line. Note that lines must have at least two nodes.

R-Click to undo a node or control point.

Area

Generally the same as lines, with the following differences:

  • The area will be automatically closed upon finishing
  • Areas must have at least three nodes, or two if the second node is a Bézier curve.

Nodes Mode

Not done

History

Undo & Redo

Ctrl+Z to undo, Ctrl+Shift+Z to redo.

History Window

The history window is located in a tab on the right side of the window by default. This shows the project’s history from when the project was opened.

Project Management

The Project Editor is on the right side of the window by default.

Namespace & Component List

On top is a list of namespaces. You can toggle each namespace’s visibility (if the project is attached to a folder on disk) as well as delete namespaces if they are empty.

Clicking on a namespace reveals a list of components within the namespace. Each component can be selected, moved into view or deleted.

Skin Status

This shows the status of the skin loading. If an error is shown, click the Reload button under the Skin section.

Configuration

This specifies the project configuration. More information can be found in the Project TOML page.

Loading & Importing

Opening Project

Projects are stored in folders. Go to File > Open or Ctrl+O to choose a folder to open. TODO check whether project.toml is necessary

Reloading Namespaces

File > Reload or Ctrl+R to reload the project’s namespaces from disk. This may be useful if you have manually added namespaces or components to disk.

Importing Namespaces

Go to File > Import Namespaces. After selecting one of the options and choosing the files to load, the components inside the file will be imported into your project.

Namespaces will be created if they were not yet created in your project. Warnings will also be returned if duplicate IDs exist in the file, or when a component of the same ID already exists in the project.

Currently supported formats are pla3.zip, pla2.msgpack and pla2.json.

Saving & Exporting

Saving Project

If the project is already attached to a folder on disk, going to File > Save or Ctrl+S will save the project to disk. To save the current project to another folder, go to File > Save As or Ctrl+Shift+S.

If the project is currently not saved to a folder on disk, File > Save and Ctrl+S will work the same as File > Save As and Ctrl+Shift+S and will prompt for a folder to save the project to.

Exporting Namespaces

Go to File > Export Namespaces and select the namespaces you want to export. You will then be prompted one by one for the path to save the files to.

To pla3.zip

A pla3.zip file consists of multiple pla3 files under the same namespace. It is similar to a namespace folder of pla3 files, just that it is conveniently compressed into one file for easy transport.

To pla2.json/pla2.msgpack

The older pla2 format stores all components of the same namespace in one file, and is generally in MessagePack format (although JSON is fully supported too).

Settings

Map

UI

Shortcut

Miscellaneous

Project TOML

Directories

Environment Variables

Welcome to Stencil2’s manual!

Last updated for: v2.2.0

Stencil2 is a software maintained and built by the MRT Mapping Organisation to edit map data for the street map of the MRT City Map.

Installation

  • Universal
    • Cargo
      • Run cargo toolchain install nightly if the nightly compiler isn’t installed
      • Run cargo +nightly install --git https://github.com/MRT-Map/stencil2
      • Launch stencil2 with stencil2
  • Windows
    • Scoop (untested)
      • scoop install "https://raw.githubusercontent.com/MRT-Map/stencil2/master/build/windows/scoop.json"
    • msi
      • Download the .msi file in the assets folder of the latest GitHub release
      • Open the .msi file and follow the instructions
      • Launch stencil2 in file explorer in either [Drive]:\Program Files\stencil2\bin or [Drive]:\Program Files (x86)\stencil2\bin
      • Remember to pin it to start/taskbar if it isn’t indexed in the search bar ;)
  • MacOS
    • dmg
      • Download the .dmg file in the assets folder of the latest GitHub release
      • Open the .dmg file and drag the application into the folder
      • Launch stencil2
    • Homebrew
      • brew install --cask mrt-map/mrt-map/stencil2
  • Linux
    • deb
      • Download the .deb file in the assets folder of the latest GitHub release
      • Extract & install the file… TODO write instructions
    • Arch PKGBUILD
      • Add to /etc/pacman.conf: 
        [arch-mrt-map]
Server = https://mrt-map.github.io/arch-mrt-map/x86_64
SigLevel = Optional TrustAll
      • sudo pacman -Sy stencil2

Usage

See Basics and Advanced Topics

FAQ & Troubleshooting

  1. Can I use Stencil2 for general purpose map annotating?
    • You technically can, though it’s not recommended
  2. I found a bug / problem! / Stencil2 crashed on me!
    • In the data directory, check under the TODO folder for the latest panic log for an error message.
      • If it’s to do with toml deserialisation, check that your toml files are syntactically correct.
    • Otherwise, open an issue in this repository, and check if your issue is a duplicate of another one
    • (You can also DM me on Discord, but if you have a GitHub account please use issues)
  3. Tiles don’t show up!
    • Update: This has been found to be a problem with the UI. Shake your cursor over anywhere except the map to make the tiles load.
    • Try reopening Stencil2. This is known to fix the issue on macOS
    • If not, open up the window settings / window_settings.toml and try disabling one of the backends and then restarting to see if it fixes the issue. This is known to fix the issue on Windows
    • Otherwise, raise an issue (recommended) or contact 7d

Layout

Loading a Project

  • Under Project on the right panel, click Open and select a folder with PLA files in it (or a new folder)
  • A list of namespaces will be loaded along with the default namespace _misc

Namespace Creation

  • Under Project on the right panel, input the namespace’s name and click +
  • Remember to do this before adding anything to the namespace, in case you forget (it does not have a way to mass-move components between namespaces yet)

Component Creation

Points

  • Click Point on the toolbar or press 4 on the keyboard
  • Left-click on the map where you want your point to be

Lines and Areas

  • Click Line on the toolbar or press 5 on the keyboard for lines; or
  • Click Area on the toolbar or press 6 on the keyboard for areas
  • Left-click on the map where you want the line/area to start. This is your first node
  • Continue left-clicking to place more nodes and continue the line/area
    • Hold down the left alt key for angle-snapping
  • If you had made a mistake with the previous node, left-click on the previous node to remove it
  • Right-click to complete the line/area at the last node placed
    • For areas, left-clicking on the first node completes it too

Component Editing

  • Click Select on the toolbar or 1 on the keyboard, then left-click the component you want to edit

Editing Component Information

  • A panel of text boxes and sliders should appear on the left of the screen
    • ns. is the namespace that the component belongs to. It should be a three-letter code that your project organisers have assigned, or that you have registered
      • If you have just created a namespace, remember to set it (before)
      • This field should be automatically prefilled the next time you edit a component’s information
    • id should be prefilled automatically with a randomly-generated ID
    • Displayed as is the text that would appear on the final map
    • Description is a brief description of the component
    • Component type is what the component would show up as on the final map
    • Tags is a comma-separated list of tags on the component
      • e.g. oneWay makes a line one-directional
    • Layer controls whether the component appears below or above other components
    • In lines, Reverse direction reverses the order of the nodes. This is useful for one-directional components
    • A list of coordinates is shown as well below the information fields
      • In lines, the green coordinate points to the start of the line and the red coordinate points to the end of the line. Both these coloured coordinates point to coloured handles on the component on the tilemap

Moving Components

  • Right-click and drag the component to move it

Editing Individual Nodes

  • Click Edit Nodes on the toolbar or 2 on the keyboard
  • For the large circles:
    • right-click and drag to move the node
    • right-click without dragging to delete the node
  • For the small circles:
    • right-click to create a node

Deleting Components

  • Click Delete on the toolbar or 3 on the keyboard
  • Left-click a component to delete it

Undo & Redo

  • Click Edit > Undo on the menu, u on the keyboard, or Undo under History on the right panel to undo
  • Click Edit > Redo on the menu, y on the keyboard, or Redo under History on the right panel to undo

View All Components

  • You can do this under Component List on the right panel
  • Click Move to next to a component in the list to shift the viewport to the first node of the component

Saving the project

  • Under Project on the right panel, Click Save
  • There is also an autosave every 1 minute

Deleting a namespace

  • Under Project on the right panel, hide the namespace and then click X
    • Namespaces can only be removed when it has no components

Quitting

  • Click Stencil v(version) > Quit on the menu or esc on the keyboard to quit

Configuration

Tilemap settings

Under Settings > Tilemap, you can set

  • the initial zoom level
  • the base map to use

Adding a base map

Scroll to the bottom and click Add and a new base map entry will be created for you. Alternatively, click Import to import a file containing a base map configuration (TOML file). An example of this file can be seen when you export any entry you have.

Selecting a base map

Click Select next to the number in a base map entry and it will be hoisted to the top. The topmost entry is used in the tilemap.

Exporting/Deleting a base map

Click Export/Delete next to the number in a base map entry.

Configuring the window

Under Settings > Window, you can set

  • the GPU backends to test for and use
  • the window mode (fullscreen, windowed, etc)
  • on Linux, the display protocol (Xorg/Wayland)

Configuring the key mappings

Under Settings > Keymap

Configuring miscellaneous settings

Under Settings > Misc

Notification Log

All notifications that have been sent are also logged to View > Notification Log.

File System Data

The data directory of Stencil2 is

  • %APPDATA%/Roaming/stencil2 on Windows
  • ~/Library/Application Support/stencil2 on macOS
  • ~/.local/share/stencil2 on Linux

tile_settings.toml

TODO UPDATE The file version of the tilemap settings. TOML spec here

Defaults:

# The base URL of the tiles to pull from. Must be a valid URL, most likely of the form
# `<url>/tiles/<world>/flat` where `<url>` shows the server's Dynmap client and
# `<world>` is the ID of the world that you want tiles for
url = "..."
# The zoom level of a tile in the maximum zoom
max_tile_zoom = 8
# The distance that a tile of the maximum zoom level represents
max_zoom_range = 32.0

# The zoom level to start with when opening Stencil2
init_zoom = 7.0

window_settings.toml

TODO UPDATE The file version of the windows settings. TOML spec here

Defaults:

# Optional. Used by Winit to decide the type of fullscreen of the window, or whether it is fullscreen
# Possible values: `Windowed`, `BorderlessFullscreen`, `SizedFullscreen`, `Fullscreen`
window_mode = "Windowed"
# Optional, Linux only. Used by Winit to decide whether to start the window with Xorg or Wayland
# Possible values: `Auto`, `Xorg`, `Wayland`
display_server_protocol = "Auto"

# Optional, each variable must be included if specified. Used by Wgpu to decide which GPU backend to render with
[backends]
vulkan = true
metal = true
dx12 = true
dx11 = true

keymap_settings.toml

TODO UPDATE

misc_settings.toml

TODO UPDATE

logs

The log files that are output by Stencil2. Feel free to delete them if they grow too large, but it may be useful for debugging

panic

The panic log files that are output by Stencil2. Feel free to also delete them if they grow too large, but it may also be useful for debugging

Environment Variables

When starting Stencil2 from the command line, you can specify some environment variables to change how it behaves

These are not included within Stencil2’s configuration/settings menus because they mostly serve as debugging tools

  • NO_DOWNLOAD=true Ignores the configured tilemap and renders a white and gray checkboard as the tilemap
  • RUST_LOG=... Configures the logger. Accepts env_logger syntax. Configurations with low levels set (trace) tend to affect both performance and disk memory. Be warned :)