4elements, web design and consultancy

  1. Render an SVG Globe

    Final product image
    What You'll Be Creating

    In this tutorial, I will be showing you how to take an SVG map and project it onto a globe, as a vector. To carry out the mathematical transforms needed to project the map onto a sphere, we must use Python scripting to read the map data and translate it into an image of a globe. This tutorial assumes that you are running Python 3.4, the latest available Python.

    Inkscape has some sort of Python API which can be used to do a variety of stuff. However, since we are only interested in transforming shapes, it’s easier to just write a standalone program that reads and prints SVG files on its own.

    1. Format the Map

    The type of map that we want is called an equirectangular map. In an equirectangular map, the longitude and latitude of a place corresponds to its x and y position on the map. One equirectangular world map can be found on Wikimedia Commons (here is a version with U.S. states).

    SVG coordinates can be defined in a variety of ways. For example, they can be relative to the previously defined point, or defined absolutely from the origin. To make our lives easier, we want to convert the coordinates in the map to the absolute form. Inkscape can do this. Go to Inkscape preferences (under the Edit menu) and under Input/Output > SVG Output, set Path string format to Absolute.

    Inkscape preferences

    Inkscape won’t automatically convert the coordinates; you have to perform some sort of transform on the paths to get that to happen. The easiest way to do that is just to select everything and move it up and back down with one press each of the up and down arrows. Then re-save the file.

    2. Start Your Python Script

    Create a new Python file. Import the following modules:

    You will need to install NumPy, a library that lets you do certain vector operations like dot product and cross product.

    3. The Math of Perspective Projection

    Projecting a point in three-dimensional space into a 2D image involves finding a vector from the camera to the point, and then splitting that vector into three perpendicular vectors. 

    The two partial vectors perpendicular to the camera vector (the direction the camera is facing) become the x and y coordinates of an orthogonally projected image. The partial vector parallel to the camera vector becomes something called the z distance of the point. To convert an orthogonal image into a perspective image, divide each x and y coordinate by the z distance.

    At this point, it makes sense to define certain camera parameters. First, we need to know where the camera is located in 3D space. Store its x, y, and z coordinates in a dictionary.

    The globe will be located at the origin, so it makes sense to orient the camera facing it. That means the camera direction vector will be the opposite of the camera position.

    It’s not just enough to determine which direction the camera is facing—you also need to nail down a rotation for the camera. Do that by defining a vector perpendicular to the cameraForward vector.

    1. Define Useful Vector Functions

    It will be very helpful to have certain vector functions defined in our program. Define a vector magnitude function:

    We need to be able to project one vector onto another. Because this operation involves a dot product, it’s much easier to use the NumPy library. NumPy, however, takes vectors in list form, without the explicit ‘x’, ‘y’, ‘z’ identifiers, so we need a function to convert our vectors into NumPy vectors.

    It’s nice to have a function that will give us a unit vector in the direction of a given vector:

    Finally, we need to be able to take two points and find a vector between them:

    2. Define Camera Axes

    Now we just need to finish defining the camera axes. We already have two of these axes—cameraForward and cameraPerpendicular, corresponding to the z distance and x coordinate of the camera’s image. 

    Now we just need the third axis, defined by a vector representing the y coordinate of the camera’s image. We can find this third axis by taking the cross product of those two vectors, using NumPy—np.cross(vectorToList(cameraForward), vectorToList(cameraPerpendicular)).

    The first element in the result corresponds to the x component; the second to the y component, and the third to the z component, so the vector produced is given by:

    3. Project to Orthogonal

    To find the orthogonal x, y, and z distance, we first find the vector linking the camera and the point in question, and then project it onto each of the three camera axes defined previously:

    A point being projected onto the three camera axes

    A point (dark gray) being projected onto the three camera axes (gray). x is red, y is green, and z is blue.

    4. Project to Perspective

    Perspective projection simply takes the x and y of the orthogonal projection, and divides each coordinate by the z distance. This makes it so that stuff that’s farther away looks smaller than stuff that’s closer to the camera. 

    Because dividing by z yields very small coordinates, we multiply each coordinate by a value corresponding to the focal length of the camera.

    5. Convert Spherical Coordinates to Rectangular Coordinates

    The Earth is a sphere. Thus our coordinates—latitude and longitude—are spherical coordinates. So we need to write a function that converts spherical coordinates to rectangular coordinates (as well as define a radius of the Earth and provide the π constant):

    We can achieve better performance by storing some calculations used more than once:

    We can write some composite functions that will combine all the previous steps into one function—going straight from spherical or rectangular coordinates to perspective images:

    4. Rendering to SVG

    Our script has to be able to write to an SVG file. So it should start with:

    And end with:

    Producing an empty but valid SVG file. Within that file the script has to be able to create SVG objects, so we will define two functions that will allow it to draw SVG points and polygons:

    We can test this out by rendering a spherical grid of points:

    This script, when saved and run, should produce something like this:

    A dot sphere rendered with perspective

    5. Transform the SVG Map Data

    To read an SVG file, a script needs to be able to read an XML file, since SVG is a type of XML. That’s why we imported xml.etree.ElementTree. This module allows you to load the XML/SVG into a script as a nested list:

    You can navigate to an object in the SVG through the list indexes (usually you have to take a look at the source code of the map file to understand its structure). In our case, each country is located at root[4][0][x][n], where x is the number of the country, starting with 1, and n represents the various subpaths that outline the country. The actual contours of the country are stored in the d attribute, accessible through root[4][0][x][n].attrib['d'].

    1. Construct Loops

    We can’t just iterate through this map because it contains a “dummy” element at the beginning that must be skipped. So we need to count the number of “country” objects and subtract one to get rid of the dummy. Then we loop through the remaining objects.

    Some country objects include multiple paths, which is why we then iterate through each path in each country:

    Within each path, there are disjoint contours separated by the characters ‘Z M’ in the d string, so we split the d string along that delimiter and iterate through those.

    We then split each contour by the delimiters ‘Z’, ‘L’, or ‘M’ to get the coordinate of each point in the path:

    Then we remove all non-numeric characters from the coordinates and split them in half along the commas, giving the latitudes and longitudes. If both exist, we store them in a sphereCoordinates dictionary (in the map, latitude coordinates go from 0 to 180°, but we want them to go from –90° to 90°—north and south—so we subtract 90°).

    Then if we test it out by plotting some points (svgCircle(spherePlot(sphereCoordinates, radius), 1, '#333')), we get something like this:

    A dot rendering of national and state borders

    2. Solve for Occlusion

    This does not distinguish between points on the near side of the globe and points on the far side of the globe. If we want to just print dots on the visible side of the planet, we need to be able to figure out which side of the planet a given point is on. 

    We can do this by calculating the two points on the sphere where a ray from the camera to the point would intersect with the sphere. This function implements the formula for solving the distances to those two points—dNear and dFar:

    If the actual distance to the point, d1, is less than or equal to both of these distances, then the point is on the near side of the sphere. Because of rounding errors, a little wiggle room is built into this operation:

    Using this function as a condition should restrict the rendering to near-side points:

    Dot globe only displaying points on the near side of the planet

    6. Render Solid Countries

    Of course, the dots are not true closed, filled shapes—they only give the illusion of closed shapes. Drawing actual filled countries requires a bit more sophistication. First of all, we need to print the entirety of all visible countries. 

    We can do that by creating a switch that gets activated any time a country contains a visible point, meanwhile temporarily storing the coordinates of that country. If the switch is activated, the country gets drawn, using the stored coordinates. We will also draw polygons instead of points.

    Solid rendering of the entirety of all visible countries

    It is difficult to tell, but the countries on the edge of the globe fold in on themselves, which we don’t want (take a look at Brazil).

    1. Trace the Disk of the Earth

    To make the countries render properly at the edges of the globe, we first have to trace the disk of the globe with a polygon (the disk you see from the dots is an optical illusion). The disk is outlined by the visible edge of the globe—a circle. The following operations calculate the radius and center of this circle, as well as the distance of the plane containing the circle from the camera, and the center of the globe.

    2D analogy of finding the edge of the visible disk

    The earth and camera (dark gray point) viewed from above. The pink line represents the visible edge of the earth. Only the shaded sector is visible to the camera.

    Then to graph a circle in that plane, we construct two axes parallel to that plane:

    Then we just graph on those axes by increments of 2 degrees to plot a circle in that plane with that radius and center (see this explanation for the math):

    Then we just encapsulate all of that with polygon drawing code:

    We also create a copy of that object to use later as a clipping mask for all of our countries:

    That should give you this:

    Rendering of the visible disk

    2. Clipping to the Disk

    Using the newly-calculated disk, we can modify our else statement in the country plotting code (for when coordinates are on the hidden side of the globe) to plot those points somewhere outside the disk:

    This uses a tangent curve to lift the hidden points above the surface of the Earth, giving the appearance that they are spread out around it:

    Lifted portions of countries on the far side of the globe

    This is not entirely mathematically sound (it breaks down if the camera is not roughly pointed at the center of the planet), but it’s simple and works most of the time. Then by simply adding clip-path="url(#clipglobe)" to the polygon drawing code, we can neatly clip the countries to the edge of the globe:

    Final product with all countries clipped to the visible disk

    I hope you enjoyed this tutorial! Have fun with your vector globes!

    Another globe rendering



    Leave a comment › Posted in: Daily


Got anything to add?

(Basic HTML is fine)