uranimator

uranimator

uranimator is a CLI tool that works with your existing uraniborg install to create animations. See how the sky evolves over a million years or what traveling to a star 100 light years away looks like.

Table Of Contents

• Background
• Application Contents
• Quick Start
• Next Steps
• Available CLI Flags
• Output Format
• More Examples

Background

After developing uraniborg, it became clear that it had the capability to quickly generate enough images to be useful for simple animations. After working with a couple of (rather slow) Python prototypes for a while, uranimator (in Go) was the result.

Version 1.22 or higher of Go is required.

You will also need:

• uraniborg (https://codeberg.org/astronexus/uraniborg), actively running
• some form of video processing software that can take a set of PNG or JPEG images and create an animation from them. The examples in this README and included as sample scripts in uranimator use ffmpeg (https://ffmpeg.org/).
• some familiarity with editing uraniborg configuration files and what the various options mean (see uraniborg configuration options for full details)

Back to Table of Contents

Application Contents

• Top directory: Source code for uranimator itself, this README file, and project/build configuration files.
• bash_video: Contains sample scripts for a uranimator + ffmpeg workflow to create videos.
• config: Location for project configuration files.
• data: Location for the uraniborg-format data file used to do star name and ID lookups.
• img: Location where image files (created by uraniborg) are saved, and used as frames in a video file. Each set of images will be created in a subdirectory under img.
• videos: Location where the scripts in bash_video save video files, and recommended for your own use in other workflows.

Back to Table of Contents

Quick Start

This Quick Start assumes a couple of things:

• a Linux or macOS CLI/terminal window (for Windows / PowerShell, the syntax for these commands will be somewhat different; adjust accordingly)
• the ffmpeg video creation tool (https://ffmpeg.org/). If you don't have ffmpeg, you can still create sets of images that can be assembled into an animation by other means, after the first few steps in this Quick Start. You'll need to change step 7 to the appropriate action in your workflow for converting a batch of image files in a directory into a video.

Quick Start Basic Install:

Do this to get a feel for how uranimator works.

1. Clone uranimator from the git repository.
2. By default, uranimator looks in its parent directory for a uraniborg install. So if the uranimator directory is not already at the same level as your uraniborg install, move the entire directory so it is (e.g. if your uraniborg install is in .../your_home/git/uraniborg, make sure the uranimator directory is moved to .../your_home/git/uranimator. )
3. Uncompress the sample data file in uranimator/data. uranimator's star name lookups can be used with any uraniborg data file, but this one is a small version containing mostly close and bright stars that will be a good starting point.
4. Start uraniborg from its install directory, if it's not already running.
   • cd ../uraniborg
   • ./uraniborg
5. From the uranimator main directory, compile the executable:
   • cd ../uranimator
   • go build
6. From the same location, run uranimator with some flags to create a sample set of frames for an animation:
   • ./uranimator -f Sun -t Sirius -l Procyon
   • This invokes uraniborg the default number of times (200 times, to create 200 frames), along a path from (-f) the Sun to (-t) Sirius, looking (-l) toward the star Procyon in each frame.
   • For this example, only location names were chosen in the command. uranimator associates all runs with a "project" (see "Organizing with Projects" below for more details). Since no distinct project name was chosen in the command, uranimator will use a default project name of default. It will then save the frames to the directory img/default.
7. Wait for uranimator to finish, then run the frames in img/default through ffmpeg:
   • ffmpeg -y -f image2 -framerate 25 -i img/default/frame%06d.png -c:v -pix_fmt yuv420p libx264 videos/quickstart.mp4
   • This creates an animation at 25 fps (total length: 8 seconds) from the uraniborg .png files and writes it to videos/quickstart.mp4.

Back to Table of Contents

Quick Start Custom Install

Do this if you want to install the executable file to a standard location (e.g. ~/go/bin).

1. Clone uranimator from the git repository.
2. From the uranimator main repository directory, compile the executable and install to the usual location for Go executables.
   • go build && go install
   • This should put uranimator in your path, so you can run it from any directory.
3. Uncompress the sample data file in uranimator/data.
4. (optional) Move or copy the bash_examples, config, data, img, and video folders to a custom location.
   • Regardless of whether you move them or not, make a note of the directory they are currently in.
5. Start uraniborg if it's not already running.
   • If your uraniborg installation puts the executable outside the cloned uraniborg repo, make a note of where your uraniborg config, data, etc. files are.
6. Run uranimator with some flags to create a sample set of frames for an animation:
   • Replace ./uranimator in the Quick Start steps with uranimator -b {path to uranimator files from step 4} -u {path to uraniborg files from step 6}
   • e.g. uranimator -b ~/Documents/Uranimator -u ~/Documents/Uraniborg -f Sun -t Sirius -l Procyon
7. Wait for uranimator to finish, then run the frames in img/default through ffmpeg:
   • cd {path to uranimator files from step 4}
   • ffmpeg -y -f image2 -framerate 25 -i img/default/frame%06d.png -c:v -pix_fmt yuv420p libx264 videos/quickstart.mp4
   • This creates an animation at 25 fps (total length: 8 seconds) from the uraniborg .png files and writes it to videos/quickstart.mp4.

Next Steps

Location Examples

The CLI pattern in either Quick Start's step 6. above can be used for any star names or IDs that exist in the data file from step 3 (about 50k distinct stars). In particular, almost all stars with an official IAU-sanctioned name, as well as most stars of or slightly below naked-eye brightness, are represented in that sample data file.

Some more examples:

• ./uranimator -f Sun -t "Proxima Centauri": Travel from the Sun to its closest star (Proxima Centauri), looking at Proxima Centauri the entire time.
• ./uranimator -f Sun -t Rigel: Travel from the Sun to Rigel, which is much farther away, so the visible sky changes much more dramatically.
• ./uranimator -f Sirius -t Altair -l Sun: Travel from Sirius to Altair, keeping the Sun centered in the animation at all times.
• ./uranimator -f Sun -t "61 Cygni" -y 5000: The -y flag sets a time in years before (negative) or after (positive) the present, for the final frame of the animation. So this one shows how the rapidly moving star 61 Cygni moves across the sky over the next 5000 years.
• ./uranimator -f Sun -t "HR 1008" -y 5000: Common star IDs like Harvard Revised (HR, used in the Yale Bright Star catalog) and HIPPARCOS (as "HIP") are good too. HR 1008 is also known as 82 G. Eridani, a nearby star in Eridanus that is also fairly rapidly moving.
• ./uranimator -f Sun -t "Towards Vernal Equinox, 5.0, 0.0, 0.0": The custom uraniborg position format works here as well, any place you would otherwise use a star name or ID. Specify the position as a CSV list of a label and the x, y, and z coordinates in parsecs.

In short, any name or ID that is valid in a uraniborg configuration works the same way in uranimator.

Changing Video Configurations

Each collection of frames uses a uraniborg-format configuration file to set all of the non-changing parameters (basically, anything that isn't a position or a time). These include things like the size of each frame, the aspect ratio of each frame, the label options for various items (like star names or constellation names), and so on. These configurations live in the config subdirectory and are chosen for a given video with the -c (for "configuration") flag. By default, if no other configuration is specified with the -c flag, the included default configuration config/default.yaml will be used.

The repository for uranimator contains several sample configurations in addition to the default that you can try out. See the uraniborg documentation for configurations for more details of the options you can set.

Organizing with Projects

You can organize distinct animations by giving each one a "project" using the -p flag. Specifying a new project will put the new frames in the img directory under the subdirectory img/[project name]. This will help keep different video sources separate.

Projects can have project-specific configurations, and by default, if you create a project, uranimator will look for a configuration with the same name (e.g., if you set -p = "rigel", uranimator will attempt to load the configuration in config/rigel.yaml if it exists). Each configuration file in config follows exactly the same format as a uraniborg configuration file. The only difference is that configuration items that affect chart position (such as to or from) or chart time (such as time) are ignored, since uranimator supplies its own values for them in each frame.

When you create a custom configuration file for a project, you don't need to set it explicitly with the -c flag so long as the project name and configuration file name are the same. If there is no matching configuration file, uranimator will load the default configuration. If you want to use a different configuration, you can override this behavior and set a specific configuration file with the -c flag.

Changing uranimator Lookup Data

The included data file (data/athyg_32_index.gz) is suitable for getting started and for essentially all bright (naked-eye-visible) and nearby (within about 100 light years) stars. If you want to be able to look up names or IDs of a wider range of stars, any valid uraniborg data file is usable, up to and including the full 2.55-million star catalog. Copy the relevant CSV file to the data directory and rename it athyg_32_index.csv.

Be aware that larger data files take longer to load when uranimator starts up.

Back to Table of Contents

Available CLI Flags

Each flag has a short (one hyphen + a single letter) and a long (two hyphens + a mnemonic word or phrase) option.

The only flag that are required is at least one location, either -f, --from or t, --to. In general, you will also want to create a custom project name and set the -p, --project flag as well, but this is optional.

File / Data Locations

These are needed whenever either uraniborg or uranimator is run outside of their default locations (e.g., if either is installed to your system with go install).

• -b, --basedir: the full path to the base directory of the uranimator support and configuration files.
• -u, --uraniborgdir: the full path to the location of uraniborg's configuration and data files.

You'll need to set the -u flag anytime you install uraniborg outside its repository directory. In this case, you're starting uraniborg with its own -b flag, and you should reuse that flag's value as uranimator's -u flag.

Similarly, you'll need to set the -b flag anytime you install uranimator outside its repository directory.

It's often a good idea to alias these to a convenient command, e.g.

export URANIBORG_FILES=~/Documents/Uraniborg
export URANIMATOR_FILES=~Documents/Uranimator
alias ua=uranimator -u $URANIBORG_FILES -b $URANIMATOR_FILES

Then you can run

ua

with just the usual flags for location and chart parameters.

Locations

• -f, --from: (string, required if -t is not set, default="Sun") The name, catalog ID, or position of the location the animation starts "from". That is, the point in space that defines the viewpoint of the very first frame. If omitted, defaults to "Sun", so the animation will start with the sky as seen from the Sun.

• -t, --to: (string, required if -f is not set, default="Sun") The name, catalog ID, or position of the location the animation "ends at". That is, the point in space that the defines the viewpoint of the final frame. E.g., for views of the sky while on a route from the Sun to Sirius, this would be the name "Sirius" or any other catalog ID for Sirius recognized by uraniborg.

  • The default value for both -f and -t is "Sun". To have a sensible animation, you'll need to specify a non-default value for at least one of the two locations.
  • The -r flag, described below, makes the -t setting behave somewhat differently when it is active. See -r below for details.

• -l, --lookto: (string, optional, default=value of the -t flag) The name, catalog ID, or position of the location each frame has in the center of the frame. This lets you have a viewpoint that is off to the side of the path your animation takes. Omitting this makes uranimator use the value of the -t flag for the chart center, so your chosen "ending" object or position will be centered in all frames.

  • All three "location" flags (-f, -t, -l) can accept a uraniborg-format absolute position instead of a star name or ID. This is a CSV string containing a text label followed by the x, y, and z coordinates of the point in space to use. More details about this option are in the uraniborg configuation documentation.

Animation configuration

• -p, --project: (string, optional, default="default") The name of an animation project. This is the name used for the directory containing images generated by uraniborg. If the -p flag is not set, the project name will be default, and so images will be placed in img/default and the configuration (see -c below) will be config/default.yaml.

• -c, --config: (string, optional, default=value of the -p flag) The name of a uraniborg-format configuration file. This is used to change "static" uraniborg parameters -- ones that don't change from frame to frame, such as the size of each image, the aspect ratio of each image, and the font/style scheme desired. If the -c flag is not set, the name of the configuration file will be the name of the project specified with the -p flag. If the specified configuration file is unavailable, the default configuration will be used.

• -n, --number: (integer, optional, default=200) The number of frames to create.

• -d, --delay: (integer, optional, default=250) The delay, in milliseconds, between requests to uraniborg for an image. This value needs to be slightly larger than the longest expected image generation time for your current configuration of uraniborg. The default of 250 ms is a somewhat conservative (most runs should be faster) value for uraniborg on mid-range hardware in the early 2020s, using the default data source (the one included in the uraniborg repository). Larger uraniborg catalogs (such as the full catalog from the AT-HYG repo) will likely need a longer -d value.

Additional options

• -y, --years: (floating point/decimal, optional, default=0.0) The total time elapsed between the first and last frames, in years. If not set (or set to 0.0), there is no time change between frames.

• -w, --warp: (floating point/decimal, optional, default=0.0) When -w is not set (or set to exactly zero), the position and/or time increment between frames is constant. If -w is set to a non-zero value, it causes a "warp" effect, where changes in location or time are slow towards the beginning and end of the animation, but then ramp up and down quickly near the midpoint. Larger values of "warp" lead to a more sudden speed change during the animation.

• -r, --revolution (optional, default=off) If -r is present (no value needed, the flag by itself is enough), it toggles "revolution" or "orbit" mode. In this mode, the animation path changes from a linear path (going from the -f position to the -t position) to a circular path. The path starts at the -f position or object, follows a circular route around the -t position or object, and returns to the -f position at the end of the circular path. The -l ("look to") flag works the same as before -- if it's missing, the -t object or position will always be centered, and if it's present, whatever object is the "look to" object will always be centered.

Back to Table of Contents

Output Format

The standard output format for uraniborg and uranimator is either PNG or JPEG files. When uranimator runs, it finds (creating if needed) a suitable directory in the img directory, and then creates sequentially numbered files named framennnnnn.png,or framennnnnn.jpeg where nnnnnn is the number of the frame with leading zeros. This convention makes it straightforward to load the frames in order into whatever workflow you want. For example, ffmpeg will read all these files correctly in order using the source file pattern frame%06d.png or frame%06d.jpeg as the file input name.

Back to Table of Contents

More Examples

The bash_video directory contains several example shell scrips that can run uranimator and create an .mp4 file in one run. Read the ./bash_video/README.md file for this directory for more details.