kerykeion 4.18.3__py3-none-any.whl → 5.1.9__py3-none-any.whl

kerykeion/charts/charts_utils.py

@@ -1,9 +1,230 @@
 import math
 import datetime
-from kerykeion.kr_types import KerykeionException, ChartType
-from typing import Union, Literal
-from kerykeion.kr_types.kr_models import AspectModel, KerykeionPointModel
-from kerykeion.kr_types.settings_models import KerykeionLanguageCelestialPointModel, KerykeionSettingsAspectModel
+from typing import Mapping, Optional, Sequence, Union, Literal
+
+from kerykeion.schemas import KerykeionException, ChartType
+from kerykeion.schemas.kr_literals import AstrologicalPoint
+from kerykeion.schemas.kr_models import AspectModel, KerykeionPointModel, CompositeSubjectModel, PlanetReturnModel, AstrologicalSubjectModel, HouseComparisonModel
+from kerykeion.schemas.settings_models import KerykeionLanguageCelestialPointModel, KerykeionSettingsCelestialPointModel
+
+
+ElementQualityDistributionMethod = Literal["pure_count", "weighted"]
+"""Supported strategies for calculating element and modality distributions."""
+
+_SIGN_TO_ELEMENT: tuple[str, ...] = (
+    "fire",    # Aries
+    "earth",   # Taurus
+    "air",     # Gemini
+    "water",   # Cancer
+    "fire",    # Leo
+    "earth",   # Virgo
+    "air",     # Libra
+    "water",   # Scorpio
+    "fire",    # Sagittarius
+    "earth",   # Capricorn
+    "air",     # Aquarius
+    "water",   # Pisces
+)
+
+_SIGN_TO_QUALITY: tuple[str, ...] = (
+    "cardinal",  # Aries
+    "fixed",     # Taurus
+    "mutable",   # Gemini
+    "cardinal",  # Cancer
+    "fixed",     # Leo
+    "mutable",   # Virgo
+    "cardinal",  # Libra
+    "fixed",     # Scorpio
+    "mutable",   # Sagittarius
+    "cardinal",  # Capricorn
+    "fixed",     # Aquarius
+    "mutable",   # Pisces
+)
+
+_ELEMENT_KEYS: tuple[str, ...] = ("fire", "earth", "air", "water")
+_QUALITY_KEYS: tuple[str, ...] = ("cardinal", "fixed", "mutable")
+
+_DEFAULT_WEIGHTED_FALLBACK = 1.0
+DEFAULT_WEIGHTED_POINT_WEIGHTS: dict[str, float] = {
+    # Core luminaries & angles
+    "sun": 2.0,
+    "moon": 2.0,
+    "ascendant": 2.0,
+    "medium_coeli": 1.5,
+    "descendant": 1.5,
+    "imum_coeli": 1.5,
+    "vertex": 0.8,
+    "anti_vertex": 0.8,
+    # Personal planets
+    "mercury": 1.5,
+    "venus": 1.5,
+    "mars": 1.5,
+    # Social planets
+    "jupiter": 1.0,
+    "saturn": 1.0,
+    # Outer/transpersonal
+    "uranus": 0.5,
+    "neptune": 0.5,
+    "pluto": 0.5,
+    # Lunar nodes (mean/true variants)
+    "mean_north_lunar_node": 0.5,
+    "true_north_lunar_node": 0.5,
+    "mean_south_lunar_node": 0.5,
+    "true_south_lunar_node": 0.5,
+    # Chiron, Lilith variants
+    "chiron": 0.6,
+    "mean_lilith": 0.5,
+    "true_lilith": 0.5,
+    # Asteroids / centaurs
+    "ceres": 0.5,
+    "pallas": 0.4,
+    "juno": 0.4,
+    "vesta": 0.4,
+    "pholus": 0.3,
+    # Dwarf planets & TNOs
+    "eris": 0.3,
+    "sedna": 0.3,
+    "haumea": 0.3,
+    "makemake": 0.3,
+    "ixion": 0.3,
+    "orcus": 0.3,
+    "quaoar": 0.3,
+    # Arabic Parts
+    "pars_fortunae": 0.8,
+    "pars_spiritus": 0.7,
+    "pars_amoris": 0.6,
+    "pars_fidei": 0.6,
+    # Fixed stars
+    "regulus": 0.2,
+    "spica": 0.2,
+    # Other
+    "earth": 0.3,
+}
+
+
+def _prepare_weight_lookup(
+    method: ElementQualityDistributionMethod,
+    custom_weights: Optional[Mapping[str, float]] = None,
+) -> tuple[dict[str, float], float]:
+    """
+    Normalize and merge default weights with any custom overrides.
+
+    Args:
+        method: Calculation strategy to use.
+        custom_weights: Optional mapping of point name (case-insensitive) to weight.
+                        Supports special key "__default__" as fallback weight.
+
+    Returns:
+        A tuple containing the weight lookup dictionary and fallback weight.
+    """
+    normalized_custom = (
+        {key.lower(): float(value) for key, value in custom_weights.items()}
+        if custom_weights
+        else {}
+    )
+
+    if method == "weighted":
+        weight_lookup: dict[str, float] = dict(DEFAULT_WEIGHTED_POINT_WEIGHTS)
+        fallback_weight = _DEFAULT_WEIGHTED_FALLBACK
+    else:
+        weight_lookup = {}
+        fallback_weight = 1.0
+
+    fallback_weight = normalized_custom.get("__default__", fallback_weight)
+
+    for key, value in normalized_custom.items():
+        if key == "__default__":
+            continue
+        weight_lookup[key] = float(value)
+
+    return weight_lookup, fallback_weight
+
+
+def _calculate_distribution_for_subject(
+    subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
+    celestial_points_names: Sequence[str],
+    sign_to_group_map: Sequence[str],
+    group_keys: Sequence[str],
+    weight_lookup: Mapping[str, float],
+    fallback_weight: float,
+) -> dict[str, float]:
+    """
+    Accumulate distribution totals for a single subject.
+
+    Args:
+        subject: Subject providing planetary positions.
+        celestial_points_names: Names of celestial points to consider (lowercase).
+        sign_to_group_map: Mapping from sign index to element/modality key.
+        group_keys: Iterable of expected keys for the resulting totals.
+        weight_lookup: Precomputed mapping of weights per point.
+        fallback_weight: Default weight if point missing in lookup.
+
+    Returns:
+        Dictionary with accumulated totals keyed by element/modality.
+    """
+    totals = {key: 0.0 for key in group_keys}
+
+    for point_name in celestial_points_names:
+        point = subject.get(point_name)
+        if point is None:
+            continue
+
+        sign_index = getattr(point, "sign_num", None)
+        if sign_index is None or not (0 <= sign_index < len(sign_to_group_map)):
+            continue
+
+        group_key = sign_to_group_map[sign_index]
+        weight = weight_lookup.get(point_name, fallback_weight)
+        totals[group_key] += weight
+
+    return totals
+
+
+_SECOND_COLUMN_THRESHOLD = 20
+_THIRD_COLUMN_THRESHOLD = 28
+_FOURTH_COLUMN_THRESHOLD = 36
+
+_DOUBLE_CHART_TYPES: tuple[ChartType, ...] = ("Synastry", "Transit", "DualReturnChart")
+_GRID_COLUMN_WIDTH = 125
+
+
+def _select_planet_grid_thresholds(chart_type: ChartType) -> tuple[int, int, int]:
+    """Return column thresholds for the planet grids based on chart type."""
+    if chart_type in _DOUBLE_CHART_TYPES:
+        return (
+            1_000_000, # effectively disable first column
+            1_000_008, # effectively disable second column
+            1_000_016, # effectively disable third column
+        )
+    return _SECOND_COLUMN_THRESHOLD, _THIRD_COLUMN_THRESHOLD, _FOURTH_COLUMN_THRESHOLD
+
+
+def _planet_grid_layout_position(
+    index: int, thresholds: Optional[tuple[int, int, int]] = None
+) -> tuple[int, int]:
+    """Return horizontal offset and row index for planet grids."""
+    second_threshold, third_threshold, fourth_threshold = (
+        thresholds
+        if thresholds is not None
+        else (_SECOND_COLUMN_THRESHOLD, _THIRD_COLUMN_THRESHOLD, _FOURTH_COLUMN_THRESHOLD)
+    )
+
+    if index < second_threshold:
+        column = 0
+        row = index
+    elif index < third_threshold:
+        column = 1
+        row = index - second_threshold
+    elif index < fourth_threshold:
+        column = 2
+        row = index - third_threshold
+    else:
+        column = 3
+        row = index - fourth_threshold
+
+    offset = -(_GRID_COLUMN_WIDTH * column)
+    return offset, row
+
 
 
 def get_decoded_kerykeion_celestial_point_name(input_planet_name: str, celestial_point_language: KerykeionLanguageCelestialPointModel) -> str:
