Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Created version 1.0.0 of HexJSON #2

Open
wants to merge 2 commits into
base: gh-pages
Choose a base branch
from
Open

Created version 1.0.0 of HexJSON #2

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1d7d29
Created version 1.0.0 of HexJSON that includes version numbering and …
Jun 18, 2017
3718dd8
Changed maxCoordinates to minCoordinates in order to match up with th…
Jun 24, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
53 changes: 45 additions & 8 deletions hexjson.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,25 +31,60 @@ <h1>HexJSON format</h1>
</div>

<div class="holder">
<p>We want to make sharing hexagon-based maps - such as our <a href="constituencies.html">UK constituency hex map</a> - easy. We've defined a simple <a href="http://jsonlint.com/">JSON format</a> to achieve that. The format is:</p>
<p>We want to make sharing hexagon-based maps - such as our <a href="constituencies.html">UK constituency hex map</a> - easy. We've defined a simple <a href="http://jsonlint.com/">JSON format</a> to achieve that.
The idea behind the format is that the layout is preserved, such that if for instance you have a map of the UK in HexJSON format,
you can understand the orientation of the hex coordinates by reading the JSON. The JSON will provide all information necessary to determine
the orientation and layout of the graph.
</p>

<p>The format is:</p>
<pre><code>{
"version": "1.0",
"layout": "odd-r",
"minCoordinates": "right-top",
"hexes": {
"E14000530":{"q":-3,"r":-11},
"E14000531":{"q":-3,"r":-1}
}
}</code></pre>
<p>The <code>layout</code> property should be one of the following <a href="http://www.redblobgames.com/grids/hexagons/#coordinates">coordinate systems</a>:</p>
<p>The <code>version</code> property follows the <a href="http://semver.org/">semantic versioning 2.0.0</a> standard.
We only use major and minor version numbers. If the version property is missing, it is assumed to be "1.0" as this JSON scheme is already used in production.
</p>

<p>The <code>layout</code> property should be one of the following <a href="http://www.redblobgames.com/grids/hexagons/#coordinates">coordinate system layouts</a>:</p>
<ul>
<li><code>odd-r</code> (pointy-topped, offset coordinate system, odd rows offset 1/2 hex to the right)</li>
<li><code>even-r</code> (pointy-topped, offset coordinate system, even rows offset 1/2 hex to the right)</li>
<li><code>odd-q</code> (flat-topped, offset coordinate system, odd columns offset 1/2 hex down)</li>
<li><code>even-q</code> (flat-topped, offset coordinate system, even columns offset 1/2 hex down)</li>
<li><code>axial-r</code> (pointy-topped, axial coordinate system)</li>
<li><code>axial-q</code> (flat-topped, axial coordinate system)</li>
</ul>
<p>The <code>minCoordinates</code> property defines the corner of the map where both axes reach their minimum value.
If the <code>minCoordinates</code> is <code>left-bottom</code>, for instance, the hexagons with the lowest q-coordinate are on the leftmost part of the map,
and the hexagons with the lowest r-coordinate are on the bottom part of the map. While a displaying agent may choose to revert or rotate the map,
at least the intention of the designer of the map is made clear by using the <code>minCoordinates</code> property.
This property usually matches the origin of the graph (<code>0,0</code>), except in axial coordinate system layouts.
</p>
<p>
The minCoordinates should be one of the following values:
<ul>
<li><code>odd-r</code> (pointy-topped)</li>
<li><code>even-r</code> (pointy-topped)</li>
<li><code>odd-q</code> (flat-topped)</li>
<li><code>even-q</code> (flat-topped)</li>
<li><code>left-top</code></li>
<li><code>left-bottom</code></li>
<li><code>right-top</code></li>
<li><code>right-bottom</code></li>
</ul>
<p>The <code>hexes</code> are then defined using unique keys for each. Every hex is positioned by providing column (<code>q</code>) and row (<code>r</code>) coordinates.</p>
If there is no defined minCoordinates, the assumption is that it is <code>left-bottom</code>, which is the standard position of the origin in graphs.
Please note that this differs from the <a href="http://www.redblobgames.com/grids/hexagons/#coordinates">coordinate system layouts</a> description,
which uses <code>left-top</code> minCoordinates.
</p>

<p>Finally, the <code>hexes</code> are defined using unique keys for each. Every hex is positioned by providing column (<code>q</code>) and row (<code>r</code>) coordinates.</p>
<p>You can add your own custom data fields to each hex if you want to. Just make sure you don't use the keys <code>q</code> and <code>r</code> as they will be the coordinates e.g.</p>
<pre><code>{
"version": "1.0",
"layout": "odd-r",
"minCoordinates": "right-top",
"hexes": {
"E14000530":{
"name": "Aldershot",
Expand All @@ -70,10 +105,12 @@ <h1>HexJSON format</h1>
...
}
}</code></pre>
<p><em>Note that with the minCoordinates for q and r in the right-top, the Aldershot location is much lower than the Aldridge-Brownhills location,
and both are to the left of the center of the map (assuming the center is located at at 0,0).</em>
</p>

</div>
</div>

<footer class="b1-bg">
<div class="holder">
&copy; 2017 <a href="https://odileeds.org/">ODI Leeds</a>. Released under an MIT license. <a href="https://github.com/odileeds/hexmaps">Source on Github</a>.
Expand Down