Stellium v0.18.1: Misc fixes

[0.18.1] - 2026-05-03

Added

• Cookbook file for essential/accidental dignities, scoring, peregrine, mutual reception, dispositor graphs: examples/dignities_cookbook.py

Changed

Fixed

• Added .with_aspects() method call for ChartBuilder examples in readme so aspects are properly calculated and drawn.
• Transit timeline strftime on Windows — %-d (strip leading zero) is a Unix-only format code that raises ValueError on Windows. Replaced with f"{d.day}" for cross-platform date formatting in TransitListSection.
• preset_detailed() moon phase / chart shape overlap — the auto-hide logic that suppresses the chart shape label when the moon phase occupies the bottom-right corner was not triggering when moon phase position was set to None (auto-detect). Since None resolves to the config default of "bottom-right", the check now treats None equivalently, correctly hiding the chart shape to prevent overlap.

Stellium v0.18.0: Bazi, More Orbs, and Misc Fixes

Stellium 0.18.0

Released: 2026-04-26

BaZi has been in development for a while. In 0.18.0 it's largely implemented with 176 tests, 23 cookbook examples, Day Master strength analysis, and full ChartBuilder integration. The same builder you use for Western and Vedic charts now handles Chinese astrology too.

Alongside that: configurable ephemeris paths (Stellium is now Docker/Lambda deployable), Chiron finally bundled, 29 coordinate corrections in the notables registry, traditional moiety orbs, and tertiary/minor progressions.

---

New Features

BaZi: Four Pillars of Destiny

BaZi (四柱命理) is now a complete, first-class chart type in Stellium. The ChartBuilder handles timezone resolution automatically with no manual offset needed.

# Recommended entry point: same builder, works for everything
chart = ChartBuilder.from_details("1994-01-06 11:47", "Palo Alto, CA").bazi()

# Or from an existing CalculatedChart
bazi = calculated_chart.bazi()

What's included:

• Four Pillars: Year, Month, Day, Hour pillars with Heavenly Stems and Earthly Branches
• Five Elements analysis: Wu Xing cycle scoring, element balance
• Ten Gods: relational roles derived from Day Master and element interactions
• Day Master Strength Analysis: BaZi's equivalent of chart ruler analysis: classifies the native as Very Strong/Strong/Moderate/Weak/Very Weak based on seasonal strength, root count, and supporting vs. draining elements. Returns favorable/unfavorable elements. Available as bazi.strength().
• Solar terms: Li Chun boundary handling, year edge cases
• Rendering: Rich terminal output, prose format, JSON export

strength = bazi.strength()
print(strength.classification)       # "Weak"
print(strength.favorable_elements)   # ["Water", "Metal"]
print(strength.score)                # weighted numeric score

176 tests in test_bazi.py. 23 examples in examples/bazi_cookbook.py.

Configurable Ephemeris Directory

Stellium now supports a three-tier ephemeris path system:

# 1. Explicit argument: highest priority
engine = SwissEphemerisEngine(ephe_path="/path/to/your/ephe")

# 2. Environment variable: no code changes needed
# export STELLIUM_EPHE_PATH=/opt/ephe

# 3. Default ~/.stellium/ephe/ unchanged for existing users

Custom paths are used as-is. Stellium won't create the directory or copy bundled files into it, so it's safe to point at an existing Swiss Ephemeris installation or a read-only folder. Missing custom directories emit a stderr warning instead of crashing.

This makes Stellium properly deployable in environments where writing to the home directory isn't an option.

New helpers: get_ephe_dir(), has_ephe_file(name), reset_ephe_initialization(). 13 new tests in test_ephemeris_paths.py.

MoietyOrbEngine: Traditional Orb Calculation

Traditional astrology uses moiety-based orbs: each planet has its own sphere of influence, and the effective orb for an aspect is the average of both planets' orbs. Two named systems ship out of the box:

from stellium.engines import MoietyOrbEngine, LILLY_FULL_ORBS, PTOLEMY_FULL_ORBS

# Medieval consensus (Lilly, Bonatti, Al-Biruni, Sahl)
engine = MoietyOrbEngine("lilly")

# Wider Ptolemaic values
engine = MoietyOrbEngine("ptolemy")

# Custom map
engine = MoietyOrbEngine(orb_map={...}, minor_aspect_multiplier=0.5)

See examples/aspects_and_orbs_cookbook.py for side-by-side comparisons of all four orb engines and a complete moiety calculation table.

