- Overview
- Features
- Requirements
- Installation
- Usage
- Command-Line Arguments
- Examples
- Further Reading
- License
- Contact
ChronoTVA (The Chronomancer's Tesseract Visualization Aid) is a Python 3.9+ command-line tool designed for generating images from three-dimensional coordinates of unfoldings of a tesseract.
This has been tested with Python 3.9, 3.10, 3.11, and 3.12. The only dependency is matplotlib.
For more information on the unfolding process, please read the Further Reading section.
- Color Customization: Customize block and edge colors using RGBA format or named colors.
- View Angle Adjustment: Set elevation and azimuth angles for 3D plot perspective.
- Output Format Options: Generate images in PNG, SVG, or PDF format.
- Image Dimensions & DPI: Control the dimensions and resolution (DPI) of the output image.
- Transparency and Shading: Option to enable transparency and shading in the plot.
- Axis Display: Toggle the display of axes in the plot.
- Automatic Output Directory Management: Saves plots to a specified directory or creates a default one based on the current date and time.
- Selective Unfolding ID Plotting: Plot specific unfoldings by providing their numeric identifiers.
- Whitespace Removal: Automatically remove whitespace around the image.
- Flexible Dimension Specifications: Set image dimensions either in pixels or inches.
- Robust Error Handling: Includes validations and error handling for input arguments and plot configurations.
- Command-Line Interface: Offers a user-friendly command-line interface for configuring and running the plotting process.
- Dynamic Plotting Capabilities: Capable of plotting varying data sets based on provided unfolding IDs.
- Python 3.9+
- Matplotlib
- Ensure Python 3.9 or higher is installed on your system.
- Install via pip:
pip install chronotva
Run the script from the command line. Default values will be used and an output directory with the current date and time will be created.
chronotva
You can also specify the desired parameters. For example:
chronotva --block-color "255,0,0,1" --edge-color "0,255,0,1" --output-format png
-b, --block-color
: Block color in RGBA format or color name. Default: '230,230,230,1'-e, --edge-color
: Block edge color in RGBA format or color name. Default: '25,25,25,1'-v, --elevation
: Elevation angle for the plot in degrees. Default: 30-a, --azimuth
: Azimuth angle for the plot in degrees. Default: 22.5-f, --output-format
: Output file format (png, svg, pdf). Default: 'svg'-d, --output-dir
: Output directory for the plots.-p, --dpi
: DPI for the output image. Default: 300-t, --transparent
: Enable transparency in the output image. Default: True-s, --shade
: Enable shading in the 3D plot. Default: False-x, --show-axes
: Show axes in the plot. Default: False-w, --whitespace-removal
: Remove whitespace around the image. Default: True-u, --unfolding-ids
: Comma-separated numeric identifiers of unfoldings to plot.
For image size, you can provide either pixel height and width, or inch height and width. Pixels will be converted to inches based off of the DPI value provided, 300 by default.
--pixel-height
: Height of the output image in pixels.--pixel-width
: Width of the output image in pixels.
Or provide:
--inch-height
: Height of the output image in inches. Default: 6.4--inch-width
: Width of the output image in inches. Default: 4.8
If you want the image to be the exact size in pixels and inches with no trimming, make sure to pass in --whitespace-removal false.
Run ChronoTVA with default parameters. This will generate an SVG image with default colors, dimensions, and angles, saving it in a directory named with the current date and time.
chronotva
Generate a PNG image with red blocks and green edges.
chronotva --block-color "255,0,0,1" --edge-color "0,255,0,1" --output-format png
Set a specific elevation and azimuth angle for a different perspective.
chronotva --elevation 45 --azimuth 45
Create a high-resolution image with increased DPI and transparency enabled.
chronotva --dpi 600 --transparent true
Generate an image with specific pixel dimensions, ensuring no whitespace removal for exact sizing.
chronotva --pixel-height 1080 --pixel-width 1920 --whitespace-removal false
Create an image with custom dimensions in inches, using SVG format.
chronotva --inch-height 8 --inch-width 10 --output-format svg
Plot specific unfoldings of the tesseract and display axes.
chronotva --unfolding-ids 1,3,5 --show-axes true
Save the generated images in a specified directory.
chronotva --output-dir "/path/to/custom/directory"
A combination of various options, including color customization, view angle adjustment, and selective unfolding plotting.
chronotva --block-color "blue" --edge-color "yellow" --elevation 60 --azimuth 30 --unfolding-ids 2,4,6
Fully customize the image with block and edge colors, DPI, transparency, shading, axis display, whitespace removal, and image size in pixels.
chronotva --block-color "128,0,128,0.5" --edge-color "255,165,0,1" --dpi 450 --transparent true --shade true --show-axes true --whitespace-removal false --pixel-height 1200 --pixel-width 1600
The unfoldings were created by Moritz Firsching and are from exploring how a tesseract, a four-dimensional hypercube, can be projected or unfolded into three-dimensional space. This process systematically analyzes the geometric relationships and connectivity of all cubes composing the tesseract. The process reveals 261 unique configurations, each representing a distinct unfolding of the tesseract, which can be visualized or rendered in three-dimensional space.
For a much more thorough explanation of the complete unfolding process, check out Unfolding the Tesseract by Peter D. Turney from the Journal of Recreational Math.
This software is released under the MIT License.
For support or contributions, please contact Jacob 'the-chronomancer' Coleman.