<img width="1917" height="1048" alt="readme_image" src="https://github.com/user-attachments/assets/6551f222-4274-4db3-a9e6-33ced04cc32b" />

ChartForgeTK

A powerful and intuitive Python charting library built purely on Tkinter. ChartForgeTK brings modern, interactive data visualization to desktop applications with zero external dependencies.

---

Table of Contents

• Why ChartForgeTK?
• Features
• Installation
• Quick Start
• Chart Types
• Pandas Integration
• API Reference
• Utility Classes
• Customization
• Stability & Reliability
• Examples
• Roadmap
• Contributing
• License

---

🚀 Why ChartForgeTK?

| Feature | ChartForgeTK | |---------|--------------| | Dependencies | Zero external dependencies - pure Tkinter | | Chart Types | 12+ chart types for any visualization need | | Customization | Light/Dark themes, flexible sizing | | Interactivity | Tooltips, hover effects, click events | | Data Sources | Lists, pandas DataFrames, pandas Series | | Performance | Lightweight, fast rendering with animations | | Stability | Comprehensive input validation (v2.0) |

---

✨ Features

Chart Types

| Chart | Description | Best For | |-------|-------------|----------| | Bar Chart | Vertical bars with animations | Categorical comparisons | | Line Chart | Multi-series with markers | Trends, time-series | | Pie Chart | 2D/3D with slice selection | Proportions | | Scatter Plot | X-Y coordinate plotting | Correlations | | Bubble Chart | Scatter with size encoding | 3-variable data | | Box Plot | Statistical distribution | Outlier detection | | Histogram | Frequency distribution | Data distribution | | Gantt Chart | Timeline visualization | Project planning | | Candlestick | OHLC financial data | Stock analysis | | Heat Map | Color-coded matrices | Pattern recognition | | Network Graph | Node-edge visualization | Relationships | | Tableau Chart | Enhanced data tables | Tabular display |

Interactive Features

• Animated chart rendering with smooth transitions
• Hover tooltips with detailed information
• Click-to-select functionality (pie charts)
• Dynamic data refresh without flickering
• Responsive layouts with auto-resize support

Pandas Integration (New!)

import pandas as pd
from ChartForgeTK import BarChart

df = pd.DataFrame({
    'quarter': ['Q1', 'Q2', 'Q3', 'Q4'],
    'sales': [150, 200, 175, 225]
})

chart = BarChart(root, width=600, height=400)
chart.plot(df, value_column='sales', label_column='quarter')

---

📦 Installation

pip install ChartForgeTK

Requirements

• Python 3.8+
• Tkinter (included with Python)
• Optional: pandas (for DataFrame support)

---

🚀 Quick Start

import tkinter as tk
from ChartForgeTK import BarChart

# Create window
root = tk.Tk()
root.title("My First Chart")
root.geometry("800x600")

# Create chart
chart = BarChart(root, width=780, height=520)
chart.pack(fill="both", expand=True)

# Plot data
chart.plot(
    data=[10, 20, 15, 25, 30],
    labels=["Q1", "Q2", "Q3", "Q4", "Q5"]
)

root.mainloop()

---

📊 Chart Types

Bar Chart

from ChartForgeTK import BarChart

chart = BarChart(parent, width=600, height=400, theme='light')
chart.plot([10, 20, 15, 25], ["A", "B", "C", "D"])

Line Chart

from ChartForgeTK import LineChart

# Single series
chart = LineChart(parent, width=600, height=400)
chart.plot([10, 15, 13, 18, 16, 20])

# Multiple series
chart.plot([
    {'data': [10, 15, 13, 18], 'color': '#FF0000', 'label': 'Series A'},
    {'data': [5, 8, 12, 10], 'color': '#00FF00', 'label': 'Series B'}
])

Pie Chart

from ChartForgeTK import PieChart

# 2D Pie Chart
chart = PieChart(parent, width=600, height=400)
chart.plot([30, 20, 15, 35], ["A", "B", "C", "D"])

# 3D Pie Chart
chart_3d = PieChart(parent, width=600, height=400, is_3d=True)
chart_3d.plot([30, 20, 15, 35], ["A", "B", "C", "D"])

Scatter Plot

from ChartForgeTK import ScatterPlot

chart = ScatterPlot(parent, width=600, height=400)
chart.plot([(1, 10), (2, 15), (3, 13), (4, 18), (5, 16)])

Box Plot

from ChartForgeTK import BoxPlot

data = [
    [1, 2, 3, 4, 5, 6, 7],
    [2, 4, 6, 8, 10, 12, 14],
    [1, 3, 5, 7, 9, 11, 20]
]
chart = BoxPlot(parent, width=600, height=400)
chart.plot(data, ["Group A", "Group B", "Group C"])

Histogram