Tertiary and Minor Progressions

# Secondary (default, unchanged)
builder.progression(date)

# Tertiary: day-for-a-lunar-month (~13× faster than secondary)
builder.progression(date, progression_type="tertiary")

# Minor: lunar-month-for-a-year (~27× faster than secondary)
builder.progression(date, progression_type="minor")

All existing progression features work with all types: angle methods, cross-aspects, house overlays, visualization.

Input Validation on Public API Entry Points

Native, ElectionalSearch, ReturnBuilder.solar(), ReturnBuilder.lunar(), and ReturnBuilder.planetary() now validate their inputs immediately with clear error messages, rather than failing deep in calculation with an unhelpful traceback.

Notable Fixes

Chiron Now Bundled

Chiron is in the default planet list but its ephemeris file (se00015.se1, 389KB) wasn't shipped with the package. Every chart showed a "Missing ephemeris" warning. It's now included and works out of the box.

29 Notable Birth Coordinates Corrected

Full verification of all 196 geocode cache entries against Nominatim revealed 28 locations with significant coordinate drift in the notables YAML files. Worst cases: Prince Philip (986km off -- Mon Repos placed in mainland Greece instead of Corfu), Patrice Lumumba (520km off), Rumi (158km off). Incorrect coordinates produce incorrect house cusps, so if you've been using ChartBuilder.from_notable() for any of the affected entries, recalculate.

A bundled geocode cache (196 pre-geocoded locations) now ships with the package, so string geocoding checks the cache first (instant, no network) before falling back to Nominatim. Eliminates geocoding failures in CI and reduces API rate-limiting in production.

Historical Charts No Longer Rejected

An overly strict year range validation (1800–2400 CE) on Native was rejecting historical charts (Newton (1643), da Vinci (1452), etc.) even though Swiss Ephemeris handles them via analytical methods. The validation is removed. This was also silently dropping 8 YAML files from the notable registry on CI, reducing it from 197 to 101 entries.

Other Fixes

• Asteroid download URL: ephe2/ → ephe/ on ephe.scryr.io. The old URL returned 404 for all asteroid downloads.
• Typst PDF compilation on Windows: fixed crash when tempfile returns a path on a different drive than / root.
• Notable registry error handling: one bad YAML entry no longer silently skips the entire file.
• Ruff pre-commit hook aligned from v0.8.0 to v0.12.4, eliminating persistent reformatting on every commit.

Upgrade Notes

pip install --upgrade stellium

Coordinate corrections: If you've used ChartBuilder.from_notable() and stored results, any of the 29 corrected entries will produce different house cusps after upgrading. Check the CHANGELOG for the full list of affected notables.

Historical charts: If you were working around the year range restriction, those workarounds can be removed.

Everything else is additive. Existing code continues to work unchanged.

Stellium v0.17.0: Docs Infra and Fixes and Component Access

Stellium 0.17.0

Released: 2026-04-01

get_component_result() gives a central API for accessing component data. A new testing infrastructure means the docs and cookbooks actually stay accurate.

---

New Features

get_component_result(): Unified Component Access

Previously, getting results back out of a calculated component required knowing which storage pattern it used internally: position-based, metadata-based, dual-storage, or analyzer. Different components, different access patterns, no single answer to "how do I get this?"

That's fixed. (Fixes #25)

# Works for all components — one pattern to remember
arabic_parts = chart.get_component_result("Arabic Parts")
midpoints = chart.get_component_result("Midpoints")
dignities = chart.get_component_result("dignities")          # alias lookup works too
patterns = chart.get_component_result("Aspect Patterns")
zr = chart.get_component_result("Zodiacal Releasing")

# Don't know what's available?
print(chart.available_components())
# ['Arabic Parts', 'Aspect Patterns', 'Dignities', 'Midpoints', ...]

available_components() returns a sorted list of everything on the chart. get_component_result() raises a KeyError with a helpful message listing available names if you ask for something that isn't there.

New components automatically work with get_component_result() via a component manifest. No changes to CalculatedChart are required as the library grows.

20 new tests in test_get_component_result.py.

---

Infrastructure

Documentation and Cookbooks Are Now Tested

The short version: most code examples in the docs and cookbooks now run as part of CI. If a future change breaks a README example or a cookbook recipe, it'll fail loudly instead of quietly rotting.

What's tested:

