touch-up to the wording and figures in design doc

design/cube_parts.svg

@@ -17,8 +17,8 @@
    inkscape:version="0.48.1 r9760"
    sodipodi:docname="cube_parts.svg"
    inkscape:export-filename="/home/andrew/mc/overviewerdocs/design/cube_parts.png"
-   inkscape:export-xdpi="67.92453"
+   inkscape:export-xdpi="63.639942"
-   inkscape:export-ydpi="67.92453">
+   inkscape:export-ydpi="63.639942">
   <defs
      id="defs4">
     <marker
@@ -56,9 +56,9 @@
      borderopacity="1.0"
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
-     inkscape:zoom="1.4"
+     inkscape:zoom="1.979899"
-     inkscape:cx="554.3654"
+     inkscape:cx="673.03608"
-     inkscape:cy="470.88322"
+     inkscape:cy="523.09315"
      inkscape:document-units="px"
      inkscape:current-layer="layer1"
      showgrid="true"
@@ -93,7 +93,8 @@
        id="path3386"
        inkscape:connector-curvature="0" />
     <g
-       id="g4606">
+       id="g4606"
+       transform="translate(0,20.000003)">
       <image
          width="240"
          height="120"
@@ -126,7 +127,8 @@
          style="fill:none;stroke:#00ff00;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
     </g>
     <g
-       id="g4614">
+       id="g4614"
+       transform="translate(-5,2.6171874e-6)">
       <image
          width="120"
          height="180"
@@ -189,14 +191,14 @@
          style="fill:none;stroke:#00ff00;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
     </g>
     <image
-       y="417.36218"
+       y="402.36218"
-       x="820"
+       x="890"
        id="image3128-0-9-6"
        xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPAAAAB4CAYAAADMtn8nAAAABHNCSVQICAgIfAhkiAAABRVJREFU eJzt3U9om3Ucx/En/ZPmf9Okuq7rKKtMBbeBCh5EEEQQdhHZpWAPgrcxPApDdCiMgZ6EMa8eNhgM lHkY7iIbqAgqCEWQbbB/qd2aNE3Sp23Spq13k8OH7oHl075fx/J5+qTp78Pv8uX3iwXY1a6fndkW o7H//+CdTy5G/GkQtb6n/QEA7BwFBoxRYMAYBQaMUWDAGAUGjFFgwBgFBoxRYMBYx/QNnq6rZ6bV ySnJlRuzUm5/MRvla4Ogy9r66rvfon7HnscODBijwIAxCgwYo8CAMQoMGKPAgDEKDBijwIAxCgwY YxLrCX349jFpcurZkUyk752rNKRcNjkk5V4/Oinlfp69J+Xy6YSUO3Jon5QLuqzV97/8Xn1212IH BoxRYMAYBQaMUWDAGAUGjFFgwBgFBoxRYMAYBQaM7blJrHMfvCVNTjVWmtLvGy/mpNxiY1XKtTc3 pVxWnHSqDmiTTsmwJOXUA7tSiUEpFxNXYEacKKuH2v8t6LL2T3/7k/psz2AHBoxRYMAYBQaMUWDA GAUGjFFgwBgFBoxRYMAYBQaM9fwk1qWP35OGf7bEEaE/H2u5oWZFyk0U0lJuYLBfypVroZSr1Fak XP+gNsF0sJiScupE1P3HS1JuS/zHqWeK3XpYlnJT40UpVyrXpVzQpUtf//C7+uyOsQMDxigwYIwC A8YoMGCMAgPGKDBgjAIDxigwYIwCA8Yin8S6cOq4NFrzaHFZ+n0bbe2MqOfGC1KuvtKScg8WalKu mNMmmFTqrYNT+0ekXEw8dCpcW5dyo3nt763WtTPAVEemxqTcfEP7Ozaaa1Ku1WpLuZfEWxZLlZ1P dp08f60jxA4MGKPAgDEKDBijwIAxCgwYo8CAMQoMGKPAgDEKDBiLXT87o144J7k9tyjlHohnJqkS 8QEpt97eivS9hVxSylWWtDOsisPRTnYthdrEUSKu3SaoGslo30s2FZdyf99deJKP0yExpK2XVw4f iPS981VtAvGX2XtSjh0YMEaBAWMUGDBGgQFjFBgwRoEBYxQYMEaBAWMUGDAW+ZlYV89MS5NdlYY2 mXS7rJ1hdaio3Zq32tTOTFpZ0947PDYp5VTby4+k3N15bZKt2dqQcmOFnJRrxbSJrf5UXsqpNmv/ SrkDzwxLuT/+KUm5vj6tIq++MCHl2pvyJGDHiz/65seOEDswYIwCA8YoMGCMAgPGKDBgjAIDxigw YIwCA8YoMGAs8kmsqH0x86Y02TW5T5v8+evOvJR7fmJUym1ta0eKqWdTtda12/BGh9NSLj7YL+XU hRCKk2xJ8Yyt6rL2vSwshVIul9Ym8vLimV3VhnzLYsdXeO7Kr+qzO8YODBijwIAxCgwYo8CAMQoM GKPAgDEKDBijwIAxCgwY6/lJrKhdPn1CGp1SJ4TqYVPKlcp1KTeSSUi5fFa7xVC9hW+1qU2ALdS1 yaRiRpuIelhuSLnDR1+WckPhnJQLuqz9k+evqc/2DHZgwBgFBoxRYMAYBQaMUWDAGAUGjFFgwBgF BoxRYMDYnpvEitqFU8elyS71rCt1YmuskJVy6plO8QHt7Kx0Mi7lMiltEqtS026pDLqs1c8u3lSf 3bXYgQFjFBgwRoEBYxQYMEaBAWMUGDBGgQFjFBgwRoEBY0xi9ZhPp9/QrjsUqbcnvvbiwShfGwRd 1ta7n1+O+h17HjswYIwCA8YoMGCMAgPGKDBgjAIDxigwYIwCA8YoMGDsP1je8qOk0Rv8AAAAAElF TkSuQmCC "
        height="120"
        width="240" />
     <g