from ChartForgeTK import Histogram

data = [1, 1.5, 2, 2, 2.5, 3, 3, 3.5, 4, 4.5, 5]
chart = Histogram(parent, width=600, height=400)
chart.plot(data, bins=5)

Candlestick Chart

from ChartForgeTK import CandlestickChart

# Format: (index, open, high, low, close)
data = [
    (1, 100, 105, 98, 103),
    (2, 103, 108, 101, 106),
    (3, 106, 110, 104, 108)
]
chart = CandlestickChart(parent, width=600, height=400)
chart.plot(data)

---

🐼 Pandas Integration

ChartForgeTK seamlessly integrates with pandas DataFrames and Series.

DataFrame with BarChart

import pandas as pd
from ChartForgeTK import BarChart

df = pd.DataFrame({
    'category': ['Q1', 'Q2', 'Q3', 'Q4'],
    'sales': [150, 200, 175, 225]
})

chart = BarChart(parent, width=600, height=400)
chart.plot(df, value_column='sales', label_column='category')

Series with PieChart

import pandas as pd
from ChartForgeTK import PieChart

series = pd.Series(
    [30, 25, 20, 15, 10],
    index=['Product A', 'Product B', 'Product C', 'Product D', 'Product E']
)

chart = PieChart(parent, width=600, height=400)
chart.plot(series)  # Index becomes labels automatically

Multi-Series LineChart from DataFrame

import pandas as pd
from ChartForgeTK import LineChart

df = pd.DataFrame({
    'month': ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    'revenue': [100, 120, 115, 130, 145],
    'expenses': [80, 85, 90, 95, 100],
    'profit': [20, 35, 25, 35, 45]
})

chart = LineChart(parent, width=600, height=400)
chart.plot(df, y_columns=['revenue', 'expenses', 'profit'], label_column='month')

ScatterPlot from DataFrame

import pandas as pd
from ChartForgeTK import ScatterPlot

df = pd.DataFrame({
    'height': [160, 165, 170, 175, 180],
    'weight': [55, 60, 65, 70, 75]
})

chart = ScatterPlot(parent, width=600, height=400)
chart.plot(df, x_column='height', y_column='weight')

---

📖 API Reference

Common Parameters

All chart constructors accept these parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | parent | Widget | None | Parent Tkinter widget | | width | int | 800 | Chart width in pixels | | height | int | 600 | Chart height in pixels | | theme | str | 'light' | Color theme ('light' or 'dark') | | display_mode | str | 'frame' | Display mode |

BarChart.plot()

chart.plot(
    data,                    # List[float] or DataFrame
    labels=None,             # Optional[List[str]]
    value_column=None,       # Column name for DataFrame
    label_column=None        # Column name for DataFrame labels
)

LineChart.plot()

chart.plot(
    data,                    # List[float], List[Dict], or DataFrame
    x_min=None,              # Optional axis limits
    x_max=None,
    y_min=None,
    y_max=None,
    y_columns=None,          # List of column names for multi-series
    label_column=None        # Column name for x-axis labels
)

PieChart.plot()

chart.plot(
    data,                    # List[float], Series, or DataFrame
    labels=None,             # Optional[List[str]]
    value_column=None,       # Column name for DataFrame
    label_column=None        # Column name for DataFrame labels
)

---

🔧 Utility Classes

DataValidator

Validate chart inputs before plotting:

from ChartForgeTK import DataValidator

# Validate numeric data
data = DataValidator.validate_numeric_list([1, 2, 3, 4, 5])

# Validate dimensions
width, height = DataValidator.validate_dimensions(800, 600)

# Validate colors
color = DataValidator.validate_color("#FF5733")

# Validate labels
labels = DataValidator.validate_labels(["A", "B", "C"], expected_length=3)

ResourceManager

Manage chart resources for proper cleanup:

from ChartForgeTK import ResourceManager

# ResourceManager is automatically used by charts
# Access it for manual resource management
chart.resource_manager.cancel_animations()
chart.resource_manager.cleanup_tooltips()
chart.resource_manager.cleanup()

CoordinateTransformer

Handle coordinate transformations:

from ChartForgeTK import CoordinateTransformer

transformer = CoordinateTransformer(width=400, height=300, padding=40)
x_min, x_max, y_min, y_max = transformer.calculate_ranges(0, 100, 0, 50)

# Convert data coordinates to pixel coordinates
pixel_x = transformer.data_to_pixel_x(50)
pixel_y = transformer.data_to_pixel_y(25)

---

🎨 Customization

Themes

# Light theme (default)
chart = BarChart(parent, theme='light')

# Dark theme
chart = BarChart(parent, theme='dark')

Line Chart Options

chart = LineChart(
    parent,
    width=800,
    height=600,
    show_point_labels=True,           # Show/hi