• Cookbook smoke tests (test_cookbooks.py): 17 subprocess tests covering every .py cookbook, plus opt-in notebook execution. Typst-dependent cookbooks gracefully skip when Typst isn't installed.
• Doc code block tests (test_doc_codeblocks.py): extracts and executes Python code blocks from 11 markdown files (README, CONTRIBUTING, CLAUDE.md, docs/REPORTS, docs/VISUALIZATION, docs/options_list, and more). Blocks marked <!--pytest.mark.skip--> are excluded.
• CI split: "library tests" and "documentation validation" now run as separate steps so doc drift is caught on every push and PR.

Setting this up found and fixed 40+ broken examples across docs and cookbooks. This was due to a mix of API drift, stale patterns, and a handful of genuine crashes in the cookbook examples. All cleaned up.

Three-Tier Test Architecture

pytest -m "not slow"    # ~2.4s: TDD inner loop
pytest                  # ~32s: full library suite (~1,938 tests)
pytest -m docs          # ~4 min: documentation validation
pytest -m notebooks     # opt-in: notebook execution (very expensive)

pytest-codeblocks, nbconvert, and ipykernel added to [dev] dependencies.

---

Bug Fixes

part.house in README Arabic Parts example: CelestialPosition has no .house attribute. Fixed to use chart.get_house(part.name).

polymaths.yml renamed to polymaths.yaml: the notable births registry glob (*.yaml) wasn't picking it up.

TraditionalAspectEngine removed from engines/__init__.py docstring: class doesn't exist; replaced by HarmonicAspectEngine some time ago.

add_component(AspectPatternAnalyzer()) -> add_analyzer() in preset_full() docstring.

GraphicEphemeris.draw() signature now accepts str | Path (was str only).

---

Upgrade Notes

pip install --upgrade stellium

get_component_result() and available_components() are purely additive. Existing component access patterns continue to work. This is just a more convenient, centralized method of access.

If you're a contributor: pip install stellium[dev] now pulls in the doc testing dependencies.

Stellium v0.16.0: LLM Prompts, Vedic Charts and Bugfixes

Stellium 0.16.0

Released: 2026-03-25

Two headline features, a test suite that got serious, and a cluster of correctness fixes that were silently wrong in ways that mattered.

---

New Features

Vedic Chart Rendering

North Indian and South Indian chart styles are now first-class citizens alongside the Western wheel.

# One-liner, chainable
chart.draw_vedic("north.svg")
chart.draw_vedic("south.svg", style="south_indian")
 
# Or chain them
chart.draw_vedic("north.svg").draw_vedic("south.svg", style="south_indian")

North Indian (NorthIndianRenderer): square frame with inner diamond, 12 triangular fixed houses, signs rotate based on ASC ( the traditional lozenge layout.)

South Indian (SouthIndianRenderer): 4×4 grid with fixed sign positions, planets placed by sign, house numbers relative to ASC.

Both styles support:

• 3 themes: classic (white), dark (navy), traditional (saffron/parchment)
• 4 label styles: abbreviation (Ari, Su), number (traditional North Indian sign numbers), glyph (Unicode symbols), full (spelled out)
• Degree + minutes display, retrograde markers, full native info

See examples/vedic_cookbook.py for 7 examples covering both styles, all themes, ayanamsa comparison, and more.

---

chart.to_prompt_text(): Paste-Ready Chart Export

Generates clean, human-readable markdown from any chart, ready to drop into an LLM prompt.

# Full chart as markdown
text = chart.to_prompt_text()
 
# Selective sections
text = chart.to_prompt_text(sections=["planets", "aspects", "dignities"])

Covers everything:

• Planetary positions with sign, degree+minutes, house, declination, OOB flag, retrograde marker
• Component results: Arabic Parts, midpoints, fixed stars, dignities, antiscia, aspect patterns
• Multi-house-system support — per-planet placements and per-system cusp listings
• Display name resolution via CELESTIAL_REGISTRY (e.g. "Mean Apogee" → "Black Moon Lilith")
• All chart types: natal, synastry/transits (with cross-chart aspects and house overlays), composite/Davison, unknown-time
• Robust to future or user-side compoment/analyzer additions: displays "extra" positions or chart metadata in catchall section of the markdown (enabled by default)
• 39 tests across all chart types (test_prompt_text.py).

---

Transit Gantt: Themes, Legend, and Bar Clamping

