stt/pybind/__init__.py

"""
STT Python Binding
==================

A Python interface for the Spherical Triangular Tessellation (STT) generator.

This module provides access to the C++ STT library for generating spherical 
triangular tessellations on various reference systems.

Basic Usage:
------------
>>> import stt
>>> generator = stt.SttGenerator()
>>> generator.set_tree_depth(3, 8)
>>> generator.set_reference_system("WGS84")
>>> generator.run("output.msh")

Quick Creation:
--------------
>>> import stt
>>> info = stt.create_stt(3, 8, "WGS84", "output.msh")
>>> print(info)

Progress Callback (for Jupyter notebooks):
-----------------------------------------
>>> import stt
>>> def my_progress(description, percentage):
...     print(f"{description}: {percentage:.1f}%")
...
>>> generator = stt.SttGenerator()
>>> generator.set_progress_callback(my_progress)
>>> generator.run("output.msh")

Advanced Usage:
--------------
>>> import stt
>>> generator = stt.SttGenerator()
>>> params = {
...     "output_msh": "output.msh",
...     "output_vertex": "vertices.txt",
...     "control_points": "points.txt",
...     "topography": "topo.txt"
... }
>>> generator.run_full(params)
"""

from .stt import (
    SttGenerator,
    create_stt,
    WGS84,
    EARTH,
    MOON,
    __version__
)

__all__ = [
    'SttGenerator',
    'create_stt',
    'WGS84',
    'EARTH',
    'MOON',
    '__version__',
    'get_info',
    'help'
]

# 模块信息
__author__ = 'STT Development Team'
__email__ = 'yizhang-geo@zju.edu.cn'
__license__ = 'MIT'
__url__ = 'https://github.com/your-repo/stt'

def get_info():
    """获取STT模块信息"""
    return {
        'version': __version__,
        'author': __author__,
        'email': __email__,
        'license': __license__,
        'url': __url__
    }

def help():
    """显示帮助信息"""
    print(__doc__)

# Jupyter notebook进度条支持
try:
    # 尝试导入tqdm用于更好的进度条支持
    from tqdm import tqdm
    HAS_TQDM = True
    
    class TqdmProgressCallback:
        """使用tqdm的进度回调"""
        def __init__(self, description="Progress"):
            self.pbar = tqdm(total=100, desc=description)
            self.current_description = description
        
        def __call__(self, description, percentage):
            if description != self.current_description:
                self.pbar.set_description(description)
                self.current_description = description
            self.pbar.n = int(percentage)
            self.pbar.refresh()
            if percentage >= 100:
                self.pbar.close()
        
        def close(self):
            if self.pbar:
                self.pbar.close()
    
    def create_tqdm_callback(description="STT Progress"):
        """创建tqdm进度回调"""
        return TqdmProgressCallback(description)
    
    __all__.extend(['TqdmProgressCallback', 'create_tqdm_callback'])
    
except ImportError:
    HAS_TQDM = False
    
    class SimpleProgressCallback:
        """简单的文本进度回调"""
        def __init__(self, description="Progress"):
            self.current_description = description
            self.last_percentage = -1
        
        def __call__(self, description, percentage):
            if description != self.current_description:
                print(f"\n{description}:")
                self.current_description = description
            if int(percentage) != int(self.last_percentage):
                print(f"  {percentage:.1f}%", end='\r')
                self.last_percentage = percentage
            if percentage >= 100:
                print("  100.0%")
    
    def create_simple_callback(description="STT Progress"):
        """创建简单进度回调"""
        return SimpleProgressCallback(description)
    
    __all__.extend(['SimpleProgressCallback', 'create_simple_callback'])

# 自动选择最佳的进度回调
def create_progress_callback(description="STT Progress", use_tqdm=None):
    """
    创建适合的进度回调函数
    
    参数:
        description: 进度条描述
        use_tqdm: 是否强制使用tqdm，None表示自动选择
    
    返回:
        进度回调函数
    """
    if use_tqdm is None:
        use_tqdm = HAS_TQDM
    
    if use_tqdm and HAS_TQDM:
        return create_tqdm_callback(description)
    else:
        return create_simple_callback(description)