An ESP2866 is never going to compete with an actual graphics card. But it has more than enough oomph to explore the fundamentals of 3D graphics. In this short tutorial we'll go through the basics of creating a 3D scene and displaying it on an OLED screen using MicroPython.
This kind of mono wireframe 3D reminds me of early ZX Spectrum 3D games which mostly involved shooting one wobbly line at another, and looking at the resulting wobbly lines. It was awesome.
The 3D code here is based on this example for Pygame with some simplifications and the display code modified for working with framebuf.
Requirements
- Wemos D1 v2.2+ or good imitations.
- 0.96in OLED Screen 128x64 pixels, I2c interface.
- Breadboard Any size will do.
- Wires (Loose ends, or jumper leads.)
Setting up
The display used here is a 128x64 OLED which communicates over I2C. We're using the ssd1306 module for OLED displays available in the MicroPython repository to handle this communication for us, and provide a framebuf drawing interface.
Upload the ssd1306.py file to your device's filesystem using the ampy tool (or the WebREPL).
ampy --port /dev/tty.wchusbserial141120 put ssd1306.py
With the ssd1306.py file on your Wemos D1, you should be able to import it as any other Python module. Connect to your device,
and then in the REPL enter:
from machine import I2C, Pin
import ssd1306
If the import ssd1306 succeeds, the package is correctly uploaded and you're good to go.
Wire up the OLED display, connecting pins D1 to SCL and D2 to SDA.Provide power from G and 5V.
To work with the display, we need to create an I2C object, connecting via pins D1 and D2 — hardware pin 4 & 5 respectively. Passing the resulting i2c object into our SSD1306_I2C class, along with screen dimensions, gets us our interface to draw with.
from machine import I2C, Pin
import ssd1306
import math
i2c = I2C(scl=Pin(5), sda=Pin(4))
display = ssd1306.SSD1306_I2C(128, 64, i2c)
To support developers in [[ countryRegion ]] I give a [[ localizedDiscount[couponCode] ]]% discount on all books and courses.
[[ activeDiscount.description ]] I'm giving a [[ activeDiscount.discount ]]% discount on all books and courses.
Modelling 3D objects
The simplest way to model objects in 3D space is to store and manipulate their vertices only — for a cube, that means the 8 corners.
To rotate the cube we manipulate these points in 3 dimensional space. To draw the cube, we project these points onto a 2-dimensional plane, to give a set of x,y coordinates, and connect the vertices with our edge lines.
Rotation along each axis and the projection onto a 2D plane is described below.
The full code is available for download here if you want to skip ahead and start experimenting.
3D Rotation
Rotating an object in 3 dimensions is no different than rotating a object on a 2D surface, it's just a matter of perspective.
Take a square drawn on a flat piece of paper, and rotate it 90°. If you look before and after rotation the X and Y coordinates of any given corner change, but the square is still flat on the paper. This is analogous to rotating any 3D object along it's Z axis — the axis that is coming out of the middle of the object and straight up.
The same applies to rotation along any axis — the coordinates in the axis of rotation remain unchanged, while coordinates along other axes are modified.
# Rotation along X
y' = y*cos(a) - z*sin(a)
z' = y*sin(a) + z*cos(a)
x' = x
# Rotation along Y
z' = z*cos(a) - x*sin(a)
x' = z*sin(a) + x*cos(a)
y' = y
# Rotation along Z
x' = x*cos(a) - y*sin(a)
y' = x*sin(a) + y*cos(a)
z' = z
The equivalent Python code for the rotation along the X axis is shown below. It maps directly to the math already described. Note that when rotating in the X dimension, the x coordinates are returned unchanged and we also need to convert from degrees to radians (we could of course write this function to accept radians instead).
def rotateX(self, x, y, z, deg):
""" Rotates this point around the X axis the given number of degrees. Return the x, y, z coordinates of the result"""
rad = deg * math.pi / 180
cosa = math.cos(rad)
sina = math.sin(rad)
y = y * cosa - z * sina
z = y * sina + z * cosa
return x, y, z
Projection
Since we're displaying our 3D objects on a 2D surface we need to be able to convert, or project, the 3D coordinates onto 2D. The approach we are using here is perspective projection.
If you imagine an object moving away from you, it gradually shrinks in size until it disappears into the distance. If it is directly in front of you, the edges of the object will gradually move towards the middle as it recedes. Similarly, a large square transparent object will have the rear edges appear 'within' the bounds of the front edges. This is perspective.
To recreate this in our 2D projection, we need to move points towards the middle of our screen the further away from our 'viewer' they are. Our x & y coordinates are zero'd around the center of the screen (an x < 0 means to the left of the center point), so dividing x & y coordinates by some amount of Z will move them towards the middle, appearing 'further away'.
The specific formula we're using is shown below. We take into account the field of view — how much of an area the viewer can see — the viewer distance and the screen height and width to project onto our framebuf.
x' = x * fov / (z + viewer_distance) + screen_width / 2
y' = -y * fov / (z + viewer_distance) + screen_height / 2
Point3D code
The complete code for a single Point3D is shown below, containing the methods for rotation in all 3 axes, and for projection onto a 2D plane. Each of these methods return a new Point3D object, allow us to chain multiple transformations and avoid altering the original points we define.
class Point3D:
def __init__(self, x = 0, y = 0, z = 0):
self.x, self.y, self.z = x, y, z
def rotateX(self, angle):
""" Rotates this point around the X axis the given number of degrees. """
rad = angle * math.pi / 180
cosa = math.cos(rad)
sina = math.sin(rad)
y = self.y * cosa - self.z * sina
z = self.y * sina + self.z * cosa
return Point3D(self.x, y, z)
def rotateY(self, angle):
""" Rotates this point around the Y axis the given number of degrees. """
rad = angle * math.pi / 180
cosa = math.cos(rad)
sina = math.sin(rad)
z = self.z * cosa - self.x * sina
x = self.z * sina + self.x * cosa
return Point3D(x, self.y, z)
def rotateZ(self, angle):
""" Rotates this point around the Z axis the given number of degrees. """
rad = angle * math.pi / 180
cosa = math.cos(rad)
sina = math.sin(rad)
x = self.x * cosa - self.y * sina
y = self.x * sina + self.y * cosa
return Point3D(x, y, self.z)
def project(self, win_width, win_height, fov, viewer_distance):
""" Transforms this 3D point to 2D using a perspective projection. """
factor = fov / (viewer_distance + self.z)
x = self.x * factor + win_width / 2
y = -self.y * factor + win_height / 2
return Point3D(x, y, self.z)
3D Simulation
We can now create a scene by arranging Point3D objects in 3-dimensional space. To create a cube, rather than 8 discrete points, we will connect our vertices to their adjacent vertices after projecting them onto our 2D surface.
Vertices
The vertices for a cube are shown below. Our cube is centered around 0 in all 3 axes, and rotates around this centre.
self.vertices = [
Point3D(-1,1,-1),
Point3D(1,1,-1),
Point3D(1,-1,-1),
Point3D(-1,-1,-1),
Point3D(-1,1,1),
Point3D(1,1,1),
Point3D(1,-1,1),
Point3D(-1,-1,1)
]
Polygons or Lines
As we're drawing a wireframe cube, we actually have a couple of options — polygons or lines.
The cube has 6 faces, which means 6 polygons. To draw a single polygon requires 4 lines, making a total draw for the wireframe cube with polygons of 24 lines. We draw more lines than needed, because each polygon shares sides with 4 others.
In contrast drawing only the lines that are required, a wireframe of the cube can be drawn using only 12 lines — half as many.
For a filled cube, polygons would make sense, but here we're going to use the lines only, which we call edges. This is an array of indices into our vertices list.
self.edges = [
# Back
(0, 1),
(1, 2),
(2, 3),
(3, 0),
# Front
(5, 4),
(4, 7),
(7, 6),
(6, 5),
# Front-to-back
(0, 5),
(1, 4),
(2, 7),
(3, 6),
]
On each iteration we apply the rotational transformations to each point, then project it onto our 2D surface.
r = v.rotateX(angleX).rotateY(angleY).rotateZ(angleZ)
# Transform the point from 3D to 2D
p = r.project(*self.projection)
# Put the point in the list of transformed vertices
t.append(p)
Then we iterate our list of edges, and retrieve the relevant transformed vertices from our list t. A line is then drawn between the x, y coordinates of two points making up the edge.
for e in self.edges:
display.line(*to_int(t[e[0]].x, t[e[0]].y, t[e[1]].x, t[e[1]].y, 1))
The to_int is just a simple helper function to convert lists of float into lists of int to make updating the OLED display simpler (you can't draw half a pixel).
def to_int(*args):
return [int(v) for v in args]
The complete simulation code is given below.
class Simulation:
def __init__(self, width=128, height=64, fov=64, distance=4, rotateX=5, rotateY=5, rotateZ=5):
self.vertices = [
Point3D(-1, 1,-1),
Point3D( 1, 1,-1),
Point3D( 1,-1,-1),
Point3D(-1,-1,-1),
Point3D(-1, 1, 1),
Point3D( 1, 1, 1),
Point3D( 1,-1, 1),
Point3D(-1,-1, 1)
]
# Define the edges, the numbers are indices to the vertices above.
self.edges = [
# Back
(0, 1), (1, 2), (2, 3), (3, 0),
# Front
(5, 4), (4, 7), (7, 6), (6, 5),
# Front-to-back
(0, 4), (1, 5), (2, 6), (3, 7),
]
# Dimensions
self.projection = [width, height, fov, distance]
# Rotational speeds
self.rotateX = rotateX
self.rotateY = rotateY
self.rotateZ = rotateZ
def run(self):
# Starting angle (unrotated in any dimension).
angleX, angleY, angleZ = 0, 0, 0
while 1:
t = []
for v in self.vertices:
# Rotate the point around X axis, then around Y axis, and finally around Z axis.
r = v.rotateX(angleX).rotateY(angleY).rotateZ(angleZ)
# Transform the point from 3D to 2D
p = r.project(*self.projection)
# Put the point in the list of transformed vertices.
t.append(p)
display.fill(0)
for e in self.edges:
display.line(*to_int(t[e[0]].x, t[e[0]].y, t[e[1]].x, t[e[1]].y, 1))
display.show()
# Continue the rotation.
angleX += self.rotateX
angleY += self.rotateY
angleZ += self.rotateZ
Running a simulation
To display our cube we need to create a Simulation object, and then call .run() to start it running.
s = Simulation()
s.run()
You can pass in different values for rotateX, rotateY, rotateZ to alter the speed of rotation. Set a negative value to rotate in reverse.
s = Simulation()
s.run()
The fov and distance parameters are set at sensible values for the 128x64 OLED by default (based on testing). So you don't need to change these, but you can.
s = Simulation(fov=32, distance=8)
s.run()
The width and height are defined by the display, so you won't want to change these unless you're using a different display output.