The transit Gantt chart introduced in 0.15.3 has been polished:

• Two themes: "dark" (default, dark blue background) and "light" (white background)
• Legend: aspect color swatches, tick mark explanation ("Exact date"), and arrow indicator ("Extends beyond window")
• Bar clamping: transits that start before or end after the chart window are now clipped to the chart area with subtle arrow indicators instead of overflowing into the labels

See examples/transit_cookbook.py for 6 examples, and the new images/transit_gantt_example.svg / images/transit_gantt_example_light.svg (Einstein's 2025–2026 transits) for reference output.

---

Improvements

Thank you to @TheDaniel166 for his multiple bug reports and fix suggestions in issue #24.

Applying/Separating: Analytical Approach

_is_applying in aspects.py has been rewritten from numerical 1-minute integration to relative velocity analysis. Three concrete improvements:

• Zodiac seam: % 360 wrapping on future positions was producing wrong results for aspects near 0°/360°. The analytical approach eliminates this entirely.
• Stationary bodies: speed_longitude == 0 was conflating "no speed data" with "genuinely stationary." Now uses explicit _STATIONARY_THRESHOLD (0.005°/day). Stationary planets return None instead of being misclassified.
• 24 new tests in test_applying_separating.py covering basic detection, stationary bodies, seam edge cases, retrograde motion, and the angular distance helper.

Chart Shape Span: Largest-Gap Method

_calculate_span in chart_shape.py now uses 360 - max_gap instead of naive (last - first) % 360. Previously, a Bundle or Bowl pattern straddling the Aries point (e.g., planets at 350°, 355°, 5°, 10°) would calculate as a 340° span instead of 20°, misidentifying the chart shape entirely. Fixed.

19 new tests in test_chart_shape.py.

---

Bug Fixes

"chalean" typo in dignity calculators (fixes #24): (oops) TraditionalDignityCalculator() and ModernDignityCalculator() raised ValueError when instantiated with no arguments. The default argument was "chalean" instead of "chaldean". Regression tests added.

The applying/separating and chart shape seam issues above were also part of #24.

---

Tests

New file	Tests	Coverage
test_applying_separating.py	24	Applying/separating detection, edge cases
test_chart_shape.py	19	Span calculation, shape detection, seam regression
test_prompt_text.py	39	All chart types for to_prompt_text()
Dignity default constructor	handful	"chalean" regression

Fast/slow test split: 30 test files are now marked @pytest.mark.slow. Fast subset runs 719 tests in 2.4s for rapid TDD. Full suite runs ~1,938 tests in 30s.

pytest -m "not slow"   # 2.4s -  use this while writing
pytest                 # 30s - full suite

---

Upgrade Notes

pip install --upgrade stellium

The applying/separating and chart shape fixes are correctness changes. If you have stored results or tests depending on applying/separating classification near the 0°/360° seam, or chart shape detection for patterns straddling the Aries point, those results will change (correctly) after upgrading.

The "chalean" fix means TraditionalDignityCalculator() and ModernDignityCalculator() now work with no arguments as documented. If you were passing "chaldean" explicitly as a workaround, your code continues to work unchanged.

Stellium v0.15.3: Transit charts and sect bugfix

Stellium 0.15.3

Released: 2026-03-15

---

New Features

Transit Period Calculation & Visualization

The headline addition: presentation/sections/transit_periods.py brings full transit period analysis to the report builder, including retrograde multi-pass handling and an SVG Gantt chart output.

calculate_transit_periods() calculates orb entry/exit windows and all exact dates for every transit-to-natal aspect. Retrograde transits that make multiple passes are handled correctly. If Jupiter stations retrograde mid-transit and crosses your natal Venus three times, you get all three exact dates and the full orb window as a single period marked is_multi_pass=True. Fully reuses existing engines.search functions. No new astronomical logic, just orchestration.

TransitPeriod dataclass: frozen, with everything you need:

@dataclass(frozen=True)
class TransitPeriod:
    transit_planet: str
    natal_planet: str
    aspect_name: str
    exact_dates: list[date]
    start: date
    end: date
    is_multi_pass: bool
    duration_days: int

TransitListSection: plain-text transit list for ReportBuilder:

Dec 2 – Mar 2 '26 — Jupiter △ natal Chiron
Jan 15 – Feb 28 '26 — Saturn □ natal Venus  ↻ (3 passes)

TransitGanttSection: SVG Gantt timeline chart grouped by transiting planet. Bars show orb windows; tick marks show exact dates. Drops directly into report output.

---

House System Exports: All 18 Now Available

stellium.engines previously exported 4 house systems. All 18 are now exported:

from stellium.engines import (
    # Previously available
    PlacidusHouses, KochHouses, WholeSignHouses, EqualHouses,
    # Now exported
    AlcabitiusHouses, APCHouses, AxialRotationHouses, CampanusHouses,
    EqualMCHouses, EqualVertexHouses, GauquelinHouses, HorizontalHouses,
    KrusinskiHouses, MorinusHouses, PorphyryHouses, RegiomontanusHouses,
    TopocentricHouses, VehlowEqualHouses,
)

These systems were implemented but not publicly exported. If you were importing them directly from internal modules as a workaround, you can now use the public API.

---

Additional Exports from stellium.engines

• ZodiacalReleasingEngine and ZodiacalReleasingAnalyzer: previously accessible only via internal imports
• AspectPatternAnalyzer: same

---

stellium.utils Chart Shape Exports

from stellium.utils import detect_chart_shape, get_chart_shape_description, ChartShape

detect_chart_shape, get_chart_shape_description, and the ChartShape enum are now part of the public API.

---

CrossChartAspectEngine Protocol Complete

core/protocols.py now has a complete calculate_cross_aspects() method definition on CrossChartAspectEngine. Previously the protocol was partially stubbed.

---

Bug Fixes

Sect calculation was inverted: day/night sect was flipped, giving incorrect results for all sect-based dignity calculations. Thanks to @bkermott for the fix and added tests. If you were using sect-sensitive calculations, your results will change -- correctly -- with this release.

Typo in Taurus Chaldean decan data: "Mecury" → "Mercury" in engines/dignities.py. If you were matching on planet name strings in decan data, update your comparisons.

Zodiacal releasing cookbook example: fixed incorrect example that was producing wrong output.

Typo in ChartLocation validation message: "Invalud latitude" → "Invalid latitude".

---

Upgrade Notes

pip install --upgrade stellium

The sect fix is a correctness change. Any calculations involving sect will produce different (correct!) results after upgrading. If you have stored results or tests that depend on the previous (incorrect) sect behavior, they'll need to be updated.

Everything else is additive. Existing code continues to work unchanged.

Stellium v0.15.2: License update on PyPI

License was changed from MIT to AGPLv3 some time ago (to reflect upstream dependencies, see this ticket: #22). This release updates the readme mentions and PyPI license field to match.

Stellium v0.15.1: Delta-T bugfix and Midpoint Trees

[0.15.1] - 2026-01-06

Fixed

Delta T Calculation Bug Affecting Angles (ASC/MC)

Fixed incorrect Delta T handling that caused Ascendant and MC to be off by ~15 arcminutes for modern charts.

The Bug: The code was incorrectly subtracting Delta T from the Julian Day after computing it from UTC. Since swe.julday() with UTC input already produces JD(UT), and swe.houses_ex() expects JD(UT), the subtraction was wrong and shifted all angle calculations.

Impact: For a 1994 birth, Delta T ≈ 60 seconds, causing ~15 arcminute error in the Ascendant. The error scales with Delta T (larger for dates further from 2000).

Files Fixed:

• stellium/core/native.py - Removed erroneous Delta T subtraction
• stellium/utils/time.py - Removed erroneous Delta T subtraction

Technical Note: Swiss Ephemeris _ut functions (swe.calc_ut(), swe.houses_ex()) expect Julian Day in Universal Time and handle Delta T conversion internally when needed for ephemeris calculations.

Added

Midpoint Tree Visualization

New MidpointTreeSection in stellium.presentation.sections that generates tree diagrams showing which midpoints aspect focal points. A standard Uranian/Hamburg astrology technique for interpreting planetary pictures.

Features:

• Configurable tree bases (focal points) - defaults to Sun, Moon, MC, ASC
• Configurable branch objects for midpoint pairs - defaults to 10 planets + angles + nodes
• Support for Hamburg/Uranian hypothetical planets when chart includes them
• Aspect modes: "conjunction" (0° only), "hard" (0°, 45°, 90°, 135°, 180°), or "all"
• Tight orb control (default 1.5°) to prevent data explosion
• 3-column SVG layout for compact visualization
• Text output with ASCII tree structure
• Smart glyph fallbacks (uses glyph when available, short name otherwise)

Usage:

from stellium import ChartBuilder, Native, ReportBuilder
from stellium.components import MidpointCalculator

chart = (ChartBuilder.from_native(native)
    .with_uranian()  # Optional: include Hamburg planets
    .add_component(MidpointCalculator())
    .calculate())

# Via ReportBuilder
report = (ReportBuilder()
    .from_chart(chart)
    .with_midpoint_trees(aspect_mode="hard", orb=1.5)
    .render())

# Direct section use for SVG export
from stellium.presentation.sections import MidpointTreeSection

section = MidpointTreeSection(
    tree_bases=["Sun", "Moon", "ASC", "MC"],
    aspect_mode="hard",
    output="svg"
)
data = section.generate_data(chart)
# data["content"] contains SVG string

Example output:

☉ Sun (16°16' ♑︎)
    ├── ☿/♀ ☌ 0.3°  Mercury/Venus
    └── ☿/♂ ☌ 0.5°  Mercury/Mars

ASC (16°57' ♈︎)
    ├── ☉/☿ □ 0.2°  Sun/Mercury
    └── ☿/♀ □ 1.0°  Mercury/Venus

Changed

Stellium v0.15.0: Vectors, Ba Zi and Timelines

Stellium 0.15.0 is a release that expands the library's scope in two directions: forward into Machine Learning and eastward into Chinese Metaphysics.

This update introduces a native Vector Embedding engine for charts (enabling O(1) similarity search and ML pipeline integration) and a fully-featured BaZi (Four Pillars) engine with Ten Gods analysis and rich visualization. On the Western front (ha), I've added professional-grade visualizations for Zodiacal Releasing timelines and spiraling Profection Wheels, along with a full GUI Planner in the webapp.

Machine Learning & Analysis

• Chart Vector Embeddings: New stellium.analysis.vector module to transform charts into dense, fixed-length NumPy arrays.
• Cyclic Encoding: Uses sin/cos pairs for all 360° positions to preserve geometric continuity.
• Similarity Search: Includes cosine similarity functions to instantly find similar charts or transits.
• ML Ready: Perfect for clustering, pattern recognition models, or recommender backends.

from stellium.analysis.vector import ChartVectorizer

# Transform charts into math
vectorizer = ChartVectorizer(include_speed=True)
vec_a = vectorizer.encode(chart_a)
vec_b = vectorizer.encode(chart_b)

# Find similarity (-1.0 to 1.0)
print(f"Similarity: {vectorizer.similarity(vec_a, vec_b):.3f}")

Chinese Astrology (BaZi)

A complete engine for Four Pillars of Destiny calculation and analysis (stellium.chinese).

• Core Engine: Calculates Pillars based on exact Solar Terms (Jie Qi) and solar longitudes.
• Deep Analysis: Full Ten Gods (十神) implementation, including hidden stems (Ben Qi, Zhong Qi, Yu Qi) and interaction analysis.
• Renderers: Includes BaziRichRenderer for beautiful terminal output, plus SVG and prose options.

from stellium.chinese.bazi import BaZiEngine, BaziRichRenderer

# Calculate & Render in Terminal
chart = BaZiEngine().calculate(datetime.now())
BaziRichRenderer().print_chart(chart)

Advanced Visualization

• Zodiacal Releasing Timelines: New Honeycomb-style stacked timeline visualizations. Shows peak periods (L1/L2/L3) with characteristic slopes and highlighting for "Loosing of the Bond."
• Profection Wheels: A new visualization for Annual Profections, featuring a spiraling age-ring design (ages 0-95) that visually maps the movement of the Time Lord through the houses.

Webapp

• Planner GUI: Added a full /planner interface to the web application. Users can now generate the PDF Astrological Planner via a friendly UI with options for page size (A4/A5/Letter), custom date ranges, and modular content toggles.

Improvements & Refactors

• Layer Architecture: The stellium.visualization.layers module has been refactored into a clean sub-package structure (layers/planets, layers/zodiac, etc.) for better maintainability. Fully backward compatible.
• Page Sizes: Added native support for A5 page sizes in the Planner and Report builders.

---

For full details, see the CHANGELOG.

Stellium v0.14.0: Chart Atlas, Antiscia and Visual Polish

v0.14.0: The Atlas Update – PDF Chart Books, Antiscia & Visual Polish

This release introduces the Chart Atlas, a powerful new way to generate multi-page PDF chart compilations, adds support for Antiscia/Contra-antiscia, and significantly overhauls the chart rendering engine for better label placement and PDF font support.

Highlights

Chart Atlas PDF Generation

The new AtlasBuilder allows you to generate professional multi-page PDF documents containing one chart per page—perfect for creating client files, research study sets, or printed reference books.

• Bulk Generation: Create a PDF book of every "Notable Scientist" in the database in one line of code.
• Mixed Types: Support for both standard wheel charts and Uranian 90° dials in the same document.
• Typst Integration: Uses the typst engine for crisp, vector-based PDF rendering.
• New "Atlas" Theme: A cream-colored (#FAF8F5) theme with purple and gold accents, designed specifically for printed output.

from stellium.visualization.atlas import AtlasBuilder

# Generate a PDF book of famous scientists
(AtlasBuilder()
    .add_notable("Albert Einstein")
    .add_notable("Marie Curie")
    .with_title_page("Famous Scientists")
    .with_theme("atlas")
    .save("scientists_atlas.pdf"))

Antiscia & Contra-Antiscia

Added a new AntisciaCalculator component to calculate solstice points (Antiscia) and equinox points (Contra-Antiscia). This component can detect "hidden" conjunctions between planets and these shadow points.

from stellium.components import AntisciaCalculator

# Detect hidden connections
chart = ChartBuilder.from_native(native).add_component(AntisciaCalculator(orb=1.5)).calculate()

Visual Engine Upgrades

• Smart Collision Detection: Completely rewrote the planet glyph placement algorithm. It is now radius-aware, meaning it allows tighter spacing on outer rings and enforces wider angular separation on inner rings. This resolves the "overlapping glyphs" issue in complex bi-wheels and tri-wheels.
• Info Corners: Charts (especially in Atlas mode) now support informational corners displaying an Aspect Count summary and an Element/Modality cross-table.
• PDF Symbols Fixed: Fixed an issue where symbols for Chiron, Lilith, Vertex, and Retrograde (℞) rendered as missing boxes in PDF exports. They now use correct embedded fonts.

---

Full Changelog

Added

• AtlasBuilder for generating multi-page PDF chart atlases.
• AntisciaCalculator component and AntisciaSection for reports.
• New atlas visualization theme.
• AspectCountsLayer and ElementModalityTableLayer for chart corners.
• Header support for Uranian Dial charts via .with_header().

Fixed

• Glyph Collision: Implemented force-based iterative spreading for planet glyphs to prevent overlaps on crowded charts.
• Font Rendering: Fixed missing glyphs for asteroids and points in PDF output (using Symbola/Noto fonts).
• Dial Charts: Fixed header rendering alignment on dial charts.

Stellium v0.13.0: PDF Planner Generator

PDF Planner Generator

Stellium can now generate beautiful personalized astrological planners as PDF files! Create 12-month planners with your natal chart, transits, Moon phases, and more.

Features

• Front matter pages: Natal chart, progressed chart, solar return, annual profection info, graphic ephemeris
• Monthly calendar grids: Full-page calendar view with all events in each day cell
• Weekly detail pages: 7-day spreads with compact event listings
• Rainbow zodiac palette: All charts rendered with colorful sign backgrounds
• Configurable week start: Sunday (US) or Monday (European) style
• Multiple page sizes: A4, Letter, or half-letter with optional binding margins

Quick Start

  from stellium import Native, PlannerBuilder

  native = Native("1990-05-15 14:30", "San Francisco, CA")

  planner = (
      PlannerBuilder.for_native(native)
      .year(2025)
      .timezone("America/Los_Angeles")
      .with_natal_chart()
      .with_solar_return()
      .with_graphic_ephemeris(harmonic=90)
      .include_natal_transits()  # All planets + Node + Chiron
      .include_moon_phases()
      .include_voc(mode="traditional")
      .generate("my_planner.pdf")
  )

Daily Events Tracked

• Transit-to-natal aspects (all 10 planets + True Node + Chiron)
• Moon phases (New Moon, Full Moon)
• Void of Course Moon periods (traditional or modern)
• Planet ingresses (sign changes)
• Planetary stations (retrograde/direct)
• Eclipses (solar and lunar)

Requirements

Requires the typst package for PDF rendering:

  pip install typst

Cookbook Examples

See examples/planner_cookbook.py for detailed recipes and usage patterns.