Skip to content

Add LaTeX sargam letter properties for better visualization rendering #19

@jon-myers

Description

@jon-myers

Problem

Currently, the Pitch class provides octaved_sargam_letter which uses Unicode combining diacritics (e.g., \u0307 for dot above, \u0323 for dot below). However, these Unicode diacritics often render poorly in visualization libraries like matplotlib:

  • Dots above uppercase letters (Ṡ, Ṙ, Ġ) are barely visible or overlap with the letter
  • Font-dependent rendering inconsistencies
  • Horizontal positioning issues in some rendering contexts

Proposed Solution

Add LaTeX math mode properties to the Pitch class for proper diacritic positioning:

  1. latex_sargam_letter - LaTeX-compatible base sargam letter
  2. latex_octaved_sargam_letter - LaTeX math mode with properly positioned diacritics

Implementation Plan

Add new methods to Pitch class:

def _octave_latex_diacritic(self) -> str:
    """Convert octave to LaTeX math notation for proper diacritic positioning."""
    mapping = {
        -3: r'\underset{\bullet\bullet\bullet}',  # Triple dot below  
        -2: r'\underset{\bullet\bullet}',         # Double dot below
        -1: r'\underset{\bullet}',                # Single dot below
        1: r'\dot',                               # Single dot above
        2: r'\ddot',                              # Double dot above  
        3: r'\dddot'                              # Triple dot above
    }
    return mapping.get(self.oct, '')

@property
def latex_sargam_letter(self) -> str:
    """LaTeX-compatible base sargam letter."""
    return self.sargam_letter

@property  
def latex_octaved_sargam_letter(self) -> str:
    """LaTeX math mode sargam letter with properly positioned diacritics."""
    base_letter = self.sargam_letter
    latex_diacritic = self._octave_latex_diacritic()
    
    if not latex_diacritic:
        return base_letter  # No octave marking
    elif latex_diacritic.startswith(r'\underset'):
        return f'${latex_diacritic}{{\\mathrm{{{base_letter}}}}}$'
    else:
        return f'${latex_diacritic}{{\\mathrm{{{base_letter}}}}}$'

Usage Example:

pitch = Pitch({'swara': 'sa', 'oct': 1})

# Current (problematic in matplotlib):
pitch.octaved_sargam_letter  # Returns "Ṡ" - renders poorly

# Proposed (clean LaTeX):
pitch.latex_octaved_sargam_letter  # Returns "$\dot{\mathrm{S}}$" - renders perfectly

Benefits

  • Perfect rendering in matplotlib and other LaTeX-compatible libraries
  • Consistent cross-platform appearance regardless of font
  • Backward compatibility - all existing properties remain unchanged
  • Easy adoption in visualization projects

Testing Requirements

  • All octave levels (-3 to +3)
  • All sargam letters (S, R, G, M, P, D, N)
  • Both raised/lowered variants
  • Edge cases and boundary conditions

This enhancement would significantly improve the usability of IDTAP for creating high-quality musical visualizations.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions