Log in



Hex Grid Renderer (HGR)

Hex Grid Renderer (HGR)is an Android app for creating hexagonal grids and exporting them to image files. It is intended as a utility for gamers who play tabletop games which use hex grids. It has a variety of options for modifying the grid, as described in more detail below. HGR is available in via Google Play for the low, low price of 0.0 Euros (that’s zero of your American dollars):

https://play.google.com/store/apps/details?id=net.wanderinghorse.android.hexish

It appears to be the only Android app of its kind available. HGR is my first Android app, but was not supposed to be. i was experimenting with some code for calculating hexagon geometries, wondering if i could use it to finally create “that game i’ve always wanted to do.” Somewhere along the way i kept adding features to help test it, and it kind of turned into a mini-app. So i went ahead and published it on Play, added some non-testing-related features (undo, load/save, and whatnot), and now it lives as a standalone app. And i still haven’t gotten around to working on that game.

 

Source Code: please see the source code page.

HGR Introduction

Hex Grid Renderer is a simple application for creating hexagon grids, intended for use by players of tabletop games which use hex maps. HGR appears to be the only app of its kind in the Google Market. HGR is BETA, and very possibly has some outstanding bugs (see further on down the page for the ones i know about). It is not terribly pretty, but what’s there seems to work. If i had had this app 20 years ago, i would have been a very happy gamer.

Features

  • Easily create hexagon grids with only a few finger-taps.
  • Customize the colors, labels, center dots, and border.
  • Export hex grids as image files to other Android Activities via Intents. What does that mean? It means it can export your hex grids directly to GMail, GDrive, Dropbox, printer services, and others.
  • Has undo (10 levels) and save/load support.
  • It speaks English and German. If you want it in a language of your choice, get in touch and i will send you the information you need to translate it :). Contact info is at the bottom.

ACHTUNG: If your device force-closes this immediately or when changing map sizes, then it has too little memory. See the NOTES section below for why.

Permissions

HGR requires EXTERNAL STORAGE WRITE permissions in order to save its images to the SD card (see below) before handing them off to services like GMail, GDrive, or Dropbox. If there were a way to do this without a file, andnot risk an out-of-memory error by buffering the exported data in a byte array, the app would need no special permissions.

Storage Locations

HGR stores its own state in the Android-provide app-private space (which requires no special permissions). In order to export the hexes as PNG files it needs to write them somewhere where other apps can read them, which means putting them on the SD card.  It stores any exported data under:

<SDCARD>/app-data/net.wanderinghorse.android.hexish/

HGR does not export via Android’s Media Manager because doing so forces the images into JPEG format (not sure why) and has atrocious results for these particular graphics (the labels are unreadable and the grids are fuzzy).

There is a menu entry which shows you the exact path for your device. Also be sure to check your Gallery, as new images normally show up there at some point.

Device Compatibility

HGR is has been seen to work on API7 devices(Android 2.1.x). It is tested on several emulator configurations (with various Android versions), a Samsung Galaxy S2 phone (Android 4.2), and an Asus TF300 tablet (also 4.2), and a Nexus 7 (2012 model, Android 4.3).

Notes and Caveats

  • No warranties,” and all that. It’s free for any purpose. The source code is available for download.
  • When exporting an image, a copy is placed in your SD storage under under SDCARD/app-data/net.wanderinghorse.android.hexish/. The menu has an entry which will show you the full path for your device. (Trivia: “hexish” was the package name i used while experimenting and neglected to change it before releasing the app. Changing it now would force me to upload HGR as a whole new app.)
  • If HGR suddenly crashes at startup (after it worked before), try the “Clear Data” option in the app control center to remove its persistent state. This “shouldn’t happen”, but just in case it does. i have never seen this happen, but can conceive of a couple cases where it might (e.g. the app getting killed by a power-off or the OS at exactly the wrong microsecond while HGR is writing its file).

Mini-HowTO