@@ -18,13 +239,6 @@ def get_decoded_kerykeion_celestial_point_name(input_planet_name: str, celestial
         str: The decoded celestial point name.
     """
 
-    # Dictionary for special house names
-    special_house_names = {
-        "First_House": "Asc",
-        "Seventh_House": "Dsc",
-        "Tenth_House": "Mc",
-        "Fourth_House": "Ic"
-    }
 
     # Get the language model keys
     language_keys = celestial_point_language.model_dump().keys()
@@ -32,9 +246,8 @@ def get_decoded_kerykeion_celestial_point_name(input_planet_name: str, celestial
     # Check if the input planet name exists in the language model
     if input_planet_name in language_keys:
         return celestial_point_language[input_planet_name]
-
-    # Return the special house name if it exists, otherwise return an empty string
-    return special_house_names.get(input_planet_name, "")
+    else:
+        raise KerykeionException(f"Celestial point {input_planet_name} not found in language model.")
 
 
 def decHourJoin(inH: int, inM: int, inS: int) -> float:
@@ -56,24 +269,42 @@ def decHourJoin(inH: int, inM: int, inS: int) -> float:
 
 
 def degreeDiff(a: Union[int, float], b: Union[int, float]) -> float:
-    """Calculate the difference between two degrees.
+    """Calculate the smallest difference between two angles in degrees.
 
     Args:
-        - a (int | float): first degree
-        - b (int | float): second degree
+        a (int | float): first angle in degrees
+        b (int | float): second angle in degrees
 
     Returns:
-        float: difference between a and b
+        float: smallest difference between a and b (0 to 180 degrees)
     """
+    diff = math.fmod(abs(a - b), 360)  # Assicura che il valore sia in [0, 360)
+    return min(diff, 360 - diff)  # Prende l'angolo più piccolo tra i due possibili
+
+
+def degreeSum(a: Union[int, float], b: Union[int, float]) -> float:
+    """Calculate the sum of two angles in degrees, normalized to [0, 360).
+
+    Args:
+        a (int | float): first angle in degrees
+        b (int | float): second angle in degrees
+
+    Returns:
+        float: normalized sum of a and b in the range [0, 360)
+    """
+    return math.fmod(a + b, 360) if (a + b) % 360 != 0 else 0.0
 
-    out = float()
-    if a > b:
-        out = a - b
-    if a < b:
-        out = b - a
-    if out > 180.0:
-        out = 360.0 - out
-    return out
+
+def normalizeDegree(angle: Union[int, float]) -> float:
+    """Normalize an angle to the range [0, 360).
+
+    Args:
+        angle (int | float): The input angle in degrees.
+
+    Returns:
+        float: The normalized angle in the range [0, 360).
+    """
+    return angle % 360 if angle % 360 != 0 else 0.0
 
 
 def offsetToTz(datetime_offset: Union[datetime.timedelta, None]) -> float:
@@ -176,7 +407,7 @@ def draw_zodiac_slice(
     # pie slices
     offset = 360 - seventh_house_degree_ut
     # check transit
-    if chart_type == "Transit" or chart_type == "Synastry":
+    if chart_type == "Transit" or chart_type == "Synastry" or chart_type == "DualReturnChart":
         dropin: Union[int, float] = 0
     else:
         dropin = c1
@@ -185,7 +416,7 @@ def draw_zodiac_slice(
     # symbols
     offset = offset + 15
     # check transit
-    if chart_type == "Transit" or chart_type == "Synastry":
+    if chart_type == "Transit" or chart_type == "Synastry" or chart_type == "DualReturnChart":
         dropin = 54
     else:
         dropin = 18 + c1
@@ -274,54 +505,12 @@ def draw_aspect_line(
     y2 = sliceToY(0, ar, second_offset) + (r - ar)
 
     return (
-        f'<g kr:node="Aspect" kr:aspectname="{aspect["aspect"]}" kr:to="{aspect["p1_name"]}" kr:tooriginaldegrees="{aspect["p1_abs_pos"]}" kr:from="{aspect["p2_name"]}" kr:fromoriginaldegrees="{aspect["p2_abs_pos"]}">'
+        f'<g kr:node="Aspect" kr:aspectname="{aspect["aspect"]}" kr:to="{aspect["p1_name"]}" kr:tooriginaldegrees="{aspect["p1_abs_pos"]}" kr:from="{aspect["p2_name"]}" kr:fromoriginaldegrees="{aspect["p2_abs_pos"]}" kr:orb="{aspect["orbit"]}" kr:aspectdegrees="{aspect["aspect_degrees"]}" kr:planetsdiff="{aspect["diff"]}" kr:aspectmovement="{aspect["aspect_movement"]}">'
         f'<line class="aspect" x1="{x1}" y1="{y1}" x2="{x2}" y2="{y2}" style="stroke: {color}; stroke-width: 1; stroke-opacity: .9;"/>'
         f"</g>"
     )
 
 
-def draw_elements_percentages(
-    fire_label: str,
-    fire_points: float,
-    earth_label: str,
-    earth_points: float,
-    air_label: str,
-    air_points: float,
-    water_label: str,
-    water_points: float,
-) -> str:
-    """Draw the elements grid.
-
-    Args:
-        - fire_label (str): Label for fire
-        - fire_points (float): Points for fire
-        - earth_label (str): Label for earth
-        - earth_points (float): Points for earth
-        - air_label (str): Label for air
-        - air_points (float): Points for air
-        - water_label (str): Label for water
-        - water_points (float): Points for water
-
-    Returns:
-        str: The SVG elements grid as a string.
-    """
-    total = fire_points + earth_points + air_points + water_points
-
-    fire_percentage = int(round(100 * fire_points / total))
-    earth_percentage = int(round(100 * earth_points / total))
-    air_percentage = int(round(100 * air_points / total))
-    water_percentage = int(round(100 * water_points / total))
-
-    return (
-        f'<g transform="translate(-30,79)">'
-        f'<text y="0" style="fill: var(--kerykeion-chart-color-fire-percentage); font-size: 10px;">{fire_label}  {str(fire_percentage)}%</text>'
-        f'<text y="12" style="fill: var(--kerykeion-chart-color-earth-percentage); font-size: 10px;">{earth_label} {str(earth_percentage)}%</text>'
-        f'<text y="24" style="fill: var(--kerykeion-chart-color-air-percentage); font-size: 10px;">{air_label}   {str(air_percentage)}%</text>'
-        f'<text y="36" style="fill: var(--kerykeion-chart-color-water-percentage); font-size: 10px;">{water_label} {str(water_percentage)}%</text>'
-        f"</g>"
-    )
-
-
 def convert_decimal_to_degree_string(dec: float, format_type: Literal["1", "2", "3"] = "3") -> str:
     """
     Converts a decimal float to a degrees string in the specified format.
@@ -448,7 +637,7 @@ def draw_first_circle(
     Returns:
         str: The SVG path of the first circle.
     """
-    if chart_type == "Synastry" or chart_type == "Transit":
+    if chart_type == "Synastry" or chart_type == "Transit" or chart_type == "DualReturnChart":
         return f'<circle cx="{r}" cy="{r}" r="{r - 36}" style="fill: none; stroke: {stroke_color}; stroke-width: 1px; stroke-opacity:.4;" />'
     else:
         if c1 is None:
@@ -459,6 +648,21 @@ def draw_first_circle(
         )
 
 
+def draw_background_circle(r: Union[int, float], stroke_color: str, fill_color: str) -> str:
+    """
+    Draws the background circle.
+
+    Args:
+        - r (Union[int, float]): The value of r.
+        - stroke_color (str): The color of the stroke.
+        - fill_color (str): The color of the fill.
+
+    Returns:
+        str: The SVG path of the background circle.
+    """
+    return f'<circle cx="{r}" cy="{r}" r="{r}" style="fill: {fill_color}; stroke: {stroke_color}; stroke-width: 1px;" />'
+
+
 def draw_second_circle(
     r: Union[int, float], stroke_color: str, fill_color: str, chart_type: ChartType, c2: Union[int, float, None] = None
 ) -> str:
@@ -476,7 +680,7 @@ def draw_second_circle(
         str: The SVG path of the second circle.
     """
 
-    if chart_type == "Synastry" or chart_type == "Transit":
+    if chart_type == "Synastry" or chart_type == "Transit" or chart_type == "DualReturnChart":
         return f'<circle cx="{r}" cy="{r}" r="{r - 72}" style="fill: {fill_color}; fill-opacity:.4; stroke: {stroke_color}; stroke-opacity:.4; stroke-width: 1px" />'
 
     else:
@@ -506,7 +710,7 @@ def draw_third_circle(
     Returns:
     - str: The SVG element as a string.
     """
-    if chart_type in {"Synastry", "Transit"}:
+    if chart_type in {"Synastry", "Transit", "DualReturnChart"}:
         # For Synastry and Transit charts, use a fixed radius adjustment of 160
         return f'<circle cx="{radius}" cy="{radius}" r="{radius - 160}" style="fill: {fill_color}; fill-opacity:.8; stroke: {stroke_color}; stroke-width: 1px" />'
 
@@ -515,10 +719,10 @@ def draw_third_circle(
 
 
 def draw_aspect_grid(
-        stroke_color: str, 
-        available_planets: list, 
+        stroke_color: str,
+        available_planets: list,
         aspects: list,
-        x_start: int = 380,
+        x_start: int = 510,
         y_start: int = 468,
     ) -> str:
     """
@@ -535,18 +739,18 @@ def draw_aspect_grid(
         str: SVG string representing the aspect grid.
     """
     svg_output = ""
-    style = f"stroke:{stroke_color}; stroke-width: 1px; fill:none"
+    style = f"stroke:{stroke_color}; stroke-width: 1px; stroke-width: 0.5px; fill:none"
     box_size = 14
 
     # Filter active planets
-    active_planets = [planet for planet in available_planets if planet.is_active]
+    active_planets = [planet for planet in available_planets if planet["is_active"]]
 
     # Reverse the list of active planets for the first iteration
     reversed_planets = active_planets[::-1]
 
     for index, planet_a in enumerate(reversed_planets):
         # Draw the grid box for the planet
-        svg_output += f'<rect x="{x_start}" y="{y_start}" width="{box_size}" height="{box_size}" style="{style}"/>'
+        svg_output += f'<rect kr:node="AspectsGridRect" x="{x_start}" y="{y_start}" width="{box_size}" height="{box_size}" style="{style}"/>'
         svg_output += f'<use transform="scale(0.4)" x="{(x_start + 2) * 2.5}" y="{(y_start + 1) * 2.5}" xlink:href="#{planet_a["name"]}" />'
 
         # Update the starting coordinates for the next box
@@ -560,7 +764,7 @@ def draw_aspect_grid(
         # Iterate over the remaining planets
         for planet_b in reversed_planets[index + 1:]:
             # Draw the grid box for the aspect
-            svg_output += f'<rect x="{x_aspect}" y="{y_aspect}" width="{box_size}" height="{box_size}" style="{style}"/>'
+            svg_output += f'<rect kr:node="AspectsGridRect" x="{x_aspect}" y="{y_aspect}" width="{box_size}" height="{box_size}" style="{style}"/>'
             x_aspect += box_size
 
             # Check for aspects between the planets
@@ -586,6 +790,7 @@ def draw_houses_cusps_and_text_number(
     chart_type: ChartType,
     second_subject_houses_list: Union[list[KerykeionPointModel], None] = None,
     transit_house_cusp_color: Union[str, None] = None,
+    external_view: bool = False,
 ) -> str:
     """
     Draws the houses cusps and text numbers for a given chart type.
@@ -603,9 +808,10 @@ def draw_houses_cusps_and_text_number(
     - chart_type: Type of the chart (e.g., Transit, Synastry).
     - second_subject_houses_list: List of house for the second subject (optional).
     - transit_house_cusp_color: Color for transit house cusps (optional).
+    - external_view: Whether to use external view mode for positioning (optional).
 
     Returns:
-    - A string containing the SVG path for the houses cusps and text numbers.
+    - A string containing SVG elements for house cusps and numbers.
     """
 
     path = ""
@@ -613,7 +819,7 @@ def draw_houses_cusps_and_text_number(
 
     for i in range(xr):
         # Determine offsets based on chart type
-        dropin, roff, t_roff = (160, 72, 36) if chart_type in ["Transit", "Synastry"] else (c3, c1, False)
+        dropin, roff, t_roff = (160, 72, 36) if chart_type in ["Transit", "Synastry", "DualReturnChart"] else (c3, c1, False)
 
         # Calculate the offset for the current house cusp
         offset = (int(first_subject_houses_list[int(xr / 2)].abs_pos) / -1) + int(first_subject_houses_list[i].abs_pos)
@@ -635,7 +841,7 @@ def draw_houses_cusps_and_text_number(
             i, standard_house_cusp_color
         )
 
-        if chart_type in ["Transit", "Synastry"]:
+        if chart_type in ["Transit", "Synastry", "DualReturnChart"]:
             if second_subject_houses_list is None or transit_house_cusp_color is None:
                 raise KerykeionException("second_subject_houses_list_ut or transit_house_cusp_color is None")
 
@@ -659,30 +865,34 @@ def draw_houses_cusps_and_text_number(
 
             # Add the house number text for the second subject
             fill_opacity = "0" if chart_type == "Transit" else ".4"
-            path += f'<g kr:node="HouseNumber">'
+            path += '<g kr:node="HouseNumber">'
             path += f'<text style="fill: var(--kerykeion-chart-color-house-number); fill-opacity: {fill_opacity}; font-size: 14px"><tspan x="{xtext - 3}" y="{ytext + 3}">{i + 1}</tspan></text>'
-            path += f"</g>"
+            path += "</g>"
 
             # Add the house cusp line for the second subject
             stroke_opacity = "0" if chart_type == "Transit" else ".3"
-            path += f'<g kr:node="Cusp">'
+            path += f'<g kr:node="Cusp" kr:absoluteposition="{second_subject_houses_list[i].abs_pos}" kr:signposition="{second_subject_houses_list[i].position}" kr:sing="{second_subject_houses_list[i].sign}" kr:slug="{second_subject_houses_list[i].name}">'
             path += f"<line x1='{t_x1}' y1='{t_y1}' x2='{t_x2}' y2='{t_y2}' style='stroke: {t_linecolor}; stroke-width: 1px; stroke-opacity:{stroke_opacity};'/>"
-            path += f"</g>"
+            path += "</g>"
 
-        # Adjust dropin based on chart type
-        dropin = {"Transit": 84, "Synastry": 84, "ExternalNatal": 100}.get(chart_type, 48)
+        # Adjust dropin based on chart type and external view
+        dropin_map = {"Transit": 84, "Synastry": 84, "DualReturnChart": 84}
+        if external_view:
+            dropin = 100
+        else:
+            dropin = dropin_map.get(chart_type, 48)
         xtext = sliceToX(0, (r - dropin), text_offset) + dropin
         ytext = sliceToY(0, (r - dropin), text_offset) + dropin
 
         # Add the house cusp line for the first subject
-        path += f'<g kr:node="Cusp">'
+        path += f'<g kr:node="Cusp" kr:absoluteposition="{first_subject_houses_list[i].abs_pos}" kr:signposition="{first_subject_houses_list[i].position}" kr:sing="{first_subject_houses_list[i].sign}" kr:slug="{first_subject_houses_list[i].name}">'
         path += f'<line x1="{x1}" y1="{y1}" x2="{x2}" y2="{y2}" style="stroke: {linecolor}; stroke-width: 1px; stroke-dasharray:3,2; stroke-opacity:.4;"/>'
-        path += f"</g>"
+        path += "</g>"
 
         # Add the house number text for the first subject
-        path += f'<g kr:node="HouseNumber">'
+        path += '<g kr:node="HouseNumber">'
         path += f'<text style="fill: var(--kerykeion-chart-color-house-number); fill-opacity: .6; font-size: 14px"><tspan x="{xtext - 3}" y="{ytext + 3}">{i + 1}</tspan></text>'
-        path += f"</g>"
+        path += "</g>"
 
     return path
 
@@ -691,7 +901,13 @@ def draw_transit_aspect_list(
     grid_title: str,
     aspects_list: Union[list[AspectModel], list[dict]],
     celestial_point_language: Union[KerykeionLanguageCelestialPointModel, dict],
-    aspects_settings: Union[KerykeionSettingsAspectModel, dict],
+    aspects_settings: dict,
+    *,
+    aspects_per_column: int = 14,
+    column_width: int = 100,
+    line_height: int = 14,
+    max_columns: int = 6,
+    chart_height: Optional[int] = None,
 ) -> str:
     """
     Generates the SVG output for the aspect transit grid.
@@ -699,69 +915,106 @@ def draw_transit_aspect_list(
     Parameters:
     - grid_title: Title of the grid.
     - aspects_list: List of aspects.
-    - planets_labels: Dictionary containing the planet labels.
+    - celestial_point_language: Dictionary containing the celestial point language data.
     - aspects_settings: Dictionary containing the aspect settings.
+    - aspects_per_column: Number of aspects to display per column (default: 14).
+    - column_width: Width in pixels for each column (default: 100).
+    - line_height: Height in pixels for each line (default: 14).
+    - max_columns: Maximum number of columns before vertical adjustment (default: 6).
+    - chart_height: Total chart height. When provided, columns from the 12th onward
+      leverage the taller layout capacity (default: None).
 
     Returns:
     - A string containing the SVG path data for the aspect transit grid.
     """
-    
+
     if isinstance(celestial_point_language, dict):
         celestial_point_language = KerykeionLanguageCelestialPointModel(**celestial_point_language)
 
-    if isinstance(aspects_settings, dict):
-        aspects_settings = KerykeionSettingsAspectModel(**aspects_settings)
-
     # If not instance of AspectModel, convert to AspectModel
-    if isinstance(aspects_list[0], dict):
-        aspects_list = [AspectModel(**aspect) for aspect in aspects_list] # type: ignore
+    if aspects_list and isinstance(aspects_list[0], dict):
+        aspects_list = [AspectModel(**aspect) for aspect in aspects_list]  # type: ignore
+
+    # Type narrowing: at this point aspects_list contains AspectModel instances
+    typed_aspects_list: list[AspectModel] = aspects_list  # type: ignore
+
+    translate_x = 565
+    translate_y = 273
+    title_clearance = 18
+    top_limit_y: float = -translate_y + title_clearance
+    bottom_padding = 40
+    baseline_index = aspects_per_column - 1
+    top_limit_index = math.ceil(top_limit_y / line_height)
+    # `top_limit_index` identifies the highest row index we can reach without
+    # touching the title block. Combined with the baseline index we know how many
+    # rows a "tall" column may contain.
+    max_capacity_by_top = baseline_index - top_limit_index + 1
 
-    line = 0
-    nl = 0
     inner_path = ""
-    scale = 1
-    for i, aspect in enumerate(aspects_list):
-        # Adjust the vertical position for every 12 aspects
-        if i == 12:
-            nl = 100
-            line = 0
-
-        elif i == 24:
-            nl = 200
-            line = 0
-
-        elif i == 36:
-            nl = 300
-            line = 0
-
-        elif i == 48:
-            nl = 400
-            # When there are more than 60 aspects, the text is moved up
-            if len(aspects_list) > 60:
-                line = -1 * (len(aspects_list) - 60) * 14
-            else:
-                line = 0
-
-        inner_path += f'<g transform="translate({nl},{line})">'
-
-        # first planet symbol
-        inner_path += f'<use transform="scale(0.4)" x="0" y="3" xlink:href="#{celestial_point_language[aspects_list[i]["p1"]]["name"]}" />'
-
-        # aspect symbol
-        inner_path += f'<use  x="15" y="0" xlink:href="#orb{aspects_settings[aspects_list[i]["aid"]]["degree"]}" />'
-
-        # second planet symbol
-        inner_path += f'<g transform="translate(30,0)">'
-        inner_path += f'<use transform="scale(0.4)" x="0" y="3" xlink:href="#{celestial_point_language[aspects_list[i]["p2"]]["name"]}" />'
-        inner_path += f"</g>"
-
-        # difference in degrees
-        inner_path += f'<text y="8" x="45" style="fill: var(--kerykeion-chart-color-paper-0); font-size: 10px;">{convert_decimal_to_degree_string(aspects_list[i]["orbit"])}</text>'
-        # line
-        inner_path += f"</g>"
-        line = line + 14
-
-    out = f'<g style="transform: translate(47%, 59%) scale({scale})">'
+
+    full_height_column_index = 10  # 0-based index → 11th column onward
+    if chart_height is not None:
+        available_height = max(chart_height - translate_y - bottom_padding, line_height)
+        allowed_capacity = max(aspects_per_column, int(available_height // line_height))
+        full_height_capacity = max(aspects_per_column, min(allowed_capacity, max_capacity_by_top))
+    else:
+        full_height_capacity = aspects_per_column
+
+    # Bucket aspects into columns while respecting the capacity of each column.
+    columns: list[list[AspectModel]] = []
+    column_capacities: list[int] = []
+
+    for aspect in typed_aspects_list:
+        if not columns or len(columns[-1]) >= column_capacities[-1]:
+            new_col_index = len(columns)
+            capacity = aspects_per_column if new_col_index < full_height_column_index else full_height_capacity
+            capacity = max(capacity, 1)
+            columns.append([])
+            column_capacities.append(capacity)
+        columns[-1].append(aspect)
+
+    for col_idx, column in enumerate(columns):
+        capacity = column_capacities[col_idx]
+        horizontal_position = col_idx * column_width
+        column_len = len(column)
+
+        for row_idx, aspect in enumerate(column):
+            # Default top-aligned placement
+            vertical_position = row_idx * line_height
+
+            # Full-height columns reuse the shared baseline so every column
+            # finishes at the same vertical position and grows upwards.
+            if col_idx >= full_height_column_index:
+                vertical_index = baseline_index - (column_len - 1 - row_idx)
+                vertical_position = vertical_index * line_height
+            # Legacy overflow columns (before the 12th) keep the older behaviour:
+            # once we exceed the configured column count, bottom-align the content
+            # so the shorter columns do not look awkwardly padded at the top.
+            elif col_idx >= max_columns and capacity == aspects_per_column:
+                top_offset_lines = max(0, capacity - len(column))
+                vertical_position = (top_offset_lines + row_idx) * line_height
+
+            inner_path += f'<g transform="translate({horizontal_position},{vertical_position})">'
+
+            # First planet symbol
+            inner_path += f'<use transform="scale(0.4)" x="0" y="3" xlink:href="#{celestial_point_language[aspect["p1"]]["name"]}" />'
+
+            # Aspect symbol
+            aspect_name = aspect["aspect"]
+            id_value = next((a["degree"] for a in aspects_settings if a["name"] == aspect_name), None)  # type: ignore
+            inner_path += f'<use x="15" y="0" xlink:href="#orb{id_value}" />'
+
+            # Second planet symbol
+            inner_path += '<g transform="translate(30,0)">'
+            inner_path += f'<use transform="scale(0.4)" x="0" y="3" xlink:href="#{celestial_point_language[aspect["p2"]]["name"]}" />'
+            inner_path += "</g>"
+
+            # Difference in degrees
+            inner_path += f'<text y="8" x="45" style="fill: var(--kerykeion-chart-color-paper-0); font-size: 10px;">{convert_decimal_to_degree_string(aspect["orbit"])}</text>'
+
+            inner_path += "</g>"
+
+    out = f'<g transform="translate({translate_x},{translate_y})">'
     out += f'<text y="-15" x="0" style="fill: var(--kerykeion-chart-color-paper-0); font-size: 14px;">{grid_title}:</text>'
     out += inner_path
     out += "</g>"
@@ -769,105 +1022,59 @@ def draw_transit_aspect_list(
     return out
 
 
-def draw_moon_phase(
-    degrees_between_sun_and_moon: float,
-    latitude: float
-) -> str:
+def calculate_moon_phase_chart_params(
+    degrees_between_sun_and_moon: float
+) -> dict:
     """
-    Draws the moon phase based on the degrees between the sun and the moon.
+    Calculate normalized parameters used by the moon phase icon.
 
     Parameters:
-    - degrees_between_sun_and_moon (float): The degrees between the sun and the moon.
-    - latitude (float): The latitude for rotation calculation.
-    - lunar_phase_outline_color (str): The color for the lunar phase outline.
-    - dark_color (str): The color for the dark part of the moon.
-    - light_color (str): The color for the light part of the moon.
+    - degrees_between_sun_and_moon (float): The elongation between the sun and moon.
 
     Returns:
-    - str: The SVG element as a string.
+    - dict: Normalized phase data (angle, illuminated fraction, shadow ellipse radius).
     """
-    deg = degrees_between_sun_and_moon
-
-    # Initialize variables for lunar phase properties
-    circle_center_x = None
-    circle_radius = None
-
-    # Determine lunar phase properties based on the degree
-    if deg < 90.0:
-        max_radius = deg
-        if deg > 80.0:
-            max_radius = max_radius * max_radius
-        circle_center_x = 20.0 + (deg / 90.0) * (max_radius + 10.0)
-        circle_radius = 10.0 + (deg / 90.0) * max_radius
-
-    elif deg < 180.0:
-        max_radius = 180.0 - deg
-        if deg < 100.0:
-            max_radius = max_radius * max_radius
-        circle_center_x = 20.0 + ((deg - 90.0) / 90.0 * (max_radius + 10.0)) - (max_radius + 10.0)
-        circle_radius = 10.0 + max_radius - ((deg - 90.0) / 90.0 * max_radius)
-
-    elif deg < 270.0:
-        max_radius = deg - 180.0
-        if deg > 260.0:
-            max_radius = max_radius * max_radius
-        circle_center_x = 20.0 + ((deg - 180.0) / 90.0 * (max_radius + 10.0))
-        circle_radius = 10.0 + ((deg - 180.0) / 90.0 * max_radius)
-
-    elif deg < 361.0:
-        max_radius = 360.0 - deg
-        if deg < 280.0:
-            max_radius = max_radius * max_radius
-        circle_center_x = 20.0 + ((deg - 270.0) / 90.0 * (max_radius + 10.0)) - (max_radius + 10.0)
-        circle_radius = 10.0 + max_radius - ((deg - 270.0) / 90.0 * max_radius)
-
-    else:
-        raise KerykeionException(f"Invalid degree value: {deg}")
+    if not math.isfinite(degrees_between_sun_and_moon):
+        raise KerykeionException(
+            f"Invalid degree value: {degrees_between_sun_and_moon}"
+        )
 
+    phase_angle = degrees_between_sun_and_moon % 360.0
+    radians = math.radians(phase_angle)
+    cosine = math.cos(radians)
+    illuminated_fraction = (1.0 - cosine) / 2.0
 
-    # Calculate rotation based on latitude
-    lunar_phase_rotate = -90.0 - latitude
+    # Guard against floating point spillover outside [0, 1].
+    illuminated_fraction = max(0.0, min(1.0, illuminated_fraction))
 
-    # Return the SVG element as a string
-    return (
-        f'<g transform="rotate({lunar_phase_rotate} 20 10)">'
-        f'    <defs>'
-        f'        <clipPath id="moonPhaseCutOffCircle">'
-        f'        <circle cx="20" cy="10" r="10" />'
-        f'        </clipPath>'
-        f'    </defs>'
-        f'    <circle cx="20" cy="10" r="10" style="fill: var(--kerykeion-chart-color-lunar-phase-0)" />'
-        f'    <circle cx="{circle_center_x}" cy="10" r="{circle_radius}" style="fill: var(--kerykeion-chart-color-lunar-phase-1)" clip-path="url(#moonPhaseCutOffCircle)" />'
-        f'    <circle cx="20" cy="10" r="10" style="fill: none; stroke: var(--kerykeion-chart-color-lunar-phase-0); stroke-width: 0.5px; stroke-opacity: 0.5" />'
-        f'</g>'
-    )
+    return {
+        "phase_angle": phase_angle,
+        "illuminated_fraction": illuminated_fraction,
+        "shadow_ellipse_rx": 10.0 * cosine,
+    }
 
 
-def draw_house_grid(
+def draw_main_house_grid(
         main_subject_houses_list: list[KerykeionPointModel],
-        chart_type: ChartType,
-        secondary_subject_houses_list: Union[list[KerykeionPointModel], None] = None,
-        text_color: str = "#000000",
         house_cusp_generale_name_label: str = "Cusp",
+        text_color: str = "#000000",
+        x_position: int = 750,
+        y_position: int = 30,
     ) -> str:
     """
-    Generate SVG code for a grid of astrological houses.
+    Generate SVG code for a grid of astrological houses for the main subject.
 
     Parameters:
-    - main_houses (list[KerykeionPointModel]): List of houses for the main subject.
-    - chart_type (ChartType): Type of the chart (e.g., Synastry, Transit).
-    - secondary_houses (list[KerykeionPointModel], optional): List of houses for the secondary subject.
-    - text_color (str): Color of the text.
-    - cusp_label (str): Label for the house cusp.
+    - main_subject_houses_list (list[KerykeionPointModel]): List of houses for the main subject.
+    - house_cusp_generale_name_label (str): Label for the house cusp. Defaults to "Cusp".
+    - text_color (str): Color of the text. Defaults to "#000000".
+    - x_position (int): X position for the grid. Defaults to 720.
+    - y_position (int): Y position for the grid. Defaults to 30.
 
     Returns:
     - str: The SVG code for the grid of houses.
     """
-    
-    if chart_type in ["Synastry", "Transit"] and secondary_subject_houses_list is None:
-        raise KerykeionException("secondary_houses is None")
-
-    svg_output = '<g transform="translate(610,-20)">'
+    svg_output = f'<g transform="translate({x_position},{y_position})">'
 
     line_increment = 10
     for i, house in enumerate(main_subject_houses_list):
@@ -882,75 +1089,108 @@ def draw_house_grid(
         line_increment += 14
 
     svg_output += "</g>"
+    return svg_output
 
-    if chart_type == "Synastry":
-        svg_output += '<!-- Synastry Houses -->'
-        svg_output += '<g transform="translate(850, -20)">'
-        line_increment = 10
-
-        for i, house in enumerate(secondary_subject_houses_list): # type: ignore
-            cusp_number = f"&#160;&#160;{i + 1}" if i < 9 else str(i + 1)
-            svg_output += (
-                f'<g transform="translate(0,{line_increment})">'
-                f'<text text-anchor="end" x="40" style="fill:{text_color}; font-size: 10px;">{house_cusp_generale_name_label} {cusp_number}:</text>'
-                f'<g transform="translate(40,-8)"><use transform="scale(0.3)" xlink:href="#{house["sign"]}" /></g>'
-                f'<text x="53" style="fill:{text_color}; font-size: 10px;"> {convert_decimal_to_degree_string(house["position"])}</text>'
-                f'</g>'
-            )
-            line_increment += 14
 
-        svg_output += "</g>"
+def draw_secondary_house_grid(
+        secondary_subject_houses_list: list[KerykeionPointModel],
+        house_cusp_generale_name_label: str = "Cusp",
+        text_color: str = "#000000",
+        x_position: int = 1015,
+        y_position: int = 30,
+    ) -> str:
+    """
+    Generate SVG code for a grid of astrological houses for the secondary subject.
+
+    Parameters:
+    - secondary_subject_houses_list (list[KerykeionPointModel]): List of houses for the secondary subject.
+    - house_cusp_generale_name_label (str): Label for the house cusp. Defaults to "Cusp".
+    - text_color (str): Color of the text. Defaults to "#000000".
+    - x_position (int): X position for the grid. Defaults to 970.
+    - y_position (int): Y position for the grid. Defaults to 30.
+
+    Returns:
+    - str: The SVG code for the grid of houses.
+    """
+    svg_output = f'<g transform="translate({x_position},{y_position})">'
+
+    line_increment = 10
+    for i, house in enumerate(secondary_subject_houses_list):
+        cusp_number = f"&#160;&#160;{i + 1}" if i < 9 else str(i + 1)
+        svg_output += (
+            f'<g transform="translate(0,{line_increment})">'
+            f'<text text-anchor="end" x="40" style="fill:{text_color}; font-size: 10px;">{house_cusp_generale_name_label} {cusp_number}:</text>'
+            f'<g transform="translate(40,-8)"><use transform="scale(0.3)" xlink:href="#{house["sign"]}" /></g>'
+            f'<text x="53" style="fill:{text_color}; font-size: 10px;"> {convert_decimal_to_degree_string(house["position"])}</text>'
+            f'</g>'
+        )
+        line_increment += 14
 
+    svg_output += "</g>"
     return svg_output
 
 
-def draw_planet_grid(
+def draw_main_planet_grid(
         planets_and_houses_grid_title: str,
         subject_name: str,
         available_kerykeion_celestial_points: list[KerykeionPointModel],
         chart_type: ChartType,
         celestial_point_language: KerykeionLanguageCelestialPointModel,
-        second_subject_name: Union[str, None] = None,
-        second_subject_available_kerykeion_celestial_points: Union[list[KerykeionPointModel], None] = None,
         text_color: str = "#000000",
+        x_position: int = 645,
+        y_position: int = 0,
     ) -> str:
     """
-    Draws the planet grid for the given celestial points and chart type.
+    Draw the planet grid (main subject) and optional title.
+
+    The entire output is wrapped in a single SVG group `<g>` so the
+    whole block can be repositioned by changing the group transform.
 
     Args:
-        planets_and_houses_grid_title (str): Title of the grid.
-        subject_name (str): Name of the subject.
-        available_kerykeion_celestial_points (list[KerykeionPointModel]): List of celestial points for the subject.
-        chart_type (ChartType): Type of the chart.
-        celestial_point_language (KerykeionLanguageCelestialPointModel): Language model for celestial points.
-        second_subject_name (str, optional): Name of the second subject. Defaults to None.
-        second_subject_available_kerykeion_celestial_points (list[KerykeionPointModel], optional): List of celestial points for the second subject. Defaults to None.
-        text_color (str, optional): Color of the text. Defaults to "#000000".
+        planets_and_houses_grid_title: Title prefix to show for eligible chart types.
+        subject_name: Subject name to append to the title.
+        available_kerykeion_celestial_points: Celestial points to render in the grid.
+        chart_type: Chart type identifier (Literal string).
+        celestial_point_language: Language model for celestial point decoding.
+        text_color: Text color for labels (default: "#000000").
+        x_position: X translation applied to the outer `<g>` (default: 620).
+        y_position: Y translation applied to the outer `<g>` (default: 0).
 
     Returns:
-        str: The SVG output for the planet grid.
+        SVG string for the main planet grid wrapped in a `<g>`.
     """
-    line_height = 10
-    offset = 0
-    offset_between_lines = 14
+    # Layout constants (kept identical to previous behavior)
+    BASE_Y = 30
+    HEADER_Y = 15  # Title baseline inside the wrapper
+    LINE_START = 10
+    LINE_STEP = 14
 
-    svg_output = (
-        f'<g transform="translate(510,-20)">'
-        f'<g transform="translate(140, -15)">'
-        f'<text text-anchor="end" style="fill:{text_color}; font-size: 14px;">{planets_and_houses_grid_title} {subject_name}:</text>'
-        f'</g>'
-    )
+    # Wrap everything inside a single group so position can be changed once
+    svg_output = f'<g transform="translate({x_position},{y_position})">'
+
+    # Add title only for specific chart types
+    if chart_type in ("Synastry", "Transit", "DualReturnChart"):
+        svg_output += (
+            f'<g transform="translate(0, {HEADER_Y})">'
+            f'<text style="fill:{text_color}; font-size: 14px;">{planets_and_houses_grid_title} {subject_name}</text>'
+            f'</g>'
+        )
 
     end_of_line = "</g>"
 
+    column_thresholds = _select_planet_grid_thresholds(chart_type)
+
     for i, planet in enumerate(available_kerykeion_celestial_points):
-        if i == 27:
-            line_height = 10
-            offset = -120
+        offset, row_index = _planet_grid_layout_position(i, column_thresholds)
+        line_height = LINE_START + (row_index * LINE_STEP)
+
+        decoded_name = get_decoded_kerykeion_celestial_point_name(
+            planet["name"],
+            celestial_point_language,
+        )
 
-        decoded_name = get_decoded_kerykeion_celestial_point_name(planet["name"], celestial_point_language)
         svg_output += (
-            f'<g transform="translate({offset},{line_height})">'
+            f'<g transform="translate({offset},{BASE_Y + line_height})">'
             f'<text text-anchor="end" style="fill:{text_color}; font-size: 10px;">{decoded_name}</text>'
             f'<g transform="translate(5,-8)"><use transform="scale(0.4)" xlink:href="#{planet["name"]}" /></g>'
             f'<text text-anchor="start" x="19" style="fill:{text_color}; font-size: 10px;">{convert_decimal_to_degree_string(planet["position"])}</text>'
@@ -961,55 +1201,101 @@ def draw_planet_grid(
             svg_output += '<g transform="translate(74,-6)"><use transform="scale(.5)" xlink:href="#retrograde" /></g>'
 
         svg_output += end_of_line
-        line_height += offset_between_lines
 
-    if chart_type in ["Transit", "Synastry"]:
-        if second_subject_available_kerykeion_celestial_points is None:
-            raise KerykeionException("second_subject_available_kerykeion_celestial_points is None")
+    # Close the wrapper group
+    svg_output += "</g>"
 
-        if chart_type == "Transit":
-            svg_output += (
-                f'<g transform="translate(320, -15)">'
-                f'<text text-anchor="end" style="fill:{text_color}; font-size: 14px;">{second_subject_name}:</text>'
-            )
-        else:
-            svg_output += (
-                f'<g transform="translate(380, -15)">'
-                f'<text text-anchor="end" style="fill:{text_color}; font-size: 14px;">{planets_and_houses_grid_title} {second_subject_name}:</text>'
-            )
+    return svg_output
 
-        svg_output += end_of_line
 
-        second_line_height = 10
-        second_offset = 250
-
-        for i, t_planet in enumerate(second_subject_available_kerykeion_celestial_points):
-            if i == 27:
-                second_line_height = 10
-                second_offset = -120
-
-            second_decoded_name = get_decoded_kerykeion_celestial_point_name(t_planet["name"], celestial_point_language)
-            svg_output += (
-                f'<g transform="translate({second_offset},{second_line_height})">'
-                f'<text text-anchor="end" style="fill:{text_color}; font-size: 10px;">{second_decoded_name}</text>'
-                f'<g transform="translate(5,-8)"><use transform="scale(0.4)" xlink:href="#{t_planet["name"]}" /></g>'
-                f'<text text-anchor="start" x="19" style="fill:{text_color}; font-size: 10px;">{convert_decimal_to_degree_string(t_planet["position"])}</text>'
-                f'<g transform="translate(60,-8)"><use transform="scale(0.3)" xlink:href="#{t_planet["sign"]}" /></g>'
-            )
+def draw_secondary_planet_grid(
+        planets_and_houses_grid_title: str,
+        second_subject_name: str,
+        second_subject_available_kerykeion_celestial_points: list[KerykeionPointModel],
+        chart_type: ChartType,
+        celestial_point_language: KerykeionLanguageCelestialPointModel,
+        text_color: str = "#000000",
+        x_position: int = 910,
+        y_position: int = 0,
+    ) -> str:
+    """
+    Draw the planet grid for the secondary subject and its title.
+
+    The entire output is wrapped in a single SVG group `<g>` so the
+    whole block can be repositioned by changing the group transform.
+
+    Args:
+        planets_and_houses_grid_title: Title prefix (used except for Transit charts).
+        second_subject_name: Name of the secondary subject.
+        second_subject_available_kerykeion_celestial_points: Celestial points to render for the secondary subject.
+        chart_type: Chart type identifier (Literal string).
+        celestial_point_language: Language model for celestial point decoding.
+        text_color: Text color for labels (default: "#000000").
+        x_position: X translation applied to the outer `<g>` (default: 870).
+        y_position: Y translation applied to the outer `<g>` (default: 0).
+
+    Returns:
+        SVG string for the secondary planet grid wrapped in a `<g>`.
+    """
+    # Layout constants
+    BASE_Y = 30
+    HEADER_Y = 15
+    LINE_START = 10
+    LINE_STEP = 14
+
+    # Open wrapper group
+    svg_output = f'<g transform="translate({x_position},{y_position})">'
+
+    # Title content and its relative x offset
+    header_text = (
+        second_subject_name if chart_type == "Transit"
+        else f"{planets_and_houses_grid_title} {second_subject_name}"
+    )
+    header_x_offset = -50 if chart_type == "Transit" else 0
+
+    svg_output += (
+        f'<g transform="translate({header_x_offset}, {HEADER_Y})">'
+        f'<text style="fill:{text_color}; font-size: 14px;">{header_text}</text>'
+        f'</g>'
+    )
+
+    # Grid rows
+    line_height = LINE_START
+    end_of_line = "</g>"
+
+    column_thresholds = _select_planet_grid_thresholds(chart_type)
+
+    for i, t_planet in enumerate(second_subject_available_kerykeion_celestial_points):
+        offset, row_index = _planet_grid_layout_position(i, column_thresholds)
+        line_height = LINE_START + (row_index * LINE_STEP)
+
+        second_decoded_name = get_decoded_kerykeion_celestial_point_name(
+            t_planet["name"],
+            celestial_point_language,
+        )
+        svg_output += (
+            f'<g transform="translate({offset},{BASE_Y + line_height})">'
+            f'<text text-anchor="end" style="fill:{text_color}; font-size: 10px;">{second_decoded_name}</text>'
+            f'<g transform="translate(5,-8)"><use transform="scale(0.4)" xlink:href="#{t_planet["name"]}" /></g>'
+            f'<text text-anchor="start" x="19" style="fill:{text_color}; font-size: 10px;">{convert_decimal_to_degree_string(t_planet["position"])}</text>'
+            f'<g transform="translate(60,-8)"><use transform="scale(0.3)" xlink:href="#{t_planet["sign"]}" /></g>'
+        )
+
+        if t_planet["retrograde"]:
+            svg_output += '<g transform="translate(74,-6)"><use transform="scale(.5)" xlink:href="#retrograde" /></g>'
+
+        svg_output += end_of_line
 
-            if t_planet["retrograde"]:
-                svg_output += '<g transform="translate(74,-6)"><use transform="scale(.5)" xlink:href="#retrograde" /></g>'
 
-            svg_output += end_of_line
-            second_line_height += offset_between_lines
+    # Close wrapper group
+    svg_output += "</g>"
 
-    svg_output += end_of_line
     return svg_output
 
 
 def draw_transit_aspect_grid(
-        stroke_color: str, 
-        available_planets: list, 
+        stroke_color: str,
+        available_planets: list,
         aspects: list,
         x_indent: int = 50,
         y_indent: int = 250,
@@ -1030,12 +1316,12 @@ def draw_transit_aspect_grid(
         str: SVG string representing the aspect grid.
     """
     svg_output = ""
-    style = f"stroke:{stroke_color}; stroke-width: 1px; fill:none"
+    style = f"stroke:{stroke_color}; stroke-width: 1px; stroke-width: 0.5px; fill:none"
     x_start = x_indent
     y_start = y_indent
 
     # Filter active planets
-    active_planets = [planet for planet in available_planets if planet.is_active]
+    active_planets = [planet for planet in available_planets if planet["is_active"]]
 
     # Reverse the list of active planets for the first iteration
     reversed_planets = active_planets[::-1]
@@ -1080,4 +1366,475 @@ def draw_transit_aspect_grid(
                 if (aspect["p1"] == planet_a["id"] and aspect["p2"] == planet_b["id"]):
                     svg_output += f'<use  x="{x_aspect - box_size + 1}" y="{y_aspect + 1}" xlink:href="#orb{aspect["aspect_degrees"]}" />'
 
-    return svg_output
+    return svg_output
+
+
+def format_location_string(location: str, max_length: int = 35) -> str:
+    """
+    Format a location string to ensure it fits within a specified maximum length.
+
+    If the location is longer than max_length, it attempts to shorten by using only
+    the first and last parts separated by commas. If still too long, it truncates
+    and adds ellipsis.
+
+    Args:
+        location: The original location string
+        max_length: Maximum allowed length for the output string (default: 35)
+
+    Returns:
+        Formatted location string that fits within max_length
+    """
+    if len(location) > max_length:
+        split_location = location.split(",")
+        if len(split_location) > 1:
+            shortened = split_location[0] + ", " + split_location[-1]
+            if len(shortened) > max_length:
+                return shortened[:max_length] + "..."
+            return shortened
+        else:
+            return location[:max_length] + "..."
+    return location
+
+
+def format_datetime_with_timezone(iso_datetime_string: str) -> str:
+    """
+    Format an ISO datetime string with a custom format that includes properly formatted timezone.
+
+    Args:
+        iso_datetime_string: ISO formatted datetime string
+
+    Returns:
+        Formatted datetime string with properly formatted timezone offset (HH:MM)
+    """
+    dt = datetime.datetime.fromisoformat(iso_datetime_string)
+    custom_format = dt.strftime('%Y-%m-%d %H:%M [%z]')
+    custom_format = custom_format[:-3] + ':' + custom_format[-3:]
+
+    return custom_format
+
+
+def calculate_element_points(
+    planets_settings: Sequence[KerykeionSettingsCelestialPointModel],
+    celestial_points_names: Sequence[str],
+    subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
+    *,
+    method: ElementQualityDistributionMethod = "weighted",
+    custom_weights: Optional[Mapping[str, float]] = None,
+) -> dict[str, float]:
+    """
+    Calculate elemental totals for a subject using the selected strategy.
+
+    Args:
+        planets_settings: Planet configuration list (kept for API compatibility).
+        celestial_points_names: Celestial point names to include.
+        subject: Astrological subject with planetary data.
+        method: Calculation method (pure_count or weighted). Defaults to weighted.
+        custom_weights: Optional overrides for point weights keyed by name.
+
+    Returns:
+        Dictionary mapping each element to its accumulated total.
+    """
+    normalized_names = [name.lower() for name in celestial_points_names]
+    weight_lookup, fallback_weight = _prepare_weight_lookup(method, custom_weights)
+
+    return _calculate_distribution_for_subject(
+        subject,
+        normalized_names,
+        _SIGN_TO_ELEMENT,
+        _ELEMENT_KEYS,
+        weight_lookup,
+        fallback_weight,
+    )
+
+
+def calculate_synastry_element_points(
+    planets_settings: Sequence[KerykeionSettingsCelestialPointModel],
+    celestial_points_names: Sequence[str],
+    subject1: AstrologicalSubjectModel,
+    subject2: AstrologicalSubjectModel,
+    *,
+    method: ElementQualityDistributionMethod = "weighted",
+    custom_weights: Optional[Mapping[str, float]] = None,
+) -> dict[str, float]:
+    """
+    Calculate combined element percentages for a synastry chart.
+
+    Args:
+        planets_settings: Planet configuration list (unused but preserved).
+        celestial_points_names: Celestial point names to process.
+        subject1: First astrological subject.
+        subject2: Second astrological subject.
+        method: Calculation strategy (pure_count or weighted).
+        custom_weights: Optional overrides for point weights.
+
+    Returns:
+        Dictionary with element percentages summing to 100.
+    """
+    normalized_names = [name.lower() for name in celestial_points_names]
+    weight_lookup, fallback_weight = _prepare_weight_lookup(method, custom_weights)
+
+    subject1_totals = _calculate_distribution_for_subject(
+        subject1,
+        normalized_names,
+        _SIGN_TO_ELEMENT,
+        _ELEMENT_KEYS,
+        weight_lookup,
+        fallback_weight,
+    )
+    subject2_totals = _calculate_distribution_for_subject(
+        subject2,
+        normalized_names,
+        _SIGN_TO_ELEMENT,
+        _ELEMENT_KEYS,
+        weight_lookup,
+        fallback_weight,
+    )
+
+    combined_totals = {key: subject1_totals[key] + subject2_totals[key] for key in _ELEMENT_KEYS}
+    total_points = sum(combined_totals.values())
+
+    if total_points == 0:
+        return {key: 0.0 for key in _ELEMENT_KEYS}
+
+    return {key: (combined_totals[key] / total_points) * 100.0 for key in _ELEMENT_KEYS}
+
+
+def draw_house_comparison_grid(
+        house_comparison: "HouseComparisonModel",
+        celestial_point_language: KerykeionLanguageCelestialPointModel,
+        active_points: list[AstrologicalPoint],
+        *,
+        points_owner_subject_number: Literal[1, 2] = 1,
+        text_color: str = "var(--kerykeion-color-neutral-content)",
+        house_position_comparison_label: str = "House Position Comparison",
+        return_point_label: str = "Return Point",
+        return_label: str = "DualReturnChart",
+        radix_label: str = "Radix",
+        x_position: int = 1100,
+        y_position: int = 0,
+) -> str:
+    """
+    Generate SVG code for displaying a comparison of points across houses between two charts.
+
+    Parameters:
+    - house_comparison ("HouseComparisonModel"): Model containing house comparison data,
+      including first_subject_name, second_subject_name, and points in houses.
+    - celestial_point_language (KerykeionLanguageCelestialPointModel): Language model for celestial points
+    - active_celestial_points (list[KerykeionPointModel]): List of active celestial points to display
+    - text_color (str): Color for the text elements
+
+    Returns:
+    - str: SVG code for the house comparison grid.
+    """
+    if points_owner_subject_number == 1:
+        comparison_data = house_comparison.first_points_in_second_houses
+    else:
+        comparison_data = house_comparison.second_points_in_first_houses
+
+    svg_output = f'<g transform="translate({x_position},{y_position})">'
+
+    # Add title
+    svg_output += f'<text text-anchor="start" x="0" y="-15" style="fill:{text_color}; font-size: 14px;">{house_position_comparison_label}</text>'
+
+    # Add column headers
+    line_increment = 10
+    svg_output += (
+        f'<g transform="translate(0,{line_increment})">'
+        f'<text text-anchor="start" x="0" style="fill:{text_color}; font-weight: bold; font-size: 10px;">{return_point_label}</text>'
+        f'<text text-anchor="start" x="77" style="fill:{text_color}; font-weight: bold; font-size: 10px;">{return_label}</text>'
+        f'<text text-anchor="start" x="132" style="fill:{text_color}; font-weight: bold; font-size: 10px;">{radix_label}</text>'
+        f'</g>'
+    )
+    line_increment += 15
+
+    # Create a dictionary to store all points by name for combined display
+    all_points_by_name = {}
+
+    for point in comparison_data:
+        # Only process points that are active
+        if point.point_name in active_points and point.point_name not in all_points_by_name:
+            all_points_by_name[point.point_name] = {
+                "name": point.point_name,
+                "secondary_house": point.projected_house_number,
+                "native_house": point.point_owner_house_number
+            }
+
+    # Display all points organized by name
+    for name, point_data in all_points_by_name.items():
+        native_house = point_data.get("native_house", "-")
+        secondary_house = point_data.get("secondary_house", "-")
+
+        svg_output += (
+            f'<g transform="translate(0,{line_increment})">'
+            f'<g transform="translate(0,-9)"><use transform="scale(0.4)" xlink:href="#{name}" /></g>'
+            f'<text text-anchor="start" x="15" style="fill:{text_color}; font-size: 10px;">{get_decoded_kerykeion_celestial_point_name(name, celestial_point_language)}</text>'
+            f'<text text-anchor="start" x="90" style="fill:{text_color}; font-size: 10px;">{native_house}</text>'
+            f'<text text-anchor="start" x="140" style="fill:{text_color}; font-size: 10px;">{secondary_house}</text>'
+            f'</g>'
+        )
+        line_increment += 12
+
+    svg_output += "</g>"
+
+    return svg_output
+
+
+def draw_single_house_comparison_grid(
+        house_comparison: "HouseComparisonModel",
+        celestial_point_language: KerykeionLanguageCelestialPointModel,
+        active_points: list[AstrologicalPoint],
+        *,
+        points_owner_subject_number: Literal[1, 2] = 1,
+        text_color: str = "var(--kerykeion-color-neutral-content)",
+        house_position_comparison_label: str = "House Position Comparison",
+        return_point_label: str = "Return Point",
+        natal_house_label: str = "Natal House",
+        x_position: int = 1030,
+        y_position: int = 0,
+) -> str:
+    """
+    Generate SVG code for displaying celestial points and their house positions.
+
+    Parameters:
+    - house_comparison ("HouseComparisonModel"): Model containing house comparison data,
+      including first_subject_name, second_subject_name, and points in houses.
+    - celestial_point_language (KerykeionLanguageCelestialPointModel): Language model for celestial points
+    - active_points (list[AstrologicalPoint]): List of active celestial points to display
+    - points_owner_subject_number (Literal[1, 2]): Which subject's points to display (1 for first, 2 for second)
+    - text_color (str): Color for the text elements
+    - house_position_comparison_label (str): Label for the house position comparison grid
+    - return_point_label (str): Label for the return point column
+    - house_position_label (str): Label for the house position column
+    - x_position (int): X position for the grid
+    - y_position (int): Y position for the grid
+
+    Returns:
+    - str: SVG code for the house position grid.
+    """
+    if points_owner_subject_number == 1:
+        comparison_data = house_comparison.first_points_in_second_houses
+    else:
+        comparison_data = house_comparison.second_points_in_first_houses
+
+    svg_output = f'<g transform="translate({x_position},{y_position})">'
+
+    # Add title
+    svg_output += f'<text text-anchor="start" x="0" y="-15" style="fill:{text_color}; font-size: 14px;">{house_position_comparison_label}</text>'
+
+    # Add column headers
+    line_increment = 10
+    svg_output += (
+        f'<g transform="translate(0,{line_increment})">'
+        f'<text text-anchor="start" x="0" style="fill:{text_color}; font-weight: bold; font-size: 10px;">{return_point_label}</text>'
+        f'<text text-anchor="start" x="77" style="fill:{text_color}; font-weight: bold; font-size: 10px;">{natal_house_label}</text>'
+        f'</g>'
+    )
+    line_increment += 15
+
+    # Create a dictionary to store all points by name for combined display
+    all_points_by_name = {}
+
+    for point in comparison_data:
+        # Only process points that are active
+        if point.point_name in active_points and point.point_name not in all_points_by_name:
+            all_points_by_name[point.point_name] = {
+                "name": point.point_name,
+                "house": point.projected_house_number
+            }
+
+    # Display all points organized by name
+    for name, point_data in all_points_by_name.items():
+        house = point_data.get("house", "-")
+
+        svg_output += (
+            f'<g transform="translate(0,{line_increment})">'
+            f'<g transform="translate(0,-9)"><use transform="scale(0.4)" xlink:href="#{name}" /></g>'
+            f'<text text-anchor="start" x="15" style="fill:{text_color}; font-size: 10px;">{get_decoded_kerykeion_celestial_point_name(name, celestial_point_language)}</text>'
+            f'<text text-anchor="start" x="90" style="fill:{text_color}; font-size: 10px;">{house}</text>'
+            f'</g>'
+        )
+        line_increment += 12
+
+    svg_output += "</g>"
+
+    return svg_output
+
+
+def makeLunarPhase(degrees_between_sun_and_moon: float, latitude: float) -> str:
+    """
+    Generate SVG representation of lunar phase.
+
+    Parameters:
+    - degrees_between_sun_and_moon (float): Angle between sun and moon in degrees
+    - latitude (float): Observer's latitude (no longer used, kept for backward compatibility)
+
+    Returns:
+    - str: SVG representation of lunar phase
+    """
+    params = calculate_moon_phase_chart_params(degrees_between_sun_and_moon)
+
+    phase_angle = params["phase_angle"]
+    illuminated_fraction = 1.0 - params["illuminated_fraction"]
+    shadow_ellipse_rx = abs(params["shadow_ellipse_rx"])
+
+    radius = 10.0
+    center_x = 20.0
+    center_y = 10.0
+
+    bright_color = "var(--kerykeion-chart-color-lunar-phase-1)"
+    shadow_color = "var(--kerykeion-chart-color-lunar-phase-0)"
+
+    is_waxing = phase_angle < 180.0
+
+    if illuminated_fraction <= 1e-6:
+        base_fill = shadow_color
+        overlay_path = ""
+        overlay_fill = ""
+    elif 1.0 - illuminated_fraction <= 1e-6:
+        base_fill = bright_color
+        overlay_path = ""
+        overlay_fill = ""
+    else:
+        is_lit_major = illuminated_fraction >= 0.5
+        if is_lit_major:
+            base_fill = bright_color
+            overlay_fill = shadow_color
+            overlay_side = "left" if is_waxing else "right"
+        else:
+            base_fill = shadow_color
+            overlay_fill = bright_color
+            overlay_side = "right" if is_waxing else "left"
+
+        # The illuminated limb is the orthographic projection of the lunar terminator;
+        # it appears as an ellipse with vertical radius equal to the lunar radius and
+        # horizontal radius scaled by |cos(phase)|.
+        def build_lune_path(side: str, ellipse_rx: float) -> str:
+            ellipse_rx = max(0.0, min(radius, ellipse_rx))
+            top_y = center_y - radius
+            bottom_y = center_y + radius
+            circle_sweep = 1 if side == "right" else 0
+
+            if ellipse_rx <= 1e-6:
+                return (
+                    f"M {center_x:.4f} {top_y:.4f}"
+                    f" A {radius:.4f} {radius:.4f} 0 0 {circle_sweep} {center_x:.4f} {bottom_y:.4f}"
+                    f" L {center_x:.4f} {top_y:.4f}"
+                    " Z"
+                )
+
+            return (
+                f"M {center_x:.4f} {top_y:.4f}"
+                f" A {radius:.4f} {radius:.4f} 0 0 {circle_sweep} {center_x:.4f} {bottom_y:.4f}"
+                f" A {ellipse_rx:.4f} {radius:.4f} 0 0 {circle_sweep} {center_x:.4f} {top_y:.4f}"
+                " Z"
+            )
+
+        overlay_path = build_lune_path(overlay_side, shadow_ellipse_rx)
+
+    svg_lines = [
+        '<g transform="rotate(0 20 10)">',
+        '    <defs>',
+        '        <clipPath id="moonPhaseCutOffCircle">',
+        '            <circle cx="20" cy="10" r="10" />',
+        '        </clipPath>',
+        '    </defs>',
+        f'    <circle cx="20" cy="10" r="10" style="fill: {base_fill}" />',
+    ]
+
+    if overlay_path:
+        svg_lines.append(
+            f'    <path d="{overlay_path}" style="fill: {overlay_fill}" clip-path="url(#moonPhaseCutOffCircle)" />'
+        )
+
+    svg_lines.append(
+        '    <circle cx="20" cy="10" r="10" style="fill: none; stroke: var(--kerykeion-chart-color-lunar-phase-0); stroke-width: 0.5px; stroke-opacity: 0.5" />'
+    )
+    svg_lines.append('</g>')
+
+    return "\n".join(svg_lines)
+
+
+def calculate_quality_points(
+    planets_settings: Sequence[KerykeionSettingsCelestialPointModel],
+    celestial_points_names: Sequence[str],
+    subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
+    *,
+    method: ElementQualityDistributionMethod = "weighted",
+    custom_weights: Optional[Mapping[str, float]] = None,
+) -> dict[str, float]:
+    """
+    Calculate modality totals for a subject using the selected strategy.
+
+    Args:
+        planets_settings: Planet configuration list (kept for API compatibility).
+        celestial_points_names: Celestial point names to include.
+        subject: Astrological subject with planetary data.
+        method: Calculation method (pure_count or weighted). Defaults to weighted.
+        custom_weights: Optional overrides for point weights keyed by name.
+
+    Returns:
+        Dictionary mapping each modality to its accumulated total.
+    """
+    normalized_names = [name.lower() for name in celestial_points_names]
+    weight_lookup, fallback_weight = _prepare_weight_lookup(method, custom_weights)
+
+    return _calculate_distribution_for_subject(
+        subject,
+        normalized_names,
+        _SIGN_TO_QUALITY,
+        _QUALITY_KEYS,
+        weight_lookup,
+        fallback_weight,
+    )
+
+
+def calculate_synastry_quality_points(
+    planets_settings: Sequence[KerykeionSettingsCelestialPointModel],
+    celestial_points_names: Sequence[str],
+    subject1: AstrologicalSubjectModel,
+    subject2: AstrologicalSubjectModel,
+    *,
+    method: ElementQualityDistributionMethod = "weighted",
+    custom_weights: Optional[Mapping[str, float]] = None,
+) -> dict[str, float]:
+    """
+    Calculate combined modality percentages for a synastry chart.
+
+    Args:
+        planets_settings: Planet configuration list (unused but preserved).
+        celestial_points_names: Celestial point names to process.
+        subject1: First astrological subject.
+        subject2: Second astrological subject.
+        method: Calculation strategy (pure_count or weighted).
+        custom_weights: Optional overrides for point weights.
+
+    Returns:
+        Dictionary with modality percentages summing to 100.
+    """
+    normalized_names = [name.lower() for name in celestial_points_names]
+    weight_lookup, fallback_weight = _prepare_weight_lookup(method, custom_weights)
+
+    subject1_totals = _calculate_distribution_for_subject(
+        subject1,
+        normalized_names,
+        _SIGN_TO_QUALITY,
+        _QUALITY_KEYS,
+        weight_lookup,
+        fallback_weight,
+    )
+    subject2_totals = _calculate_distribution_for_subject(
+        subject2,
+        normalized_names,
+        _SIGN_TO_QUALITY,
+        _QUALITY_KEYS,
+        weight_lookup,
+        fallback_weight,
+    )
+
+    combined_totals = {key: subject1_totals[key] + subject2_totals[key] for key in _QUALITY_KEYS}
+    total_points = sum(combined_totals.values())
+
+    if total_points == 0:
+        return {key: 0.0 for key in _QUALITY_KEYS}
+
+    return {key: (combined_totals[key] / total_points) * 100.0 for key in _QUALITY_KEYS}