StarForge
Generate beautiful, accurate astronomical star charts in Python.
StarForge is a high-fidelity astronomical visualization engine that transforms real celestial mechanics into beautiful, publication-ready vector star charts.
"It is not a toy sky plotter."
StarForge combines:
-
Physically accurate astronomy (Skyfield, real ephemerides, Hipparcos catalog)
-
Smart decluttering & perceptual filtering
-
A fluent, composable API
-
A professional SVG rendering pipeline
-
CLI + library parity
All while remaining deterministic, scriptable, and design-grade.
Features
- Simple API - One line to generate a beautiful star chart
- Fluent Interface - Chain methods for easy configuration
- Accurate Astronomy - Uses Skyfield for precise star positions
- Fuzzy Location Search - Type "New York" or "NYC" - it just works
- Multiple Date Formats - Supports "2024-12-25", "25/12/2024", etc.
- Customizable - Colors, sizes, labels, effects, and more
- High Quality SVG - Scalable vector output for any resolution
Usage
StarForge can be used both as a Python library and as a command-line tool. The API is designed to be fluent, composable, and easy to read, while still allowing deep control over astronomical accuracy and visual styling.
Installation
pip install py-starforge
Python 3.9+ recommended
Quick Start (Recommended)
Generate a star chart in a single line:
from Starforge import StarForge
StarForge("Paris").render("paris_sky.svg")
This generates an accurate SVG star chart of the sky visible from Paris at the current time.
Fluent API Usage
StarForge supports a fluent, chainable API for expressive configuration:
from Starforge import StarForge
(
StarForge("Tokyo")
.at_date("2024-06-15 22:00")
.with_fov(60)
.with_magnitude_limit(5.0)
.without_labels()
.with_circular_mask()
.render("tokyo_sky.svg")
)
Setting Location
Using a City Name
StarForge("New York").render("nyc_sky.svg")
City names are resolved using fuzzy matching and population weighting.
Using Coordinates
StarForge("28.61, 77.20").render("delhi_sky.svg")
Using Explicit Coordinates
StarForge("Delhi").at_coordinates(28.61, 77.20).render("delhi_sky.svg")
Setting Date & Time
Using a String (Multiple Formats Supported)
chart.at_date("2024-12-25")
chart.at_date("25/12/2024 22:30")
chart.at_date("2024-12-25 22:30")
Using a datetime Object
from datetime import datetime
import pytz
chart.at_datetime(datetime(2024, 12, 25, 22, 30, tzinfo=pytz.utc))
Current Time
chart.now()
Field of View (Zoom)
chart.with_fov(90) # Full hemisphere (default)
chart.with_fov(60) # Zoomed
chart.with_fov(30) # Deep zoom near zenith
Star Density Control
Limit faint background stars:
chart.with_magnitude_limit(4.5) # Bright stars only
chart.with_magnitude_limit(6.5) # Dense sky
Labels & Annotations
chart.with_labels(True)
chart.without_labels()
Chart Shape & Projection
Circular Mask
chart.with_circular_mask()
Sphere / Globe Effect
chart.with_sphere_effect(True, strength=0.6)
Styling & Colors
chart.with_colors(
background="#050505",
stars="#ffffff",
lines="#ffffff",
labels="#ffcc00",
)
Size & Resolution
chart.with_size(1000) # Square
chart.with_size(1200, 800) # Rectangular
SVG output is resolution-independent and print-ready.
Advanced Styling
Star Sizes
chart.with_star_sizes(
constellation=14.0,
background=7.0
)
Constellation Line Style
chart.with_line_style(
width=1.2,
opacity=0.8
)
Label Style
chart.with_label_style(
font_size="12px",
font_family="Arial",
opacity=0.9
)
Procedural Background Stars
chart.with_procedural_stars(enabled=True, count=300)
Useful for artistic or stylized charts.
Custom Star Icons (SVG)
chart.with_custom_icons(
constellation_star_file="icons/star_main.svg",
background_star_file="icons/star_bg.svg"
)
Rendering & Saving
chart.render("output.svg")
chart.save("output.svg") # Alias
If the .svg extension is omitted, it is added automatically.
Command-Line Interface (CLI)
StarForge includes a first-class CLI for automation and scripting.
Basic Usage
starforge "Paris" paris.svg
With Options
starforge "New York" nyc.svg \
--date "2024-12-25 22:00" \
--fov 60 \
--magnitude 5.0 \
--no-labels \
--circular
Quiet Mode
starforge "Tokyo" tokyo.svg --quiet
Log Levels
Control console output verbosity:
from starforge import StarForge, Log, LogLevel
Log.set_level(LogLevel.WARNING) # Only warnings and errors
Log.set_level(LogLevel.SILENT) # No output
StarForge("Paris").render("quiet.svg")
Legacy API (Still Supported)
from Starforge import create_starmap
create_starmap("Paris", "paris_sky.svg")
create_starmap("28.61, 77.20", "delhi_sky.svg")
Typical Workflow
(
StarForge("London")
.at_date("2024-10-01 21:00")
.with_fov(45)
.with_magnitude_limit(5.5)
.with_circular_mask()
.with_colors(background="#000000", stars="#ffffff")
.render("london_sky.svg")
)
StarForge is designed to scale from one-line scripts to production pipelines without changing how you think about the sky.
Configuration Options
| Method | Description |
|---|---|
.at_date(date) |
Set observation date/time |
.with_fov(degrees) |
Field of view (default: 90) |
.with_magnitude_limit(mag) |
Star brightness filter (default: 6.0) |
.with_labels() / .without_labels() |
Toggle constellation labels |
.with_circular_mask() |
Clip to circular shape |
.with_sphere_effect(enabled, strength) |
3D globe distortion |
.with_size(width, height) |
Chart dimensions in pixels |
.with_colors(...) |
Customize colors |
.with_star_sizes(...) |
Star icon sizes |
.with_line_style(...) |
Constellation line style |
Examples
See more examples in examples.py & their outputs in outputs
Run specific examples:
python examples.py basic
python examples.py dates
python examples.py colors
python examples.py all
License
MIT License - see LICENSE file.
Author
Developed by Aditya Gaur (@xdityagr)
Links
Metadata
Release files for py-starforge 1.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| py_starforge-1.0.3.tar.gz | 29.0 kB | Without provenance | Details for py_starforge-1.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| py_starforge-1.0.3-py3-none-any.whl | Python 3 | none | any | Details for py_starforge-1.0.3-py3-none-any.whl |
Total release size: 57.9 kB
Release files / py_starforge-1.0.3.tar.gz
| Download URL | py_starforge-1.0.3.tar.gz |
|---|---|
| Size | 29.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5f49249e4282378ae153fab4ff11280edad0a6e9788a82459490a755ca9e6a7a
|
|
BLAKE2b-256 checksum How to use checksums |
2313590b754e4dcf8a9b1e71a707079745c55e787c30a693e46e8525a80ff3fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
Release files / py_starforge-1.0.3-py3-none-any.whl
| Download URL | py_starforge-1.0.3-py3-none-any.whl |
|---|---|
| Size | 28.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
29f403af88ee579a34e296e1733b1ff33c59cce8cf1e5d4f769902a1ac0df8b1
|
|
BLAKE2b-256 checksum How to use checksums |
8ac54a2d350fafc9dff892999b6276c4815ef6eac5f6ebe2612cc8ea63e284ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
Security for py-starforge 1.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.