-       transform="translate(750,-4.9999948)"
+       transform="translate(820,-19.999995)"
        id="g4614-4-2">
       <image
          width="120"
@@ -212,88 +214,119 @@
          style="fill:none;stroke:#0000ff;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
     </g>
     <image
-       y="477.36218"
+       y="462.36218"
-       x="820"
+       x="890"
        id="image3209-6-5"
        xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAC0CAYAAABfTugdAAAABHNCSVQICAgIfAhkiAAABQtJREFU eJzt3c9r23Ucx/HvN/2mSdr8aNoubRdp1sVt4kURBEFw8yDoQdgugtCJp4kKY5cd58EyOhAviiAe PHgTPHjw5M2LQ3GgTLvhWk1tado1/ZFuSdqmafwHPLwOdV1fPB/nN9/9ePZzefP5fht+dfV8NxC8 9dG3oTKHx0vssP8C+H8R2ByBzRHYHIHNEdgcgc0R2ByBzYWfv/+atMna7uxLD1yuPZDmbnzzI5ux R4ATbI7A5ghsjsDmCGyOwOYIbI7A5ghsLmonstLgwtxf0txmqy3NXZ98SdqgnTr9pPS8Nz74ks3Y f+AEmyOwOQKbI7A5ApsjsDkCmyOwOQKbC6+9qW2UcqPj2hM3F6Wx/mRcmquFeWmu26pLc+2mdmds 6muPO2OcYHMENkdgcwQ2R2BzBDZHYHMENkdgc+HU5Flpk9UT75UeeKY4IM3NVrXN02xF24xFmWPS 3LPFlDS3tNGQ5ta3WtLcp9/9ciibMU6wOQKbI7A5ApsjsDkCmyOwOQKbI7C5qFwckgZ/+HVOmusG 0mIsWKutSXMnnhiV5sqjOWmuE2o/06PiXHuvI8199p72PTL1eVe++F7ajHGCzRHYHIHNEdgcgc0R 2ByBzRHYHIHNhZ+8+6q0YWk0d6QHPlXSNk8z9Uia25i/K821drUv0qdS2luN8Zj2s5/J9Etzfy/e l+aKw9pGLtmr/f9xgs0R2ByBzRHYHIHNEdgcgc0R2ByBzUX9Ke2twWptS5r7o1KV5vKFMWkuzPZJ c7vaVaYgimkv+S2vbUpztdiwNFfIZ6S50+Pa836eWZDmOMHmCGyOwOYIbI7A5ghsjsDmCGyOwOai rca2NNjTo/0sJCLtrtDKQkWaa3e1P3dkIC3NiVetgkSvtlGKh9r3tBqdpDR3e07bBA7ntLtgnGBz BDZHYHMENkdgcwQ2R2BzBDZHYHNRpbouDSZ7tbfy8lnti+ox8W7U4qp2N+qnO/9IcyfHBqW5hPj2 3sTEiDT3270laS4ubgKbO21pjhNsjsDmCGyOwOYIbI7A5ghsjsDmCGwuKo3kpcG6eHdrfmVDmnum rL1dWBjQ3i5c2dTuRlXFzVi6PyHN3bqr/W7Fzr72Ha9cWvv3TgyJd9CkKRxZBDZHYHMENkdgcwQ2 R2BzBDZHYHPRflf7XYMPW7vSnPqW370lbaNUKmjflwp7tDtjUaEszY1ltM3dblv7QFc6KX6PbFW7 I9eX1P69nGBzBDZHYHMENkdgcwQ2R2BzBDZHYHPaK35BEEy//bK08ioXte9L3byjfQ8q1tE2SqXj x6S5ykpdmnvhjPY7GH+fr0lzz5W1v9/yXlaaq/w5I81xgs0R2ByBzRHYHIHNEdgcgc0R2ByBzcmb rIM2PfmitBlbTxSl5/U1te9Q1epNaW4op73lt9fR7rQ9aLSkufETJWluR7wLxgk2R2BzBDZHYHME NkdgcwQ2R2BzBDZ3aJusgzb1zgVppZQLtqTnPdzWNkWLq9rzMintdxc+Pa59kf7m7Jo0xwk2R2Bz BDZHYHMENkdgcwQ2R2BzBDZns8k6aB9ePKfdGatrX5rvE7+TdfK4tskaTGtfpOcEmyOwOQKbI7A5 ApsjsDkCmyOwOQKbY5P1iHx86RVpM7a9syc9bzCrvf3ICTZHYHMENkdgcwQ2R2BzBDZHYHMENscm 64i6/Prz0maME2yOwOYIbI7A5ghsjsDmCGyOwOYIbO5f4STjXu/9BEMAAAAASUVORK5CYII= "
        height="180"
        width="120" />
     <path
        style="fill:none;stroke:#ff0000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 820,487.36218 20,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 50,0 0,-10 20,0 0,-10 20,0 0,-10 20,0 0,-10 20,0 0,-10 10,0"
