tianzige 0.3.0

Generate Tianzige (田字格) writing grid PDFs for Chinese character practice

Tianzige (田字格)

A Python tool to generate Tianzige (田字格) writing grid PDFs for Chinese character practice.

Installation

pip install tianzige

Usage

Basic usage:

tianzige output.pdf

This will create a PDF file with default settings (A4 size, auto-calculated square size ensuring at least 10 boxes in each direction, gray lines, optimized margins).

Options

• -c, --color: Line color in hex format (default: #808080)
• -p, --page-size: Page size (choices: a4, a5, a6, a3, b4, b5, letter, legal) (default: a4)
• -s, --size: Size of each square in mm (default: auto-calculated to ensure minimum boxes)
• --min-horizontal: Minimum number of horizontal boxes (default: 10 if size not specified)
• --min-vertical: Minimum number of vertical boxes (default: 10 if size not specified)
• --margin-top: Top margin in mm (default: 15)
• --margin-bottom: Bottom margin in mm (default: 15)
• --margin-left: Left margin in mm (default: 20)
• --margin-right: Right margin in mm (default: 10)
• --no-inner-grid: Disable inner grid lines
• -v, --version: Show version information

Square Size and Box Count Behavior

1. When no size or minimum boxes specified:

   • Automatically calculates square size to fit at least 10 boxes in both directions

2. When only size specified:

   • Uses the exact size specified
   • No minimum box requirements enforced

3. When size and minimum boxes specified:

   • Uses specified size
   • Validates that minimum box requirements can be met
   • Provides detailed error message if requirements cannot be met, showing:
     • How many boxes would fit with the specified size
     • What maximum size would allow the minimum box count

Examples

Generate grid with black lines:

tianzige -c "#000000" output.pdf

Generate A5-sized grid:

tianzige -p a5 output.pdf

Generate grid with custom square size (no minimum box requirement):

tianzige -s 25 output.pdf

Generate grid with at least 12 horizontal boxes:

tianzige --min-horizontal 12 output.pdf

Generate grid with specific requirements:

tianzige --min-horizontal 12 --min-vertical 15 -p a4 output.pdf

Generate grid without inner lines:

tianzige --no-inner-grid output.pdf

Generate A3-sized grid with black lines:

tianzige -p a3 -c "#000000" output.pdf

Python API

You can also use Tianzige in your Python code:

from tianzige import create_tianzige

create_tianzige(
    "output.pdf",
    line_color="#808080",
    square_size=None,  # Auto-calculated based on page size and minimum boxes
    margin_top=15,
    margin_bottom=15,
    margin_left=20,
    margin_right=10,
    show_inner_grid=True,
    page_size='a4',  # Options: 'a4', 'a5', 'a6', 'a3', 'b4', 'b5', 'letter', 'legal'
    min_horizontal=None,  # Default: 10 if square_size is None
    min_vertical=None    # Default: 10 if square_size is None
)

Sample PDFs

The sample_pdf directory contains example outputs:

• a5_example.pdf: A5-sized grid with default settings
• black_20mm.pdf: Grid with 20mm squares and black lines
• 15x15_boxes.pdf: Grid with minimum 15 boxes in both directions

Development

Git Configuration

The repository includes a .gitignore file configured for Python development with specific rules for PDF files:

• Ignores all PDF files by default (*.pdf)
• Allows sample PDFs in the sample_pdf directory (!sample_pdf/*.pdf)
• Includes standard Python, virtual environment, and IDE ignores

License

MIT License - see the LICENSE file for details.