HGR is trivially simple to use and can be mastered in under 10 minutes. It uses a series of menus and popups to prompt for options relating to the configuration of the grid and other actions like loading/saving grids and exporting PNG images. Note that the UI is very primitive because my Android skills are primitive. As my experience with Android improves, HGR will be a good place to try out new ideas. i.e. the plan is to update the UI incrementally as i figure out what the Android UI API can and cannot do for me. HGR manages a small handful of basic drawing components, each of which has its own menu area (in version 20120709 this was changed from a set of menus to a preferences-style list):

  • Grid: (v20120709+) Modify the grid size and orientation (tall- vs. wide-grain).
  • Hexes: modify the hexagon colors, sizes, etc. In versions older than 20120709 this menu also holds the Grid options.
  • Dots: center-dots can have their size and color changed.
  • Labels: text markings on the hexes. They can be formatted to display the row/column numbers in a variety of ways.
  • Border: a simple border around the edge of the grid. It can be colored and its size changed.
  • Background: the color can be modified. TODO: use an image as a pen.
  • Toolbar: the toolbar (added in v20130921) is not on by default but can be enabled in the menu (that toggle is persistent). The toolbar is pretty basic, but it will be expanded to support more shortcuts once i find a suitable collection of icons which all fit together thematically :/.
Each of those elements has an associated “pen” object which describes the colors, stroke style, line width, etc., of the grid component. Any given component may be toggled on or off. e.g. if you just want center-dots or labels, without hexes, then toggle the hexes off. The associated menus allow one to manipulate the pens.Additional (non-pen) menus include:
  • Undo: undoes the last change made to the grid. Up to 15 levels of undo are enabled. Undo info is currently lost if the app exits. It would be very easy to allow undo info to persist across application sessions, and that is up for consideration (the first time i lose data, i’ll be motivated to take the 10 minutes to add this).
  • Export: export the hex grid in PNG format using Android Intents. In principal, any Intent which can accept PNG files can be a target for the export, but at least one popular Intent (Google+) is known to fail for unknown reasons. Exporting to GMail, GDrive, Dropbox, and a few lesser-known apps is known to work. HGR does not use Android media manager export mechanism because that converts these images to JPEG and the results are exceptionally poor in that format.
  • Load/Save: HGR saves the grid state automatically when Android “pauses” it, e.g. when switching apps or returning to the home screen, and loads automatically at startup, but these menus allow the user to save and load an arbitrary number of grid states . They are saved to app-private storage (in a JSON file), taking up very little space (currently something like 600 storage bytes per saved copy). The plan is to eventually also allow exporting these via intents and then importing them via whatever mechanism Android gives us for asking other Activities to select a file. (i’ve seen it done before but don’t know how it was done.)
  • Toggle Buffering: removed in v20120709. Toggles internal buffering of the hex grid. This can greatly improve scrolling speed, but otherwise has no benefits and has one major drawback: it drastically increases the amount of memory used by HGR and can easily lead to an out-of-memory error (force-close). Scrolling of the grid is really just “fluff,” so this feature was sacrificed for the sake of memory.

 

Known Problems

  • If the app starts up with a blank black area, use Hexes==>Radius to set the radius. It sometimes gets set to 0 and i do not know where it is happening. (This might be a side-effect only i am seeing, as a result of using test builds on my devices which leave older app state lying around.)
  • Export to G+ fails mysteriously. Seems to be resolved in newer G+ and/or Android versions. GDrive, GMail, and Dropbox exports are known to work, as well as a couple lesser-known apps i’ve tried.
  • If it crashes after changing radii or dimensions, or toggling on buffering, then the problem is almost certainly that the rendered grid takes up too much memory and Android is killing the app. Workaround: scale it back a notch. The memory hog is the drawing/scrolling parts, not the actual hex data (which has low, constant memory costs, independent of the number of hexes in the grid).
  • The mechanism for removing saved grids is very basic. It allows the user to delete only one entry at a time. If you want to delete all entries, and have more than a few, a much faster way is to use the “Clear Data” option in the application control panel (which will also clear any other persistent state, but there is nothing notable stored there). Note that the number of saved entries is not significant for storage purposes: each profile takes up less than a kilobyte of storage and they are all saved in a single file.

Reporting Problems, Feature Requests, etc.

Please send problem reports directly to me (sgbeal at googlemail).

Notable TODOs

While HGR is essentially feature-complete, there are a couple more notable TODOs (in no particular order, with no particular priority, and with no particular commitment that they will ever get done)…

  • Add stroke styles to the hexes and border pens. The first alpha version had this, but i have never added the JSON support for it, so it was removed. (It’s not hard, it just needs an hour or two of attention.)
  • SVG, as opposed to raster graphics.
  • Saving/Loading:
    • Export/import saved data (JSON, not images), either via SD or Intents.
    • Allow selection of a previous profile to overwrite. Overwriting is currently automatic if one re-uses a name (and there is no warning when this happens).
    • Improve the delete-saved-profiles view. A ListView of checkboxes or other multi-select list would be ideal.

i think that’s about it.

Leave a Reply

You must be logged in to post a comment.