+       d="m 890,472.36218 20,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 50,0 0,-10 20,0 0,-10 20,0 0,-10 20,0 0,-10 20,0 0,-10 10,0"
        id="path4600-6-4"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#00ff00;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 820,477.36218 10,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 10,0 0,120"
+       d="m 890,462.36218 10,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 20,0 0,10 10,0 0,120"
        id="path4602-8-6"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Lend)"
-       d="m 690,542.36218 100,0"
+       d="m 760,527.36218 100,0"
        id="path3386-6"
        inkscape:connector-curvature="0" />
     <text
        xml:space="preserve"
        style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans;-inkscape-font-specification:Andale Mono"
-       x="920"
+       x="990"
-       y="692.36218"
+       y="677.36218"
        id="text4768"
        sodipodi:linespacing="125%"><tspan
          sodipodi:role="line"
          id="tspan4770"
-         x="920"
+         x="990"
-         y="692.36218">24</tspan></text>
+         y="677.36218">24</tspan></text>
     <text
        xml:space="preserve"
        style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans;-inkscape-font-specification:Andale Mono"
-       x="1080"
+       x="1150"
-       y="552.36218"
+       y="537.36218"
        id="text4768-3"
        sodipodi:linespacing="125%"><tspan
          sodipodi:role="line"
          id="tspan4770-6"
-         x="1080"
+         x="1150"
-         y="552.36218">24</tspan></text>
+         y="537.36218">24</tspan></text>
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 820,677.36218 95,0"
+       d="m 890,662.36218 95,0"
        id="path4797"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 965,677.36218 95,0"
+       d="m 1035,662.36218 95,0"
        id="path4799"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 1100,557.36218 0,100"
+       d="m 1170,542.36218 0,100"
        id="path4801"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 1100,522.36218 0,-100"
+       d="m 1170,507.36218 0,-100"
        id="path4803"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 1120,422.36218 -40,0"
+       d="m 1190,407.36218 -40,0"
        id="path4805"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 1080,657.36218 40,0"
+       d="m 1150,642.36218 40,0"
        id="path4807"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 1060,657.36218 0,40"
+       d="m 1130,642.36218 0,40"
        id="path4809"
        inkscape:connector-curvature="0" />
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 820,657.36218 0,40"
+       d="m 890,642.36218 0,40"
        id="path4811"
        inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans;-inkscape-font-specification:Andale Mono"
+       x="685"
+       y="547.36218"
+       id="text4768-3-8"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4770-6-5"
+         x="685"
+         y="547.36218">25</tspan></text>
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 705,562.36218 0,100"
+       id="path4801-6"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 705,512.36218 0,-100"
+       id="path4803-1"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 725,412.36218 -40,0"
+       id="path4805-1"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 680,662.36218 40,0"
+       id="path4807-5"
+       inkscape:connector-curvature="0" />
   </g>
 </svg>

design/designdoc.rst

@@ -6,9 +6,9 @@ to the right place!
 
 This document's scope does not cover the details of the code. The code is fairly
 well commented and not difficult to understand. Instead, this document is
