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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions