kerykeion 5.0.0a9__py3-none-any.whl → 5.1.8__py3-none-any.whl

kerykeion/charts/charts_utils.py

@@ -1,11 +1,229 @@
 import math
 import datetime
-from kerykeion.kr_types import KerykeionException, ChartType
-from kerykeion.kr_types.kr_literals import AstrologicalPoint
-from typing import Union, Literal, TYPE_CHECKING
-from kerykeion.kr_types.kr_models import AspectModel, KerykeionPointModel, CompositeSubjectModel, PlanetReturnModel, AstrologicalSubjectModel
-from kerykeion.kr_types.settings_models import KerykeionLanguageCelestialPointModel, KerykeionSettingsCelestialPointModel
-from kerykeion.house_comparison import HouseComparisonModel
+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
 
 
 
@@ -189,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" or chart_type == "Return":
+    if chart_type == "Transit" or chart_type == "Synastry" or chart_type == "DualReturnChart":
         dropin: Union[int, float] = 0
     else:
         dropin = c1
@@ -198,7 +416,7 @@ def draw_zodiac_slice(
     # symbols
     offset = offset + 15
     # check transit
-    if chart_type == "Transit" or chart_type == "Synastry" or chart_type == "Return":
+    if chart_type == "Transit" or chart_type == "Synastry" or chart_type == "DualReturnChart":
         dropin = 54
     else:
         dropin = 18 + c1
@@ -287,7 +505,7 @@ 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>"
     )
@@ -419,7 +637,7 @@ def draw_first_circle(
     Returns:
         str: The SVG path of the first circle.
     """
-    if chart_type == "Synastry" or chart_type == "Transit" or chart_type == "Return":
+    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:
@@ -462,7 +680,7 @@ def draw_second_circle(
         str: The SVG path of the second circle.
     """
 
-    if chart_type == "Synastry" or chart_type == "Transit" or chart_type == "Return":
+    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:
@@ -492,7 +710,7 @@ def draw_third_circle(
     Returns:
     - str: The SVG element as a string.
     """
-    if chart_type in {"Synastry", "Transit", "Return"}:
+    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" />'
 
@@ -572,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.
@@ -589,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 = ""
@@ -599,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", "Return"] 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)
@@ -621,7 +841,7 @@ def draw_houses_cusps_and_text_number(
             i, standard_house_cusp_color
         )
 
-        if chart_type in ["Transit", "Synastry", "Return"]:
+        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")
 
@@ -645,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, "Return": 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
 
@@ -682,7 +906,8 @@ def draw_transit_aspect_list(
     aspects_per_column: int = 14,
     column_width: int = 100,
     line_height: int = 14,
-    max_columns: int = 6
+    max_columns: int = 6,
+    chart_height: Optional[int] = None,
 ) -> str:
     """
     Generates the SVG output for the aspect transit grid.
@@ -696,6 +921,8 @@ def draw_transit_aspect_list(
     - 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.
@@ -708,115 +935,122 @@ def draw_transit_aspect_list(
     if aspects_list and isinstance(aspects_list[0], dict):
         aspects_list = [AspectModel(**aspect) for aspect in aspects_list]  # type: ignore
 
-    inner_path = ""
-
-    for i, aspect in enumerate(aspects_list):
-        # Calculate which column this aspect belongs in
-        current_column = i // aspects_per_column
-
-        # Calculate horizontal position based on column
-        horizontal_position = current_column * column_width
-
-        # Calculate vertical position within the column
-        current_line = i % aspects_per_column
-        vertical_position = current_line * line_height
-
-        # Special handling for many aspects - if we exceed max_columns
-        if current_column >= max_columns:
-            # Calculate how many aspects will overflow beyond the max columns
-            overflow_aspects = len(aspects_list) - (aspects_per_column * max_columns)
-            if overflow_aspects > 0:
-                # Adjust the starting vertical position to move text up
-                vertical_position = vertical_position - (overflow_aspects * 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"]}" />'
+    # 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
 
-        # 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 += f'<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 += 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(aspect["orbit"])}</text>'
-
-        inner_path += f"</g>"
+    inner_path = ""
 
-    out = '<g transform="translate(565,273)">'
+    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>'
+    out += "</g>"
 
     return out
 
 
 def calculate_moon_phase_chart_params(
-    degrees_between_sun_and_moon: float,
-    latitude: float
+    degrees_between_sun_and_moon: float
 ) -> dict:
     """
-    Calculate the parameters for the moon phase chart.
+    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.
+    - degrees_between_sun_and_moon (float): The elongation between the sun and moon.
 
     Returns:
-    - dict: The moon phase chart parameters.
-    """
-    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}")
+    - dict: Normalized phase data (angle, illuminated fraction, shadow ellipse radius).
+    """
+    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 {
-        "circle_center_x": circle_center_x,
-        "circle_radius": circle_radius,
-        "lunar_phase_rotate": lunar_phase_rotate,
+        "phase_angle": phase_angle,
+        "illuminated_fraction": illuminated_fraction,
+        "shadow_ellipse_rx": 10.0 * cosine,
     }
 
 
@@ -824,7 +1058,7 @@ def draw_main_house_grid(
         main_subject_houses_list: list[KerykeionPointModel],
         house_cusp_generale_name_label: str = "Cusp",
         text_color: str = "#000000",
-        x_position: int = 720,
+        x_position: int = 750,
         y_position: int = 30,
     ) -> str:
     """
@@ -862,7 +1096,7 @@ 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 = 970,
+        x_position: int = 1015,
         y_position: int = 30,
     ) -> str:
     """
@@ -903,57 +1137,60 @@ def draw_main_planet_grid(
         chart_type: ChartType,
         celestial_point_language: KerykeionLanguageCelestialPointModel,
         text_color: str = "#000000",
+        x_position: int = 645,
+        y_position: int = 0,
     ) -> str:
     """
-    Draws the planet grid for the main subject.
+    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.
-        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 main planet grid.
+        SVG string for the main planet grid wrapped in a `<g>`.
     """
-    line_height = 10
-    offset = 0
-    offset_between_lines = 14
-    svg_output = ""
+    # Layout constants (kept identical to previous behavior)
+    BASE_Y = 30
+    HEADER_Y = 15  # Title baseline inside the wrapper
+    LINE_START = 10
+    LINE_STEP = 14
 
-    if chart_type == "Synastry":
-        svg_output += (
-            f'<g transform="translate(620, 15)">'  # Added the 620,30 offset (adjusted for -15)
-            f'<text style="fill:{text_color}; font-size: 14px;">{planets_and_houses_grid_title} {subject_name}</text>'
-            f'</g>'
-        )
-    elif chart_type == "Transit":
-        svg_output += (
-            f'<g transform="translate(620, 15)">'  # Added the 620,30 offset (adjusted for -15)
-            f'<text style="fill:{text_color}; font-size: 14px;">{planets_and_houses_grid_title} {subject_name}</text>'
-            f'</g>'
-        )
-    elif chart_type == "Return":
+    # 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(620, 15)">'  # Added the 620,30 offset (adjusted for -15)
+            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>'
         )
-    else:
-        svg_output += ""
 
     end_of_line = "</g>"
 
+    column_thresholds = _select_planet_grid_thresholds(chart_type)
+
     for i, planet in enumerate(available_kerykeion_celestial_points):
-        if i == 22:
-            line_height = 10
-            offset = -125
+        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({620 + offset},{30 + line_height})">'  # Added the 620,30 offset
+            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>'
@@ -964,7 +1201,9 @@ def draw_main_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
+
+    # Close the wrapper group
+    svg_output += "</g>"
 
     return svg_output
 
@@ -976,49 +1215,66 @@ def draw_secondary_planet_grid(
         chart_type: ChartType,
         celestial_point_language: KerykeionLanguageCelestialPointModel,
         text_color: str = "#000000",
+        x_position: int = 910,
+        y_position: int = 0,
     ) -> str:
     """
-    Draws the planet grid for the secondary subject in Transit, Synastry, or Return charts.
+    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 (str): Title of the grid.
-        second_subject_name (str): Name of the second subject.
-        second_subject_available_kerykeion_celestial_points (list[KerykeionPointModel]): List of celestial points for the second subject.
-        chart_type (ChartType): Type of the chart.
-        celestial_point_language (KerykeionLanguageCelestialPointModel): Language model for celestial points.
-        text_color (str, optional): Color of the text. Defaults to "#000000".
+        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:
-        str: The SVG output for the secondary planet grid.
+        SVG string for the secondary planet grid wrapped in a `<g>`.
     """
-    svg_output = ""
-    end_of_line = "</g>"
+    # Layout constants
+    BASE_Y = 30
+    HEADER_Y = 15
+    LINE_START = 10
+    LINE_STEP = 14
 
-    if chart_type == "Transit":
-        svg_output += (
-            f'<g transform="translate(820, 15)">'  # 620+200, 30-15
-            f'<text style="fill:{text_color}; font-size: 14px;">{second_subject_name}</text>'
-        )
-    elif chart_type == "Return":
-        svg_output += (
-            f'<g transform="translate(870, 15)">'  # 620+250, 30-15
-            f'<text style="fill:{text_color}; font-size: 14px;">{planets_and_houses_grid_title} {second_subject_name}</text>'
-        )
-    else:
-        svg_output += (
-            f'<g transform="translate(870, 15)">'  # 620+250, 30-15
-            f'<text style="fill:{text_color}; font-size: 14px;">{planets_and_houses_grid_title} {second_subject_name}</text>'
-        )
+    # 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>'
+    )
 
-    svg_output += end_of_line
+    # Grid rows
+    line_height = LINE_START
+    end_of_line = "</g>"
 
-    line_height = 10
-    offset = 250
+    column_thresholds = _select_planet_grid_thresholds(chart_type)
 
     for i, t_planet in enumerate(second_subject_available_kerykeion_celestial_points):
-        second_decoded_name = get_decoded_kerykeion_celestial_point_name(t_planet["name"], celestial_point_language)
+        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({620 + offset},{30 + line_height})">'  # Added the 620,30 offset
+            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>'
@@ -1029,7 +1285,10 @@ def draw_secondary_planet_grid(
             svg_output += '<g transform="translate(74,-6)"><use transform="scale(.5)" xlink:href="#retrograde" /></g>'
 
         svg_output += end_of_line
-        line_height += 14  # Using fixed offset_between_lines value
+
+
+    # Close wrapper group
+    svg_output += "</g>"
 
     return svg_output
 
@@ -1155,121 +1414,89 @@ def format_datetime_with_timezone(iso_datetime_string: str) -> str:
 
 
 def calculate_element_points(
-        planets_settings: list[KerykeionSettingsCelestialPointModel],
-        celestial_points_names: list[str],
-        subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
-    ):
+    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 point totals based on planetary positions.
+    Calculate elemental totals for a subject using the selected strategy.
 
     Args:
-        planets_settings (list): List of planet configuration dictionaries
-        celestial_points_names (list): List of celestial point names to process
-        subject: Astrological subject with get() method for accessing planet data
+        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:
-        dict: Dictionary with element point totals for 'fire', 'earth', 'air', and 'water'
-    """
-    ZODIAC = (
-        {"name": "Ari", "element": "fire"},
-        {"name": "Tau", "element": "earth"},
-        {"name": "Gem", "element": "air"},
-        {"name": "Can", "element": "water"},
-        {"name": "Leo", "element": "fire"},
-        {"name": "Vir", "element": "earth"},
-        {"name": "Lib", "element": "air"},
-        {"name": "Sco", "element": "water"},
-        {"name": "Sag", "element": "fire"},
-        {"name": "Cap", "element": "earth"},
-        {"name": "Aqu", "element": "air"},
-        {"name": "Pis", "element": "water"},
+        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,
     )
 
-    # Initialize element point totals
-    element_totals = {
-        "fire": 0.0,
-        "earth": 0.0,
-        "air": 0.0,
-        "water": 0.0
-    }
-
-    # Make list of the points sign
-    points_sign = [subject.get(planet).sign_num for planet in celestial_points_names]
-
-    for i in range(len(planets_settings)):
-        # Add points to appropriate element
-        element = ZODIAC[points_sign[i]]["element"]
-        element_totals[element] += planets_settings[i]["element_points"]
-
-    return element_totals
-
 
 def calculate_synastry_element_points(
-        planets_settings: list[KerykeionSettingsCelestialPointModel],
-        celestial_points_names: list[str],
-        subject1: AstrologicalSubjectModel,
-        subject2: AstrologicalSubjectModel,
-    ):
+    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 elemental point totals for both subjects in a synastry chart.
+    Calculate combined element percentages for a synastry chart.
 
     Args:
-        planets_settings (list): List of planet configuration dictionaries
-        celestial_points_names (list): List of celestial point names to process
-        subject1: First astrological subject with get() method for accessing planet data
-        subject2: Second astrological subject with get() method for accessing planet data
+        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:
-        dict: Dictionary with element point totals as percentages, where the sum equals 100%
-    """
-    ZODIAC = (
-        {"name": "Ari", "element": "fire"},
-        {"name": "Tau", "element": "earth"},
-        {"name": "Gem", "element": "air"},
-        {"name": "Can", "element": "water"},
-        {"name": "Leo", "element": "fire"},
-        {"name": "Vir", "element": "earth"},
-        {"name": "Lib", "element": "air"},
-        {"name": "Sco", "element": "water"},
-        {"name": "Sag", "element": "fire"},
-        {"name": "Cap", "element": "earth"},
-        {"name": "Aqu", "element": "air"},
-        {"name": "Pis", "element": "water"},
+        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,
     )
 
-    # Initialize combined element point totals
-    combined_totals = {
-        "fire": 0.0,
-        "earth": 0.0,
-        "air": 0.0,
-        "water": 0.0
-    }
-
-    # Make list of the points sign for both subjects
-    subject1_points_sign = [subject1.get(planet).sign_num for planet in celestial_points_names]
-    subject2_points_sign = [subject2.get(planet).sign_num for planet in celestial_points_names]
-
-    # Calculate element points for subject 1
-    for i in range(len(planets_settings)):
-        # Add points to appropriate element
-        element1 = ZODIAC[subject1_points_sign[i]]["element"]
-        combined_totals[element1] += planets_settings[i]["element_points"]
-
-    # Calculate element points for subject 2
-    for i in range(len(planets_settings)):
-        # Add points to appropriate element
-        element2 = ZODIAC[subject2_points_sign[i]]["element"]
-        combined_totals[element2] += planets_settings[i]["element_points"]
-
-    # Calculate total points across all elements
+    combined_totals = {key: subject1_totals[key] + subject2_totals[key] for key in _ELEMENT_KEYS}
     total_points = sum(combined_totals.values())
 
-    # Convert to percentages (total = 100%)
-    if total_points > 0:
-        for element in combined_totals:
-            combined_totals[element] = (combined_totals[element] / total_points) * 100.0
+    if total_points == 0:
+        return {key: 0.0 for key in _ELEMENT_KEYS}
 
-    return combined_totals
+    return {key: (combined_totals[key] / total_points) * 100.0 for key in _ELEMENT_KEYS}
 
 
 def draw_house_comparison_grid(
@@ -1281,9 +1508,9 @@ def draw_house_comparison_grid(
         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 = "Return",
+        return_label: str = "DualReturnChart",
         radix_label: str = "Radix",
-        x_position: int = 1030,
+        x_position: int = 1100,
         y_position: int = 0,
 ) -> str:
     """
@@ -1439,149 +1666,175 @@ def makeLunarPhase(degrees_between_sun_and_moon: float, latitude: float) -> str:
 
     Parameters:
     - degrees_between_sun_and_moon (float): Angle between sun and moon in degrees
-    - latitude (float): Observer's latitude for correct orientation
+    - latitude (float): Observer's latitude (no longer used, kept for backward compatibility)
 
     Returns:
     - str: SVG representation of lunar phase
     """
-    # Calculate parameters for the lunar phase visualization
-    params = calculate_moon_phase_chart_params(degrees_between_sun_and_moon, latitude)
-
-    # Extract the calculated values
-    lunar_phase_circle_center_x = params["circle_center_x"]
-    lunar_phase_circle_radius = params["circle_radius"]
-    lunar_phase_rotate = params["lunar_phase_rotate"]
-
-    # Generate the SVG for the lunar phase
-    svg = (
-        f'<g transform="rotate({lunar_phase_rotate} 20 10)">\n'
-        f'    <defs>\n'
-        f'        <clipPath id="moonPhaseCutOffCircle">\n'
-        f'            <circle cx="20" cy="10" r="10" />\n'
-        f'        </clipPath>\n'
-        f'    </defs>\n'
-        f'    <circle cx="20" cy="10" r="10" style="fill: var(--kerykeion-chart-color-lunar-phase-0)" />\n'
-        f'    <circle cx="{lunar_phase_circle_center_x}" cy="10" r="{lunar_phase_circle_radius}" style="fill: var(--kerykeion-chart-color-lunar-phase-1)" clip-path="url(#moonPhaseCutOffCircle)" />\n'
-        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" />\n'
-        f'</g>'
-    )
+    params = calculate_moon_phase_chart_params(degrees_between_sun_and_moon)
 
-    return svg
+    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
 
-def calculate_quality_points(
-        planets_settings: list[KerykeionSettingsCelestialPointModel],
-        celestial_points_names: list[str],
-        subject: Union[AstrologicalSubjectModel, CompositeSubjectModel, PlanetReturnModel],
-    ):
-    """
-    Calculate quality point totals based on planetary positions.
+    bright_color = "var(--kerykeion-chart-color-lunar-phase-1)"
+    shadow_color = "var(--kerykeion-chart-color-lunar-phase-0)"
 
-    Args:
-        planets_settings (list): List of planet configuration dictionaries
-        celestial_points_names (list): List of celestial point names to process
-        subject: Astrological subject with get() method for accessing planet data
-        planet_in_zodiac_extra_points (int): Extra points awarded for planets in their home sign
+    is_waxing = phase_angle < 180.0
 
-    Returns:
-        dict: Dictionary with quality point totals for 'cardinal', 'fixed', and 'mutable'
-    """
-    ZODIAC = (
-        {"name": "Ari", "quality": "cardinal"},
-        {"name": "Tau", "quality": "fixed"},
-        {"name": "Gem", "quality": "mutable"},
-        {"name": "Can", "quality": "cardinal"},
-        {"name": "Leo", "quality": "fixed"},
-        {"name": "Vir", "quality": "mutable"},
-        {"name": "Lib", "quality": "cardinal"},
-        {"name": "Sco", "quality": "fixed"},
-        {"name": "Sag", "quality": "mutable"},
-        {"name": "Cap", "quality": "cardinal"},
-        {"name": "Aqu", "quality": "fixed"},
-        {"name": "Pis", "quality": "mutable"},
-    )
-
-    # Initialize quality point totals
-    quality_totals = {
-        "cardinal": 0.0,
-        "fixed": 0.0,
-        "mutable": 0.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"
+            )
 
-    # Make list of the points sign
-    points_sign = [subject.get(planet).sign_num for planet in celestial_points_names]
+        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)" />'
+        )
 
-    for i in range(len(planets_settings)):
-        # Add points to appropriate quality
-        quality = ZODIAC[points_sign[i]]["quality"]
-        quality_totals[quality] += planets_settings[i]["element_points"]
+    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 quality_totals
+    return "\n".join(svg_lines)
 
 
-def calculate_synastry_quality_points(
-        planets_settings: list[KerykeionSettingsCelestialPointModel],
-        celestial_points_names: list[str],
-        subject1: AstrologicalSubjectModel,
-        subject2: AstrologicalSubjectModel,
-    ):
+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 quality point totals for both subjects in a synastry chart.
+    Calculate modality totals for a subject using the selected strategy.
 
     Args:
-        planets_settings (list): List of planet configuration dictionaries
-        celestial_points_names (list): List of celestial point names to process
-        subject1: First astrological subject with get() method for accessing planet data
-        subject2: Second astrological subject with get() method for accessing planet data
+        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:
-        dict: Dictionary with quality point totals as percentages, where the sum equals 100%
-    """
-    ZODIAC = (
-        {"name": "Ari", "quality": "cardinal"},
-        {"name": "Tau", "quality": "fixed"},
-        {"name": "Gem", "quality": "mutable"},
-        {"name": "Can", "quality": "cardinal"},
-        {"name": "Leo", "quality": "fixed"},
-        {"name": "Vir", "quality": "mutable"},
-        {"name": "Lib", "quality": "cardinal"},
-        {"name": "Sco", "quality": "fixed"},
-        {"name": "Sag", "quality": "mutable"},
-        {"name": "Cap", "quality": "cardinal"},
-        {"name": "Aqu", "quality": "fixed"},
-        {"name": "Pis", "quality": "mutable"},
+        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,
     )
 
-    # Initialize combined quality point totals
-    combined_totals = {
-        "cardinal": 0.0,
-        "fixed": 0.0,
-        "mutable": 0.0
-    }
 
-    # Make list of the points sign for both subjects
-    subject1_points_sign = [subject1.get(planet).sign_num for planet in celestial_points_names]
-    subject2_points_sign = [subject2.get(planet).sign_num for planet in celestial_points_names]
+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.
 
-    # Calculate quality points for subject 1
-    for i in range(len(planets_settings)):
-        # Add points to appropriate quality
-        quality1 = ZODIAC[subject1_points_sign[i]]["quality"]
-        combined_totals[quality1] += planets_settings[i]["element_points"]
+    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.
 
-    # Calculate quality points for subject 2
-    for i in range(len(planets_settings)):
-        # Add points to appropriate quality
-        quality2 = ZODIAC[subject2_points_sign[i]]["quality"]
-        combined_totals[quality2] += planets_settings[i]["element_points"]
+    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,
+    )
 
-    # Calculate total points across all qualities
+    combined_totals = {key: subject1_totals[key] + subject2_totals[key] for key in _QUALITY_KEYS}
     total_points = sum(combined_totals.values())
 
-    # Convert to percentages (total = 100%)
-    if total_points > 0:
-        for quality in combined_totals:
-            combined_totals[quality] = (combined_totals[quality] / total_points) * 100.0
-
-    return combined_totals
+    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}