-intended to give an explanation to how the Overviewer was designed and how all
+intended to give an explanation to how the Overviewer was designed, why certain
-the pieces fit together. Think of this document as commenting on how all the
+decisions were made, and how all the pieces fit together. Think of this document
-high level pieces of the code work.
+as commenting on how all the high level pieces of the code work.
 
 This document is probably a good read to anyone that wants to get involved in
 Overviewer development.
@@ -54,15 +54,14 @@ exist.
 About the Rendering
 ===================
 
-Minecraft worlds are rendered in an approximated Isometric projection
+Minecraft worlds are rendered in an approximated Isometric projection at an
-[#isomorphicref]_, or
+oblique angle. In the original design, the projection acts as if your eye is
-what I call the "Sim City projection" [#isomorphicnote]_. In the original design, the projection
+infinitely far away looking down at the world at a 45 degree angle in the
-acts as if your eye is infinitely far away looking down at the world at a 45
+South-East direction (now, the world can be rendered at any of the 4 oblique
-degree angle in the South-East direction (now, the world can be rendered at any
+directions).
-of the 4 oblique directions).
 
-.. [#isomorphicref] http://en.wikipedia.org/wiki/Isometric_projection
+.. image:: screenshot.png
-.. [#isomorphicnote] To be honest, I'm not entirely sure it's technically an isomorphic projection. There are a lot of very similar projections.
+    :alt: A screenshot of Overviewer output
 
 In order to render a Minecraft world, there are a few steps that need to happen.
 These steps are explained in detail in the next few sections.
@@ -76,28 +75,27 @@ Block Rendering
 ===============
 .. This section shows how each block is pre-rendered
 
-The first step is rendering the blocks from the textures. Each block is built
+The first step is rendering the blocks from the textures. Each block is "built"
-and cached in global variables of the :mod:`textures` module.
+from its textures into an image of a cube and cached in global variables of the
+:mod:`textures` module.
 
-Textures come in the size 16 by 16 [#f1]_. In order to render a cube out of
+Textures come in the size 16 by 16 (higher resolution textures are resized and
-this, I apply an `affine transformation`_ to the texture in order to skew it to
+the process remains the same). In order to render a cube out of this, an `affine
-the right shape.
+transformation`_ is applied to the texture in order to transform it to the top,
+left, and right faces of the cube.
 
 .. image:: texturecubing.png
     :alt: A texture gets rendered into a cube
 
-.. [#f1]
-    Textures can come in other sizes and are re-sized so this section applies
-    just the same.
-
 .. _affine transformation: http://en.wikipedia.org/wiki/Affine_transformation
 
-The result is an image of a cube that is 24 by 24 pixels large. This particular
+The result is an image of a cube that is 24 by 24 pixels in size. This
-size for the cubes was chosen for an important reason: 24 is divisible by 2 and
+particular size for the cubes was chosen for an important reason: 24 is
-by 4. This makes placement much easier. E.g. in order to draw two cubes that are
+divisible by 2 and by 4. This makes placement much easier. E.g. in order to draw
-next to each other in the world, one are drawn exactly 12 pixels over and 6
+two cubes that are next to each other in the world, one is drawn exactly 12
-pixels down from the other. These kind of placement decisions all happen on
+pixels over and 6 pixels down from the other. All placements of the cubes happen
-exact pixel boundaries.
+on exact pixel boundaries and no further resolution is lost beyond the initial
+transformations.
 
 The transformation happens in two stages. First, the texture is transformed for
 the top of the cube. Then the texture is transformed for the left side of the
@@ -105,11 +103,12 @@ cube, which is mirrored for the right side of the cube.
 
 Top Transformation
 ------------------
-The transformation from the top is a simple `affine transformation`_. It is
+
-actually several affine transformations: a re-size, a rotation, and a scaling;
+The transformation for the top face of the cube is a simple `affine
-but since multiple affine transformations can be chained together simply by
+transformation`_ from the original square texture. It is actually several affine
-multiplying the transformation matrices together, only one transformation is
+transformations: a re-size, a rotation, and a scaling; but since multiple affine
-actually done.
+transformations can be chained together simply by multiplying the transformation
+matrices together, only one transformation is actually done.
 
 This can be seen in the function :func:`textures.transform_image`. It takes
 these steps:
@@ -139,9 +138,11 @@ interpolation to show the pixels.
 
 Side Transformation
 -------------------
-The texture square is transformed for the sides of the cube in
+
-:func:`textures.transform_image_side`. This is another `affine transformation`_,
+The texture square is transformed for the sides of the cube in the
-but this time only two transformations are done: a re-size and a shear.
+:func:`textures.transform_image_side` function. This is another `affine
+transformation`_, but this time only two transformations are done: a re-size and
+a shear.
 
 1. First the texture is re-sized to 12 by 12 pixels. This is half the width of
    24 so it will have the correct width after the shear.