added documentation

jo-mueller · Aug 13, 2023 · 5131d1e · 5131d1e
1 parent f9ec659
commit 5131d1e
Show file tree

Hide file tree

Showing 11 changed files with 53 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -7,7 +7,51 @@
 [![codecov](https://codecov.io/gh/jo-mueller/napari-boardgame-maker/branch/main/graph/badge.svg)](https://codecov.io/gh/jo-mueller/napari-boardgame-maker)
 [![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-boardgame-maker)](https://napari-hub.org/plugins/napari-boardgame-maker)
 
-Make boardgame tiles
+This plugin turns 2D grayscale images into 3D-printable landscape tiles for a certain all-time tabletop boardgame which revolves around building settlements, obtaining ressources expanding and collecting more points than your opponents.
+
+In short, images (for instance, [digital elevation models](https://en.wikipedia.org/wiki/Digital_elevation_model)) can be turned into surfaces like this:
+
+| Image | Created tile|
+| --- | --- |
+| <img src="./docs/imgs/sample.png"> | <img src="./docs/imgs/sample_as_tile.png"> |
+
+## Usage
+
+To use the boardgame tile maker, open it from the plugins menu (`Plugins > napari-boardgame-maker: Boardgame Tile Maker`) or from the tools menu (`Tools > Boardgame tile maker (npbgm)`). There are a few steps and parameters to set before the tile can be created.
+
+[](./docs/imgs/GUI_screenshot.jpg)
+
+Clicking on `Make hexagon` and `Make number field` will create a hexagonal shape in the viewer (which will be the outline of the tile) and a circular field (which can later be used to put some markers, figures, chips, etc. On the center of the board).
+
+![](docs/imgs/sample_with_shapes.png)
+
+The next step is to set the parameters for the tile. The following parameters can be set:
+
+### Radii and sizes
+
+The following sketch shows the different radii and sizes that can be set:
+
+![](./docs/imgs/stride_and_town.png)
+
+- `hexagon radius`: The radius of the hexagon (in pixels). Upon export, this will be rescaled to a desired physical size in mm.
+- `number field radius`: The radius of the number field (in pixels). Can also be set in mm units. The pixels are changed accordingly if the size of the whole hexagon is changed.
+- `stride`: The region next to the edge of the tile that should remain flat.
+- `town radius`: A circular region around the edges of the hexagonal tiles that should remain flat.
+
+### Topography
+
+The following parameters can be set to create the topography of the tile:
+
+![](./docs/imgs/slope_and_heights.png)
+
+- `slope`: Adds a smooth transition of a given width between the edge of the cropped topography and the level of the base platte. Setting this to zero will result in a sharp edge.
+- `z-multiplier`: The height of the topography is multiplied by this factor. This can be used to scale the topography to the desired height.
+- `Plate thickness`: The thickness of the base plate (in mm).
+
+### Export
+
+- CLicking on `produce tile` will run the workflow to create the tile
+- Clicking `Export` will open a dialog to save the tile as an `.stl` file. *Note*: The tile will be exported in the size of the hexagon radius. If the hexagon radius is set to 100 mm, the tile will be exported as a 100 mm hexagon.
 
 ----------------------------------
 
@@ -28,8 +72,6 @@ You can install `napari-boardgame-maker` via [pip]:
     pip install napari-boardgame-maker
 
 
-
-
 ## Contributing
 
 Contributions are very welcome. Tests can be run with [tox], please ensure

diff --git a/docs/imgs/GUI_screenshot.jpg b/docs/imgs/GUI_screenshot.jpg
diff --git a/docs/imgs/sample.png b/docs/imgs/sample.png
diff --git a/docs/imgs/sample_as_tile.png b/docs/imgs/sample_as_tile.png
diff --git a/docs/imgs/sample_with_labels.png b/docs/imgs/sample_with_labels.png
diff --git a/docs/imgs/sample_with_shapes.png b/docs/imgs/sample_with_shapes.png
diff --git a/docs/imgs/slope_and_heights.png b/docs/imgs/slope_and_heights.png
diff --git a/docs/imgs/stride_and_town.png b/docs/imgs/stride_and_town.png
diff --git a/docs/imgs/tile_side_view.png b/docs/imgs/tile_side_view.png
diff --git a/setup.cfg b/setup.cfg
@@ -32,6 +32,7 @@ install_requires =
     qtpy
     napari-stl-exporter
     vedo
+    napari-tools-menu
 
 python_requires = >=3.8
 include_package_data = True

diff --git a/src/napari_boardgame_maker/_widget.py b/src/napari_boardgame_maker/_widget.py
@@ -25,8 +25,9 @@
 import os
 import numpy as np
 import napari
+from napari_tools_menu import register_function
 
-
+@register_function(menu="Games > Boardgame tile maker (npbgm)")
 class BoardgameMakerWidget(QWidget):
     # your QWidget.__init__ can optionally request the napari viewer instance
     # in one of two ways:
@@ -84,6 +85,9 @@ def eventFilter(self, obj: QObject, event: QEvent):
     def _create_outline(self):
         """Create outline of tile hexagon"""
 
+        if self.outline_layer not in self.viewer.layers:
+            self.outline_layer = None
+
         if self.outline_layer is None:
             self.center = np.asarray(self.image_layer_select.value.data.shape) / 2
 
@@ -106,6 +110,8 @@ def _create_outline(self):
     def _create_number_field(self):
         """Create number field around center of tile"""
 
+        if self.number_field_layer not in self.viewer.layers:
+            self.number_field_layer = None
 
         if self.number_field_layer is not None:
             center = self.number_field_layer.data[0][1:].mean(axis=0)