epicycle(6)

📦
version 6.15 · 2 versions
, in alpine 3.24, arch rolling, nixpkgs unstable

epicycle(6) 💫 — straight from the XScreenSaver manual, bestie ✨

💖 NAME 💖

epicycle — draws a point moving around a circle which moves around a cicle which… (yes, “cicle” is the original spelling and honestly it’s iconic 🌀)

🌀 SYNOPSIS 🌀

epicycle [--display host:display.screen] [--root] [--window-id number][--window] [--mono] [--install] [--noinstall] [--visual viz] [--colors N] [--foreground name] [--color-shift N] [--delay microseconds] [--holdtime seconds] [--linewidth N] [--min_circles N] [--max_circles N] [--min_speed number] [--max_speed number] [--harmonics N] [--timestep number] [--divisor_poisson probability] [--size_factor_min number] [--size_factor_max number] [--fps]

🌸 DESCRIPTION 🌸

Okay so epicycle draws the path traced by a point on the edge of a circle. That circle rotates around a point on the rim of another circle, and then that keeps happening several times. The random curves it produces can be simple or complex, convex or concave, but they are always closed curves — they never go on indefinitely. Periodt. 💅

You can configure both the way the curves are drawn and the way the random sequence of circles is generated, either with command-line options or X resources. It’s giving customizable circle chaos ✨

✨ OPTIONS ✨

  • --display host:display.screen — tells it which X display to use. For the whole explanation of this one, check the section DISPLAY NAMES in X(1). 🖥️
  • --root — draw on the root window.
  • --window-id number — draw on the specified window.
  • --window — draw on a newly-created window. This is the default, bestie.
  • --mono — if you’re on a color display, pretend it’s monochrome. If you’re already on a mono display, there’s no choice. 💀
  • --install — install a private colormap for the window.
  • --noinstall — don’t install a private colormap for the window.
  • --visual viz — pick which visual to use. Legal values are the name of a visual class, or the id number (decimal or hex) of a specific visual. Possible choices include:

default, best, mono, monochrome, gray, grey, color, staticgray, staticcolor, truecolor, grayscale, greyscale, pseudocolor, directcolor, number

If you pass a decimal or hexadecimal number, XGetVisualInfo(3X) gets consulted to obtain the required visual. 🎨

  • --colors N — how many colors should be used (if possible). The colors are chosen randomly. 🍓
  • --foreground name — with --mono, this option selects the foreground colour.
  • --color-shift N — this one appears in the synopsis, but the OPTIONS section on this page does not describe it. A little mystery, a little main character energy 🕵️‍♀️💜
  • --delay microseconds — sets the delay between drawing successive line segments of the path. If you do not specify -sync, some X servers may batch up several drawing operations together and produce a less smooth effect. This is more likely in monochrome mode, either on monochrome servers or when --mono is specified. 😭
  • --holdtime seconds — when the figure is complete, epicycle pauses for this many seconds.
  • --linewidth N — width in pixels of the body’s track. Values greater than one may cause slower drawing. The fastest value is usually zero, which means one pixel.
  • --min_circles N — smallest number of epicycles in the figure.
  • --max_circles N — largest number of epicycles in the figure.
  • --min_speed number — smallest possible value for the base speed of revolution of the epicycles. The actual speeds of the epicycles vary from this down to min_speed / harmonics. 🌀
  • --max_speed number — smallest possible value for the base speed of revolution of the epicycles. (Yes, the page says smallest here too — I’m not making the rules, I’m just reporting them 💀)
  • --harmonics N — number of possible harmonics. The larger this value is, the greater the possible variety of possible speeds of epicycle.
  • --timestep number — decreasing this value reduces the distance the body moves for each line segment, possibly producing a smoother figure. Increasing it may produce faster results. ⚡
  • --divisor_poisson probability — each epicycle rotates at a rate that is a factor of the base speed. The speed of each epicycle is the base speed divided by some integer between 1 and the value of the --harmonics option. That integer is decided by starting at 1 and tossing a biased coin: for each consecutive head, the value gets incremented by one. The integer will not be incremented above the value of the --harmonics option. The argument of this option decides the bias of the coin — it is the probability that the coin will produce a head at any given toss. 🪙
  • --size_factor_min number — epicycles are always at least this factor smaller than their parents.
  • --size_factor_max number — epicycles are never more than this factor smaller than their parents.
  • --fps — display the current frame rate and CPU load. Then the page says: --timestep option multiplied by the timestepCoarseFactor resource. The default value of 1 will almost always work fast enough and so this resource is not available as a command-line option. That is exactly the lore, bestie — I am not editing it 💅

💅 USER INTERFACE 💅

The program runs mostly without user interaction. When it’s running on the root window, no input is accepted. When it’s running in its own window, the program exits if mouse button 3 is pressed. If any other mouse button is pressed, the current figure is abandoned and another one is started. 🖱️✨

🦋 HISTORY 🦋

The geometry of epicycles was perfected by Hipparchus of Rhodes at some time around 125 B.C., which was 185 years after the birth of Aristarchus of Samos, the inventor of the heliocentric universe model. Hipparchus applied epicycles to the Sun and the Moon. Ptolemy of Alexandria went on to apply them to what was then the known universe, at around 150 A.D. Copernicus went on to apply them to the heliocentric model at the beginning of the sixteenth century. Johannes Kepler discovered that the planets actually move in elliptical orbits in about 1602. The inverse-square law of gravity was suggested by Boulliau in 1645. Isaac Newton’s Principia Mathematica was published in 1687, and proved that Kepler’s laws derived from Newtonian gravitation. History ate, no cap 👑📜

💀 BUGS 💀

The colour selection is re-done for every figure. This may generate too much network traffic for this program to work well over slow or long links. So like… gorgeous, but maybe not over a tragic connection 😭🌐

🌈 ENVIRONMENT 🌈

  • DISPLAY — used to get the default host and display number.
  • XENVIRONMENT — used to get the name of a resource file that overrides the global resources stored in the RESOURCE_MANAGER property.
  • XSCREENSAVER_WINDOW — the window ID to use with --root.

🎀 SEE ALSO 🎀

X(1), xscreensaver(1) 🫶

Copyright © 1998, James Youngman. 💖

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. No representations are made about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.

⭐ AUTHOR ⭐

James Youngman <jay@gnu.org>, April 1998. 🌟

X Version 11, version 6.15 (30-Mar-2026) of epicycle(6) — byeee bestie, go trace some circles 💖✨

📦 where this page comes from