battle-map-tv 0.6.1

Display battle maps for TTRPGs on a secondary tv

Battle Map TV

Display battle maps for TTRPGs on a tv or monitor that lies flat horizontally on your table.

No more features than needed: just show an image the way you want. Optionally add a grid, initiative order and area of effect shapes.

For GM's with little time or who improvise their sessions: much easier to use in-session than a full blown VTT.

Features

• Works on Linux, macOS and Windows by using Python.
• Doesn't use a browser.
• Free and open source
• Works offline
• Simple UI
• Two windows:
  • one on the TV with your map and grid on it
  • one on your GM laptop with controls
• Import local image files to display on the tv.
• Scale, pan, center and rotate the image.
• Store the physical size of your screen to enable grid and autoscaling.
• Overlay a 1-inch grid.
• Automatically detect the grid in an image and scale to a 1 inch grid.
• Save settings so images load like you had them last time.
• Simple initiative tracker
• Overlay area of effects
  • snap to grid
  • rasterize to grid

Installation

• Open terminal or cmd.
• Check that you have Python installed by running the python --version command.
  • If you don't have Python, it's easy to install. See here: https://wiki.python.org/moin/BeginnersGuide/Download
• Install Battle Map TV with this command: python -m pip install battle-map-tv
• Then run it with: python -m battle_map_tv

Manual

• Drag the TV window to your TV and make it fullscreen with the 'fullscreen' button.
• Use the 'add' button to load an image.
• You can drag the image to pan. Zoom with your mouse scroll wheel or use the slider in the controls window.
• Close the application with the 'exit' button.

Set screen size

There are two text boxes to enter the physical dimensions of your secondary screen in milimeters. This is needed to display a grid overlay and autoscale the image to 1 inch.

Initiative tracker

In the controls window, you can add players and their initiative. The list will be sorted automatically. Just put a number and a name on each line, for example "1 barbarians" and "20 heroes".

The '+' and '-' buttons increase and decrease the font size.

The 'move' button moves the lists to different positions and rotations on the screen.

Area of effect

Click on one of the buttons for a shape like 'circle' or 'square'. Then click and drag anywhere in the TV window to create the shape in the size you want.

The default color for shapes is white, but you can also toggle another color with the color buttons.

You can delete a shape by right-clicking on it, or by using the 'Clear' button.

If the grid is enabled, points will automatically snap to the grid.

If you click 'rasterize', the edges of the shapes you make will fit the grid.

When creating a shape, hold 'shift' to freeze the size of the shape, but keep rotating.

Technical

• Uses PySide6 for the graphical user interface.
• Uses OpenCV to detect the grid on battle maps.
• Uses Hatch to build and release the package.