Of course! Here's a comprehensive guide to using PyChartDirector, a powerful Python wrapper for the ChartDirector charting library.

What is PyChartDirector?

PyChartDirector is a Python extension module that allows you to create high-quality, publication-ready charts and graphs. It's a wrapper around the ChartDirector library, which is written in C++ and known for its performance, flexibility, and wide range of chart types.

It's an excellent choice when you need more control and customization than what libraries like Matplotlib or Plotly offer out-of-the-box, especially for financial charts, scientific plots, or dashboards.

Key Features

• High Performance: Renders charts quickly, even with large datasets.
• Vast Chart Types: Supports common charts (Line, Bar, Pie, Area) and specialized ones (Financial Candlestick, Gantt, Surface, Contour, Polar, etc.).
• High Customization: You have fine-grained control over almost every visual aspect: colors, fonts, line styles, data labels, legends, and axes.
• Image Formats: Can output charts as common image formats (PNG, JPG, GIF, SVG, PDF, BMP) or directly as binary data for web applications.
• Server-Side Rendering: Perfect for generating charts in web frameworks like Flask or Django.

Installation

First, you need to install the PyChartDirector package using pip.

pip install pychartdir

This will automatically download and install the necessary C++ library components.

Basic Usage: A Step-by-Step Example

Let's create a simple line chart. The core idea is to create a Chart object and then add various elements (like a title, plot area, data, axes, and a legend) to it.

# Import the necessary modules
from pychartdir import *
# 1. Prepare the data
# For a line chart, we need x-axis data and y-axis data
data = [10, 13, 18, 25, 33, 40, 45, 50, 58, 63, 68, 73]
labels = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
# 2. Create a Chart object (400px wide, 300px high)
c = Chart(400, 300)
# 3. Add a title to the chart"Monthly Sales Performance 2025")
# 4. Add a plot area and set its background color
# The plot area is where the actual chart is drawn
c.setPlotArea(50, 60, 300, 200).setBackground(0xf0f0f0, 0xd0d0d0, 0x888888)
# 5. Add a line layer to the chart
# A layer can contain one or more data series
layer = c.addLineLayer(data, "blue")
# 6. Set the data labels on the data points
layer.setDataLabelStyle()
# 7. Set the x-axis labels
c.xAxis().setLabels(labels)
# 8. Add a chart legend
c.addLegend(50, 20)
# 9. Output the chart as a PNG file
c.makeChart("line_chart.png")
print("Chart saved to line_chart.png")

When you run this script, a file named line_chart.png will be created in your current directory. It will look something like this:

Deeper Dive: Common Chart Types and Customization

Let's explore other chart types and how to customize them.

Bar Chart

Creating a bar chart is very similar. We just use addBarLayer().

from pychartdir import *
# Data
data = [25, 38, 20, 45, 30]
labels = ["Product A", "Product B", "Product C", "Product D", "Product E"]
# Create chart
c = Chart(500, 300)"Quarterly Sales by Product")
c.setPlotArea(70, 60, 380, 180)
# Add a bar layer
layer = c.addBarLayer(data, [0x55aa55, 0xff6600, 0xff00ff, 0x00bbee, 0xffaa00])
# Set labels
c.xAxis().setLabels(labels)
c.xAxis().setLabelsRotation(45) # Rotate labels for better readability
# Output
c.makeChart("bar_chart.png")

Pie Chart

Pie charts use addPieLayer().

from pychartdir import *
# Data and labels
data = [25, 18, 15, 22, 20]
labels = ["North", "South", "East", "West", "Central"]
colors = [0xff0000, 0x00ff00, 0x0000ff, 0xffff00, 0xff00ff]
# Create chart
c = Chart(400, 300)"Market Share Distribution")
# Add a pie layer
layer = c.addPieLayer(data, colors)
layer.setLabels(labels)
# Add a legend
c.addLegend(120, 100)
# Output
c.makeChart("pie_chart.png")

Financial (Candlestick) Chart

This is a specialty chart where ChartDirector really shines.

from pychartdir import *
# OHLC data (Open, High, Low, Close)
# Each inner list represents one day's data
ohlcData = [
    [100, 110, 95, 105],
    [105, 112, 100, 108],
    [108, 115, 105, 112],
    [112, 120, 110, 118],
    [118, 125, 115, 122]
]
# Create a finance chart object
c = FinanceChart(600, 400)"Daily Stock Price")
# Add the main chart area (for candlesticks)
mainChart = c.addMainChart(10, 60, 580, 300)
# Add the data series
c.addCandlestickLayer(ohlcData, 0x00ff00, 0xff0000) # Green for up, red for down
# Add a volume chart at the bottom
c.addVolumeBarLayer([100, 120, 110, 130, 125], 0x99ccff, 0x6666ff)
# Add a moving average line
c.addMovingAverageLayer(ohlcData, 0xff0000, 3) # 3-day moving average
# Add title and axis labels
c.yAxis().setTitle("Price (USD)")
c.xAxis().setTitle("Trading Days")
# Output
c.makeChart("financial_chart.png")

Integration with Web Frameworks (Flask Example)

A common use case is generating charts on-the-fly for a web application. Here’s how you can do it with Flask.

from flask import Flask, send_file
from pychartdir import *
import io
app = Flask(__name__)
@app.route("/")
def show_chart():
    # 1. Create the chart (same as before)
    data = [10, 13, 18, 25, 33, 40, 45, 50, 58, 63, 68, 73]
    labels = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
    c = Chart(600, 400)
    c.addTitle("Live Sales Data")
    c.setPlotArea(50, 60, 500, 300).setBackground(0xf0f0f0)
    layer = c.addLineLayer(data, "blue")
    layer.setDataLabelStyle()
    c.xAxis().setLabels(labels)
    # 2. Save the chart to a memory buffer instead of a file
    chart_image_bytes = c.makeChart2(PNG)
    # 3. Create a file-like object from the bytes
    image_stream = io.BytesIO(chart_image_bytes)
    # 4. Send the image back to the browser
    return send_file(image_stream, mimetype='image/png')
if __name__ == "__main__":
    app.run(debug=True)

When you run this Flask app and navigate to http://127.0.0.1:5000/, you will see the chart rendered directly in your browser.

Advantages and Disadvantages

Advantages

• Extremely Customizable: If you need a chart to look exactly a certain way, ChartDirector gives you the tools.
• High Performance: Great for server-side applications that need to generate many charts.
• Rich Set of Chart Types: Excellent support for financial, scientific, and statistical charts.
• Mature and Stable: The underlying C++ library has been around for a long time.

Disadvantages

• Steeper Learning Curve: The API is more procedural and less "Pythonic" compared to libraries like Seaborn or Plotly. You build the chart step-by-step.
• License: The free version of ChartDirector includes a small watermark on the charts. For commercial use without a watermark, you must purchase a license.
• Less "Interactive": By default, it generates static images. For interactive charts (zooming, panning, tooltips), you would need to use a JavaScript library like Chart.js and use PyChartDirector to generate the initial data or static image.

Comparison with Other Libraries

When to choose PyChartDirector:

• You need a highly customized, publication-quality static chart.
• You are building a server-side application (e.g., Flask/Django) to generate charts as images.
• You need specialized chart types like financial candlesticks or Gantt charts.
• Performance is a critical factor.