The ASCII Side of the Moon - aleyan.com

The ASCII Side of the Moon

What you are seeing

Look up at the sky, then to your screen, now back up to the sky, now down again. Chances are when looking up you did not see the Moon, but there was a Moon on your screen.

Presented for your consideration is a rendering of the Moon in glorious 7-bit ASCII. Drag the slider with the Moon icon, and you will notice the Moon changes over time.

As the Moon orbits around the Earth in a monthly cycle, the visible portion of the Moon change as part of the Moon hides in its own shadow. This is called the Lunar phase. The illuminated percentage and side are accurately calculated and displayed.

The orbit itself is not circular and the Lunar distance to the Earth is not constant. Variation in distance causes the apparent size of the Moon to change, up to 12% smaller at apogee than perigee. This is also accurately calculated and displayed.

Additionally, the Moon wobbles slightly up and down and side to side in its orbit. This is called Lunar libration. The libration angle is also accurately calculated and is visible in the ASCII art.

Depending on observer’s position on the Earth and time of day, the Moon’s apparent angular orientation changes. Click or drag on the world map to set your location and see the Moon as it appears from your position, including whether it is above or below the horizon.

Lastly, the Moon is often viewed with up towards Polaris, the Celestial Reference Frame, rather than the Zenith. You can get this view by clicking on the location bead on the world map and toggling between the observer, celestial up, and celestial down reference frames. The celestial reference frames are particularly useful for seeing the lunar wobble and distance changes over time.

Breathe (In the Terminal)

Now that we got that astronomy out of the way, let’s get the ASCII in to your terminal. You have 2 choices. First, you can fetch the ASCII from the webserver at the present url. A curl command is helpfully provided in the virtual terminal above to fetch the ASCII for a given date, but it will fetch today’s date if no date is provided.

# The Moon as viewed from your location and present time
curl -s "https://aleyan.com/projects/ascii-side-of-the-moon"

# The Moon at a particular UTC datetime
curl -s "https://aleyan.com/projects/ascii-side-of-the-moon?date=2025-09-01T21:30Z"

# With observer location (latitude/longitude in degrees)
curl -s "https://aleyan.com/projects/ascii-side-of-the-moon?date=2025-09-01T21:30Z&lat=37.77&lon=-122.42"

# The Moon at present time as viewed with Celestial North refrence frame
curl -s "https://aleyan.com/projects/ascii-side-of-the-moon?celestial=up"

Alternatively, you can get the ascii-side-of-the-moon package from npmjs.com and run it locally. For your convenience, npx will install and run the package for you. The command also takes an optional date argument.

npx ascii-side-of-the-moon 2025-09-01T21:30Z

Implementation details

The ascii-side-of-the-moon npm package is MIT licensed and available on GitHub. The Lunar calculations were made via the excellent astronomy-engine package by CosineKitty. Images of the Moon were rendered in Blender from gerhald3d’s Moon 2K 3D model for a variety of distances and libration. Chafa was used to create the ASCII representation of the resulting .pngs.

Money

This website is statically hosted on Cloudflare Pages free tier. The serverless function to serve https for curl is also on the Cloudflare free tier. To make it work, the javascript bundle had to be under 3 MB in size and respond under 10 milliseconds CPU time. The ascii-side-of-the-moon package was designed with those constraints in mind.