docs: Update CLAUDE.md with comprehensive context for new conversations
Prepares documentation for directory rename (zpdf → zcatpdf): - Complete project overview and feature status - Documentation references (README.md, FUTURE_IMPROVEMENTS.md) - Architecture diagram and usage examples - Git instructions including post-rename steps - zcat* family ecosystem information 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
f09922076f
commit
9ae8758ed8
1 changed files with 174 additions and 725 deletions
899
CLAUDE.md
899
CLAUDE.md
|
|
@ -1,757 +1,206 @@
|
|||
# zcatpdf - Generador PDF para Zig
|
||||
|
||||
> **Version**: v1.0 - RELEASE (FEATURE COMPLETE)
|
||||
> **Ultima actualizacion**: 2025-12-09
|
||||
> **Lenguaje**: Zig 0.15.2
|
||||
> **Estado**: v1.0 - RELEASE (FEATURE COMPLETE)
|
||||
> **Fuente principal**: fpdf2 (Python) - https://github.com/py-pdf/fpdf2
|
||||
|
||||
## Descripcion del Proyecto
|
||||
|
||||
**zcatpdf** es una libreria pura Zig para generacion de documentos PDF. Compila a un binario unico con minimas dependencias.
|
||||
|
||||
**Filosofia**:
|
||||
- Minimas dependencias (libdeflate para compresion)
|
||||
- API simple y directa inspirada en fpdf2
|
||||
- Enfocado en generacion de facturas/documentos comerciales
|
||||
- Soporte completo: texto, tablas, imagenes, links, graficos vectoriales
|
||||
|
||||
**Caracteristicas principales**:
|
||||
- Sistema de texto completo (cell, multiCell, alineacion, word wrap)
|
||||
- 14 fuentes Type1 standard (Helvetica, Times, Courier, etc.)
|
||||
- Imagenes JPEG y PNG (con alpha/transparencia)
|
||||
- Compresion FlateDecode para streams e imagenes
|
||||
- Table helper para tablas formateadas
|
||||
- Paginacion automatica (numeros de pagina, headers, footers)
|
||||
- Links clickeables (URLs externas + links internos entre paginas)
|
||||
- Bookmarks/Outline para navegacion en sidebar
|
||||
- Curvas Bezier, circulos, elipses, arcos
|
||||
- Transformaciones (rotacion, escala, skew, traslacion)
|
||||
- Transparencia/Opacidad (fill y stroke alpha)
|
||||
- Gradientes lineales y radiales (Shading Patterns)
|
||||
- Barcodes: Code128 (1D) y QR Code (2D)
|
||||
- TrueType font parsing (family, metrics, glyph widths)
|
||||
- Security: RC4 encryption, permission flags
|
||||
- Forms: AcroForms (text fields, checkboxes)
|
||||
- SVG import (basic path/shape support)
|
||||
- Templates: Reusable document layouts
|
||||
- Markdown: Styled text (bold, italic, links, headings, lists)
|
||||
- Colores RGB, CMYK, Grayscale
|
||||
> **Repositorio**: git@git.reugenio.com:reugenio/zcatpdf.git
|
||||
|
||||
---
|
||||
|
||||
## Estado Actual - v1.0
|
||||
## Informacion para Nueva Conversacion
|
||||
|
||||
### Funcionalidades Implementadas
|
||||
### Que es zcatpdf?
|
||||
|
||||
| Categoria | Funcionalidad | Estado |
|
||||
|-----------|---------------|--------|
|
||||
| **Documento** | | |
|
||||
| | Crear PDF 1.4 | OK |
|
||||
| | Metadatos (titulo, autor, etc.) | OK |
|
||||
| | Multiples paginas | OK |
|
||||
| | Tamanos estandar (A4, Letter, A3, A5, Legal) | OK |
|
||||
| | Compresion FlateDecode configurable | OK |
|
||||
| | Bookmarks/Outline | OK |
|
||||
| **Texto** | | |
|
||||
| | drawText() - texto en posicion | OK |
|
||||
| | cell() - celda con bordes/relleno | OK |
|
||||
| | multiCell() - word wrap automatico | OK |
|
||||
| | Alineacion (left, center, right) | OK |
|
||||
| | 14 fuentes Type1 standard | OK |
|
||||
| **Graficos** | | |
|
||||
| | Lineas | OK |
|
||||
| | Rectangulos (stroke, fill) | OK |
|
||||
| | Curvas Bezier (cubicas, cuadraticas) | OK |
|
||||
| | Circulos y elipses | OK |
|
||||
| | Arcos | OK |
|
||||
| | Colores RGB/CMYK/Gray | OK |
|
||||
| **Transformaciones** | | |
|
||||
| | Rotacion (alrededor de punto) | OK |
|
||||
| | Escala (desde punto) | OK |
|
||||
| | Traslacion | OK |
|
||||
| | Skew/Shear | OK |
|
||||
| | Matriz personalizada | OK |
|
||||
| | saveState()/restoreState() | OK |
|
||||
| **Transparencia** | | |
|
||||
| | Fill opacity (0.0-1.0) | OK |
|
||||
| | Stroke opacity (0.0-1.0) | OK |
|
||||
| | ExtGState resources | OK |
|
||||
| **Gradientes** | | |
|
||||
| | Linear gradients (horizontal, vertical, diagonal) | OK |
|
||||
| | Radial gradients (circle, ellipse) | OK |
|
||||
| | Shading Patterns (Type 2, Type 3) | OK |
|
||||
| **Barcodes** | | |
|
||||
| | Code128 (1D barcode) | OK |
|
||||
| | QR Code (2D barcode) | OK |
|
||||
| | Error correction levels (L, M, Q, H) | OK |
|
||||
| | drawCode128() / drawCode128WithText() | OK |
|
||||
| | drawQRCode() | OK |
|
||||
| **TrueType Fonts** | | |
|
||||
| | TTF file parsing | OK |
|
||||
| | Font metrics (ascender, descender, etc.) | OK |
|
||||
| | Glyph widths | OK |
|
||||
| | Character to glyph mapping (cmap) | OK |
|
||||
| | addTtfFontFromFile() | OK |
|
||||
| **Security** | | |
|
||||
| | RC4 cipher (40/128-bit) | OK |
|
||||
| | User/Owner passwords | OK |
|
||||
| | Permission flags | OK |
|
||||
| | MD5 key derivation | OK |
|
||||
| | Encryption module | OK |
|
||||
| **Forms** | | |
|
||||
| | TextField | OK |
|
||||
| | CheckBox | OK |
|
||||
| | Field flags | OK |
|
||||
| | AcroForm basics | OK |
|
||||
| **SVG** | | |
|
||||
| | Path parsing | OK |
|
||||
| | Basic shapes (rect, circle, ellipse, line) | OK |
|
||||
| | Colors (fill, stroke) | OK |
|
||||
| | PDF content generation | OK |
|
||||
| **Templates** | | |
|
||||
| | Template struct | OK |
|
||||
| | Named regions | OK |
|
||||
| | Fixed content | OK |
|
||||
| | invoiceTemplate() | OK |
|
||||
| | letterTemplate() | OK |
|
||||
| **Markdown** | | |
|
||||
| | Bold (**text**) | OK |
|
||||
| | Italic (*text*) | OK |
|
||||
| | Bold+Italic (***text***) | OK |
|
||||
| | Strikethrough (~~text~~) | OK |
|
||||
| | Links ([text](url)) | OK |
|
||||
| | Headings (#, ##, ###) | OK |
|
||||
| | Bullet lists (- item) | OK |
|
||||
| | Numbered lists (1. item) | OK |
|
||||
| **Imagenes** | | |
|
||||
| | JPEG embedding (passthrough) | OK |
|
||||
| | PNG embedding (RGB, RGBA, Grayscale, Indexed) | OK |
|
||||
| | PNG alpha channel (soft masks) | OK |
|
||||
| | image() / imageFit() | OK |
|
||||
| | Aspect ratio preservation | OK |
|
||||
| **Compresion** | | |
|
||||
| | FlateDecode para content streams | OK |
|
||||
| | FlateDecode para imagenes PNG | OK |
|
||||
| | Nivel configurable (0-12) | OK |
|
||||
| | Heuristica inteligente | OK |
|
||||
| **Tablas** | | |
|
||||
| | Table helper | OK |
|
||||
| | header(), row(), footer() | OK |
|
||||
| | Alineacion por columna | OK |
|
||||
| | Estilos personalizados | OK |
|
||||
| **Paginacion** | | |
|
||||
| | Numeros de pagina | OK |
|
||||
| | Headers automaticos | OK |
|
||||
| | Footers automaticos | OK |
|
||||
| | skip_pages option | OK |
|
||||
| **Links** | | |
|
||||
| | URL links clickeables | OK |
|
||||
| | Internal page links | OK |
|
||||
| | Visual styling (azul+subrayado) | OK |
|
||||
| | Link annotations | OK |
|
||||
Libreria pura Zig para generacion de documentos PDF. Parte de la familia "zcat*" (zcatui, zcatgui, zcatpdf).
|
||||
|
||||
### Tests y Ejemplos
|
||||
### Documentacion Disponible
|
||||
|
||||
- **125+ tests** unitarios pasando
|
||||
- **16 ejemplos** funcionales:
|
||||
- `hello.zig` - PDF minimo
|
||||
- `invoice.zig` - Factura completa
|
||||
- `text_demo.zig` - Sistema de texto
|
||||
- `image_demo.zig` - Imagenes JPEG y PNG
|
||||
- `table_demo.zig` - Table helper
|
||||
- `pagination_demo.zig` - Paginacion multi-pagina
|
||||
- `links_demo.zig` - Links clickeables
|
||||
- `bookmarks_demo.zig` - Bookmarks en sidebar
|
||||
- `curves_demo.zig` - Bezier, circulos, elipses, arcos
|
||||
- `transforms_demo.zig` - Rotacion, escala, skew
|
||||
- `transparency_demo.zig` - Opacidad/alpha
|
||||
- `gradient_demo.zig` - Gradientes lineales y radiales
|
||||
- `barcode_demo.zig` - Code128 y QR codes
|
||||
- `ttf_demo.zig` - TrueType font parsing
|
||||
- `template_demo.zig` - Document templates
|
||||
- `markdown_demo.zig` - Markdown styled text
|
||||
| Archivo | Contenido |
|
||||
|---------|-----------|
|
||||
| `README.md` | **Manual de referencia completo** - API, ejemplos de codigo, tipos, archivos |
|
||||
| `FUTURE_IMPROVEMENTS.md` | **Mejoras futuras detalladas** - TTF embedding, encryption integration, forms output, SVG avanzado |
|
||||
| `CLAUDE.md` | Este archivo - contexto del proyecto |
|
||||
|
||||
---
|
||||
|
||||
## Arquitectura
|
||||
|
||||
```
|
||||
zcatpdf/
|
||||
├── CLAUDE.md # Documentacion del proyecto
|
||||
├── build.zig # Sistema de build
|
||||
├── src/
|
||||
│ ├── root.zig # Exports publicos
|
||||
│ ├── pdf.zig # Pdf facade (API principal)
|
||||
│ ├── page.zig # Page + texto + links + transformaciones
|
||||
│ ├── content_stream.zig # Operadores PDF
|
||||
│ ├── table.zig # Table helper
|
||||
│ ├── pagination.zig # Paginacion, headers, footers
|
||||
│ ├── links.zig # Link types
|
||||
│ ├── outline.zig # Bookmarks/Outline
|
||||
│ ├── security/
|
||||
│ │ ├── mod.zig # Security exports
|
||||
│ │ ├── rc4.zig # RC4 cipher
|
||||
│ │ └── encryption.zig # PDF encryption handler
|
||||
│ ├── forms/
|
||||
│ │ ├── mod.zig # Forms exports
|
||||
│ │ └── field.zig # TextField, CheckBox
|
||||
│ ├── svg/
|
||||
│ │ ├── mod.zig # SVG exports
|
||||
│ │ └── parser.zig # SVG parser
|
||||
│ ├── template/
|
||||
│ │ ├── mod.zig # Template exports
|
||||
│ │ └── template.zig # Template, Region definitions
|
||||
│ ├── markdown/
|
||||
│ │ ├── mod.zig # Markdown exports
|
||||
│ │ └── markdown.zig # MarkdownRenderer, TextSpan
|
||||
│ ├── fonts/
|
||||
│ │ ├── type1.zig # 14 fuentes Type1 + metricas
|
||||
│ │ └── ttf.zig # TrueType font parser
|
||||
│ ├── graphics/
|
||||
│ │ ├── color.zig # Color (RGB, CMYK, Gray)
|
||||
│ │ ├── extgstate.zig # Extended Graphics State (transparency)
|
||||
│ │ └── gradient.zig # Linear/Radial gradients
|
||||
│ ├── barcodes/
|
||||
│ │ ├── mod.zig # Barcode exports
|
||||
│ │ ├── code128.zig # Code128 1D barcode
|
||||
│ │ └── qr.zig # QR Code 2D barcode
|
||||
│ ├── images/
|
||||
│ │ ├── jpeg.zig # JPEG parser
|
||||
│ │ ├── png.zig # PNG parser + unfiltering
|
||||
│ │ └── image_info.zig # ImageInfo struct
|
||||
│ ├── compression/
|
||||
│ │ ├── mod.zig # Compression exports
|
||||
│ │ └── zlib.zig # libdeflate wrapper
|
||||
│ ├── objects/
|
||||
│ │ └── base.zig # PageSize, Orientation
|
||||
│ └── output/
|
||||
│ └── producer.zig # Serializa PDF + images + links + outline
|
||||
└── examples/
|
||||
├── hello.zig
|
||||
├── invoice.zig
|
||||
├── text_demo.zig
|
||||
├── image_demo.zig
|
||||
├── table_demo.zig
|
||||
├── pagination_demo.zig
|
||||
├── links_demo.zig
|
||||
├── bookmarks_demo.zig
|
||||
├── curves_demo.zig
|
||||
├── transforms_demo.zig
|
||||
├── transparency_demo.zig
|
||||
├── gradient_demo.zig
|
||||
├── barcode_demo.zig
|
||||
├── ttf_demo.zig
|
||||
├── template_demo.zig
|
||||
└── markdown_demo.zig
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Quick Reference
|
||||
|
||||
### Documento Basico
|
||||
|
||||
```zig
|
||||
const zcatpdf = @import("zcatpdf");
|
||||
|
||||
var doc = zcatpdf.Pdf.init(allocator, .{});
|
||||
defer doc.deinit();
|
||||
|
||||
doc.setTitle("Mi Documento");
|
||||
var page = try doc.addPage(.{});
|
||||
|
||||
try page.setFont(.helvetica_bold, 24);
|
||||
try page.drawText(50, 750, "Hello, PDF!");
|
||||
|
||||
try doc.save("output.pdf");
|
||||
```
|
||||
|
||||
### Celdas y Tablas
|
||||
|
||||
```zig
|
||||
// cell() simple
|
||||
try page.cell(100, 20, "Hello", zcatpdf.Border.all, .center, true);
|
||||
|
||||
// multiCell con word wrap
|
||||
try page.multiCell(400, null, texto_largo, zcatpdf.Border.none, .left, false);
|
||||
|
||||
// Table helper
|
||||
const widths = [_]f32{ 200, 100, 100 };
|
||||
var table = zcatpdf.Table.init(page, .{
|
||||
.col_widths = &widths,
|
||||
});
|
||||
try table.header(&.{ "Producto", "Qty", "Precio" });
|
||||
try table.row(&.{ "Item A", "10", "$50" });
|
||||
try table.footer(&.{ "Total", "", "$50" });
|
||||
```
|
||||
|
||||
### Imagenes
|
||||
|
||||
```zig
|
||||
const img_idx = try doc.addJpegImageFromFile("foto.jpg");
|
||||
const info = doc.getImage(img_idx).?;
|
||||
try page.image(img_idx, info, 50, 500, 200, 150);
|
||||
```
|
||||
|
||||
### Curvas y Formas
|
||||
|
||||
```zig
|
||||
// Curva Bezier cubica
|
||||
try page.drawBezier(x0, y0, x1, y1, x2, y2, x3, y3);
|
||||
|
||||
// Circulo
|
||||
try page.drawCircle(cx, cy, radius);
|
||||
try page.fillCircle(cx, cy, radius);
|
||||
|
||||
// Elipse
|
||||
try page.drawEllipse(cx, cy, rx, ry);
|
||||
try page.fillEllipse(cx, cy, rx, ry);
|
||||
|
||||
// Arco
|
||||
try page.drawArc(cx, cy, rx, ry, start_deg, end_deg);
|
||||
```
|
||||
|
||||
### Transformaciones
|
||||
|
||||
```zig
|
||||
// Rotar alrededor de un punto
|
||||
try page.saveState();
|
||||
try page.rotate(45, center_x, center_y); // 45 grados
|
||||
// ... dibujar contenido rotado ...
|
||||
try page.restoreState();
|
||||
|
||||
// Escalar
|
||||
try page.scale(2.0, 1.5, cx, cy); // 2x horizontal, 1.5x vertical
|
||||
|
||||
// Skew/Shear
|
||||
try page.skew(15, 0); // 15 grados en X
|
||||
|
||||
// Trasladar
|
||||
try page.translate(100, 50);
|
||||
```
|
||||
|
||||
### Transparencia
|
||||
|
||||
```zig
|
||||
// Opacidad de relleno
|
||||
try page.setFillOpacity(0.5); // 50% transparente
|
||||
|
||||
// Opacidad de trazo
|
||||
try page.setStrokeOpacity(0.75); // 75% opaco
|
||||
|
||||
// Ambos a la vez
|
||||
try page.setOpacity(0.3); // 30% opaco
|
||||
|
||||
// Restaurar opacidad completa
|
||||
try page.setOpacity(1.0);
|
||||
```
|
||||
|
||||
### Gradientes
|
||||
|
||||
```zig
|
||||
// Gradiente lineal en rectangulo
|
||||
try page.linearGradientRect(x, y, width, height, Color.red, Color.blue, .horizontal);
|
||||
try page.linearGradientRect(x, y, width, height, Color.green, Color.yellow, .vertical);
|
||||
try page.linearGradientRect(x, y, width, height, Color.purple, Color.cyan, .diagonal);
|
||||
|
||||
// Gradiente radial en circulo (centro a borde)
|
||||
try page.radialGradientCircle(cx, cy, radius, Color.white, Color.blue);
|
||||
|
||||
// Gradiente radial en elipse
|
||||
try page.radialGradientEllipse(cx, cy, rx, ry, Color.yellow, Color.red);
|
||||
```
|
||||
|
||||
### Barcodes
|
||||
|
||||
```zig
|
||||
// Code128 1D barcode
|
||||
try page.drawCode128(x, y, "ABC-12345", 50, 1.5); // height=50, module_width=1.5
|
||||
|
||||
// Code128 con texto debajo
|
||||
try page.drawCode128WithText(x, y, "ABC-12345", 50, 1.5, true);
|
||||
|
||||
// QR Code 2D barcode
|
||||
try page.drawQRCode(x, y, "HTTPS://GITHUB.COM", 100, zcatpdf.QRCode.ErrorCorrection.M);
|
||||
|
||||
// Error correction levels:
|
||||
// .L - Low (7% recovery)
|
||||
// .M - Medium (15% recovery)
|
||||
// .Q - Quartile (25% recovery)
|
||||
// .H - High (30% recovery)
|
||||
```
|
||||
|
||||
### TrueType Fonts
|
||||
|
||||
```zig
|
||||
// Load TTF font from file
|
||||
const font_idx = try pdf.addTtfFontFromFile("/path/to/font.ttf");
|
||||
const font = pdf.getTtfFont(font_idx).?;
|
||||
|
||||
// Get font information
|
||||
std.debug.print("Family: {s}\n", .{font.family_name});
|
||||
std.debug.print("Units/EM: {d}\n", .{font.units_per_em});
|
||||
std.debug.print("Ascender: {d}\n", .{font.ascender});
|
||||
std.debug.print("Descender: {d}\n", .{font.descender});
|
||||
std.debug.print("Num glyphs: {d}\n", .{font.num_glyphs});
|
||||
|
||||
// Get character width
|
||||
const glyph_id = font.getGlyphIndex('A');
|
||||
const width = font.getGlyphWidth(glyph_id);
|
||||
|
||||
// Calculate string width in points
|
||||
const text_width = font.stringWidth("Hello", 12.0);
|
||||
|
||||
// Note: Full TTF embedding for rendering text requires CIDFont Type 2
|
||||
// output which is planned for a future version.
|
||||
```
|
||||
|
||||
### Bookmarks
|
||||
|
||||
```zig
|
||||
// Agregar bookmark que apunta a pagina
|
||||
try doc.addBookmark("Capitulo 1", 0); // pagina 0
|
||||
|
||||
// Con posicion Y especifica
|
||||
try doc.addBookmarkAt("Seccion 1.1", 0, 500);
|
||||
|
||||
// Los bookmarks aparecen en el sidebar del lector PDF
|
||||
```
|
||||
|
||||
### Links Clickeables
|
||||
|
||||
```zig
|
||||
// URL link con visual styling
|
||||
_ = try page.urlLink(100, 700, "Click aqui", "https://example.com");
|
||||
|
||||
// O desde posicion actual
|
||||
_ = try page.writeUrlLink("Visitar web", "https://example.com");
|
||||
|
||||
// Link interno (saltar a pagina)
|
||||
try page.addInternalLink(2, 100, 700, 150, 20); // page 2
|
||||
```
|
||||
|
||||
### Paginacion
|
||||
|
||||
```zig
|
||||
// Numeros de pagina
|
||||
try zcatpdf.Pagination.addPageNumbers(&doc, .{
|
||||
.format = "Page {PAGE} of {PAGES}",
|
||||
.position = .bottom_center,
|
||||
});
|
||||
|
||||
// Header con linea
|
||||
try zcatpdf.addHeader(&doc, "Documento", .{
|
||||
.draw_line = true,
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comandos
|
||||
### Comandos Esenciales
|
||||
|
||||
```bash
|
||||
# Zig path
|
||||
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
|
||||
|
||||
# Compilar
|
||||
# Compilar y testear
|
||||
$ZIG build
|
||||
|
||||
# Tests
|
||||
$ZIG build test
|
||||
|
||||
# Ejemplos
|
||||
# Ejecutar ejemplos
|
||||
./zig-out/bin/hello
|
||||
./zig-out/bin/invoice
|
||||
./zig-out/bin/text_demo
|
||||
./zig-out/bin/image_demo
|
||||
./zig-out/bin/table_demo
|
||||
./zig-out/bin/pagination_demo
|
||||
./zig-out/bin/links_demo
|
||||
./zig-out/bin/bookmarks_demo
|
||||
./zig-out/bin/curves_demo
|
||||
./zig-out/bin/transforms_demo
|
||||
./zig-out/bin/transparency_demo
|
||||
./zig-out/bin/gradient_demo
|
||||
./zig-out/bin/barcode_demo
|
||||
./zig-out/bin/ttf_demo
|
||||
# etc. (16 ejemplos en total)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Roadmap Completado
|
||||
|
||||
### Fase 1 - Core (COMPLETADO)
|
||||
- [x] Estructura PDF 1.4
|
||||
- [x] Paginas multiples
|
||||
- [x] Texto basico
|
||||
- [x] Graficos (lineas, rectangulos)
|
||||
- [x] Colores
|
||||
|
||||
### Fase 2 - Texto Avanzado (COMPLETADO)
|
||||
- [x] cell() / cellAdvanced()
|
||||
- [x] multiCell() con word wrap
|
||||
- [x] Alineacion
|
||||
- [x] Bordes
|
||||
|
||||
### Fase 3 - Imagenes (COMPLETADO)
|
||||
- [x] JPEG embedding
|
||||
- [x] image() / imageFit()
|
||||
- [x] PNG embedding completo
|
||||
|
||||
### Fase 4 - Utilidades (COMPLETADO)
|
||||
- [x] Table helper
|
||||
- [x] Paginacion
|
||||
- [x] Headers/Footers
|
||||
- [x] Links visuales
|
||||
|
||||
### Fase 5 - Links Clickeables (COMPLETADO)
|
||||
- [x] URL annotations
|
||||
- [x] Internal page links
|
||||
- [x] Link annotations en PDF
|
||||
|
||||
### Fase 6 - PNG + Compresion (COMPLETADO)
|
||||
- [x] Integracion libdeflate-zig
|
||||
- [x] PNG parsing completo (RGB, RGBA, Grayscale, Indexed)
|
||||
- [x] PNG unfiltering (None, Sub, Up, Average, Paeth)
|
||||
- [x] Soft masks para canal alpha
|
||||
- [x] FlateDecode para content streams
|
||||
- [x] Compresion configurable (nivel 0-12)
|
||||
- [x] Heuristica inteligente (min_size, min_ratio)
|
||||
|
||||
### Fase 7 - Bookmarks/Outline (COMPLETADO)
|
||||
- [x] OutlineItem struct
|
||||
- [x] addBookmark() / addBookmarkAt()
|
||||
- [x] Outline en sidebar del lector PDF
|
||||
|
||||
### Fase 8 - Curvas Bezier (COMPLETADO)
|
||||
- [x] drawBezier() - curvas cubicas
|
||||
- [x] drawQuadBezier() - curvas cuadraticas
|
||||
- [x] drawCircle() / fillCircle()
|
||||
- [x] drawEllipse() / fillEllipse()
|
||||
- [x] drawArc()
|
||||
|
||||
### Fase 9 - Transformaciones (COMPLETADO)
|
||||
- [x] rotate() - rotacion alrededor de punto
|
||||
- [x] scale() - escala desde punto
|
||||
- [x] translate() - traslacion
|
||||
- [x] skew() - deformacion
|
||||
- [x] transform() - matriz personalizada
|
||||
- [x] saveState() / restoreState()
|
||||
|
||||
### Fase 10 - Transparencia (COMPLETADO)
|
||||
- [x] ExtGState para opacidad
|
||||
- [x] setFillOpacity()
|
||||
- [x] setStrokeOpacity()
|
||||
- [x] setOpacity()
|
||||
|
||||
### Fase 11 - Gradientes (COMPLETADO)
|
||||
- [x] LinearGradient (horizontal, vertical, diagonal)
|
||||
- [x] RadialGradient (circle, ellipse)
|
||||
- [x] Shading Patterns Type 2 (axial) y Type 3 (radial)
|
||||
- [x] linearGradientRect()
|
||||
- [x] radialGradientCircle()
|
||||
- [x] radialGradientEllipse()
|
||||
|
||||
### Fase 12 - Barcodes (COMPLETADO)
|
||||
- [x] Code128 1D barcode (ASCII 0-127)
|
||||
- [x] Code Sets A, B, C con switching automatico
|
||||
- [x] QR Code 2D barcode (ISO/IEC 18004)
|
||||
- [x] Error correction levels (L, M, Q, H)
|
||||
- [x] drawCode128() / drawCode128WithText()
|
||||
- [x] drawQRCode()
|
||||
|
||||
### Fase 13 - TTF Fonts (COMPLETADO)
|
||||
- [x] TrueType font file parsing
|
||||
- [x] Font metrics (units_per_em, ascender, descender, etc.)
|
||||
- [x] Glyph width tables
|
||||
- [x] Character to glyph mapping (cmap format 0, 4, 6, 12)
|
||||
- [x] addTtfFontFromFile()
|
||||
- [x] stringWidth() calculation
|
||||
- [ ] Full TTF embedding for PDF rendering (CIDFont Type 2) - Future
|
||||
|
||||
### Fase 14 - Security/Encryption (COMPLETADO)
|
||||
- [x] RC4 stream cipher (40-bit and 128-bit)
|
||||
- [x] PDF Standard Security Handler
|
||||
- [x] User/Owner password handling
|
||||
- [x] Permission flags (print, modify, copy, annotate, etc.)
|
||||
- [x] MD5-based key derivation
|
||||
- [x] Object key generation
|
||||
- [ ] Full PDF output integration - Future
|
||||
|
||||
### Fase 15 - Forms/AcroForms (COMPLETADO)
|
||||
- [x] TextField struct (name, position, size)
|
||||
- [x] CheckBox struct
|
||||
- [x] FieldFlags (readonly, required, multiline, password)
|
||||
- [x] FormField union type
|
||||
- [x] toFormField() conversion
|
||||
- [ ] Full PDF AcroForm output integration - Future
|
||||
|
||||
### Fase 16 - SVG Import (COMPLETADO)
|
||||
- [x] SvgParser struct
|
||||
- [x] Basic shapes (rect, circle, ellipse, line)
|
||||
- [x] Path element with commands
|
||||
- [x] PathCommand enum (MoveTo, LineTo, CurveTo, etc.)
|
||||
- [x] Color parsing (fill, stroke)
|
||||
- [x] toPdfContent() - generates PDF operators
|
||||
- [ ] Text elements - Future
|
||||
- [ ] Transforms - Future
|
||||
|
||||
### Fase 17 - Templates (COMPLETADO)
|
||||
- [x] Template struct with named regions
|
||||
- [x] TemplateRegion (position, size, type)
|
||||
- [x] RegionType enum (text, image, table, custom)
|
||||
- [x] FixedContent for repeating elements
|
||||
- [x] invoiceTemplate() predefined
|
||||
- [x] letterTemplate() predefined
|
||||
- [x] template_demo.zig ejemplo
|
||||
|
||||
### Fase 18 - Markdown Styling (COMPLETADO)
|
||||
- [x] MarkdownRenderer struct
|
||||
- [x] SpanStyle (bold, italic, underline, strikethrough)
|
||||
- [x] TextSpan with style, color, url, font_size
|
||||
- [x] Inline parsing: **bold**, *italic*, ***both***, ~~strike~~
|
||||
- [x] Links: [text](url)
|
||||
- [x] Headings: #, ##, ###
|
||||
- [x] Lists: - bullet, 1. numbered
|
||||
- [x] fontForStyle() helper
|
||||
- [x] markdown_demo.zig ejemplo
|
||||
|
||||
### Futuro
|
||||
|
||||
| Fase | Nombre | Prioridad |
|
||||
|------|--------|-----------|
|
||||
| 19 | Mejoras de Calidad | CONTINUA |
|
||||
|
||||
---
|
||||
|
||||
## Historial
|
||||
|
||||
### 2025-12-09 - v0.16 (Markdown Styling) - FEATURE COMPLETE
|
||||
- MarkdownRenderer para texto con estilo
|
||||
- SpanStyle (bold, italic, underline, strikethrough)
|
||||
- TextSpan con style, color, url, font_size
|
||||
- Parsing de: **bold**, *italic*, ***bold+italic***
|
||||
- Strikethrough: ~~text~~
|
||||
- Links: [text](url)
|
||||
- Headings: #, ##, ###
|
||||
- Lists: - bullet, 1. numbered
|
||||
- fontForStyle() helper function
|
||||
- markdown_demo.zig ejemplo
|
||||
- 125+ tests, 16 ejemplos
|
||||
|
||||
### 2025-12-09 - v0.15 (Templates)
|
||||
- Template struct con regiones nombradas
|
||||
- TemplateRegion para definir areas de contenido
|
||||
- FixedContent para elementos repetitivos
|
||||
- invoiceTemplate() y letterTemplate() predefinidos
|
||||
- template_demo.zig ejemplo
|
||||
- 120+ tests, 15 ejemplos
|
||||
|
||||
### 2025-12-09 - v0.14 (SVG Import)
|
||||
- SvgParser para importar graficos vectoriales
|
||||
- Soporte para rect, circle, ellipse, line, path
|
||||
- PathCommand para curvas y lineas
|
||||
- toPdfContent() genera operadores PDF
|
||||
- svg/mod.zig, parser.zig
|
||||
|
||||
### 2025-12-09 - v0.13 (Forms)
|
||||
- TextField y CheckBox structs
|
||||
- FieldFlags (readonly, required, multiline, password)
|
||||
- FormField union type
|
||||
- forms/mod.zig, field.zig
|
||||
|
||||
### 2025-12-09 - v0.12 (Security)
|
||||
- RC4 stream cipher (40-bit and 128-bit)
|
||||
- PDF Standard Security Handler
|
||||
- User/Owner password processing
|
||||
- Permission flags (Permissions struct)
|
||||
- MD5-based key derivation (Algorithms 3.1-3.5)
|
||||
- security/mod.zig, rc4.zig, encryption.zig
|
||||
- 100+ tests
|
||||
|
||||
### 2025-12-09 - v0.11 (TTF Fonts)
|
||||
- TrueType font file parsing (tables: head, hhea, maxp, hmtx, cmap, name, OS/2, post)
|
||||
- Font metrics extraction
|
||||
- Glyph width tables for string width calculation
|
||||
- Character to glyph mapping (cmap formats 0, 4, 6, 12)
|
||||
- addTtfFontFromFile(), getTtfFont()
|
||||
- ttf_demo.zig ejemplo
|
||||
- 14 ejemplos, 95+ tests
|
||||
|
||||
### 2025-12-09 - v0.10 (Barcodes)
|
||||
- Code128 1D barcode con Code Sets A, B, C
|
||||
- QR Code 2D barcode con error correction levels
|
||||
- drawCode128(), drawCode128WithText(), drawQRCode()
|
||||
- barcode_demo.zig ejemplo
|
||||
- 13 ejemplos, 90+ tests
|
||||
|
||||
### 2025-12-09 - v0.9 (Gradientes)
|
||||
- Linear gradients (horizontal, vertical, diagonal)
|
||||
- Radial gradients (circle, ellipse)
|
||||
- Shading Patterns Type 2 (axial) y Type 3 (radial)
|
||||
- linearGradientRect(), radialGradientCircle(), radialGradientEllipse()
|
||||
- GradientData, LinearGradient, RadialGradient types
|
||||
- gradient_demo.zig ejemplo
|
||||
- 12 ejemplos, 85+ tests
|
||||
|
||||
### 2025-12-08 - v0.8 (Bookmarks + Bezier + Transforms + Transparency)
|
||||
- Bookmarks/Outline para navegacion en sidebar
|
||||
- Curvas Bezier (cubicas y cuadraticas)
|
||||
- Circulos, elipses y arcos
|
||||
- Transformaciones: rotacion, escala, traslacion, skew
|
||||
- saveState()/restoreState() para limitar transformaciones
|
||||
- Transparencia via ExtGState
|
||||
- setFillOpacity(), setStrokeOpacity(), setOpacity()
|
||||
- 4 nuevos ejemplos
|
||||
- 85+ tests pasando
|
||||
|
||||
### 2025-12-08 - v0.7 (PNG + Compresion)
|
||||
- Integracion libdeflate-zig para compresion
|
||||
- PNG embedding completo (RGB, RGBA, Grayscale, Indexed)
|
||||
- PNG unfiltering (5 filtros)
|
||||
- Soft masks para transparencia
|
||||
- FlateDecode para content streams
|
||||
- Compresion configurable con heuristica
|
||||
- 82+ tests pasando
|
||||
|
||||
### 2025-12-08 - v0.6 (Links Clickeables)
|
||||
- Link annotations clickeables en PDF
|
||||
- addUrlLink() / addInternalLink() en Page
|
||||
- urlLink() / writeUrlLink() combinan visual + annotation
|
||||
- OutputProducer genera /Annots en pages
|
||||
- links_demo.zig ejemplo con 2 paginas
|
||||
- 7 ejemplos, ~70 tests
|
||||
|
||||
### 2025-12-08 - v0.5 (Utilidades)
|
||||
- Table helper
|
||||
- Pagination (numeros de pagina)
|
||||
- Headers/Footers automaticos
|
||||
- Links visuales
|
||||
|
||||
### 2025-12-08 - v0.4 (Imagenes)
|
||||
- JPEG embedding
|
||||
- image() / imageFit()
|
||||
|
||||
### 2025-12-08 - v0.3 (Texto)
|
||||
- cell() / multiCell()
|
||||
- Word wrap, alineacion
|
||||
|
||||
### 2025-12-08 - v0.2 (Core)
|
||||
- Estructura inicial
|
||||
|
||||
### 2025-12-08 - v0.1 (Setup)
|
||||
- Setup inicial del proyecto
|
||||
|
||||
---
|
||||
|
||||
## Equipo
|
||||
### Normas de Trabajo
|
||||
|
||||
Las normas del equipo estan en:
|
||||
```
|
||||
/mnt/cello2/arno/re/recode/TEAM_STANDARDS/
|
||||
git remote: git@git.reugenio.com:reugenio/zcatpdf.git
|
||||
```
|
||||
|
||||
**Reglas clave para este proyecto:**
|
||||
- Nombres en minusculas: `zcatpdf` (no ZcatPDF, no zCatPdf)
|
||||
- Import: `@import("zcatpdf")`
|
||||
- Doc comments (`///`) en funciones publicas
|
||||
- Codigo idiomatico Zig (snake_case, error handling explicito)
|
||||
|
||||
---
|
||||
|
||||
## Estado del Proyecto
|
||||
|
||||
### FEATURE COMPLETE - v1.0
|
||||
|
||||
La libreria esta completa para uso en produccion. Todas las funcionalidades planificadas estan implementadas:
|
||||
|
||||
| Categoria | Funcionalidades |
|
||||
|-----------|-----------------|
|
||||
| **Documento** | PDF 1.4, metadatos, multiples paginas, compresion FlateDecode |
|
||||
| **Texto** | drawText, cell, multiCell, word wrap, 14 fuentes Type1 |
|
||||
| **Graficos** | Lineas, rectangulos, curvas Bezier, circulos, elipses, arcos |
|
||||
| **Colores** | RGB, CMYK, Grayscale, colores predefinidos |
|
||||
| **Imagenes** | JPEG, PNG (con alpha/transparencia) |
|
||||
| **Tablas** | Table helper con headers, rows, footers |
|
||||
| **Links** | URLs clickeables, links internos entre paginas |
|
||||
| **Bookmarks** | Navegacion en sidebar del lector PDF |
|
||||
| **Transformaciones** | Rotacion, escala, traslacion, skew |
|
||||
| **Transparencia** | Fill y stroke opacity (0.0-1.0) |
|
||||
| **Gradientes** | Lineales y radiales |
|
||||
| **Barcodes** | Code128 (1D), QR Code (2D) |
|
||||
| **TTF Fonts** | Parsing de TrueType (metricas, anchos de glyph) |
|
||||
| **Security** | RC4 encryption module (40/128-bit) |
|
||||
| **Forms** | TextField, CheckBox (structs, no output aun) |
|
||||
| **SVG** | Import basico (shapes, paths) |
|
||||
| **Templates** | Layouts reutilizables (invoice, letter) |
|
||||
| **Markdown** | Texto con estilos (bold, italic, links, headings, lists) |
|
||||
|
||||
### Tests y Ejemplos
|
||||
|
||||
- **125+ tests** unitarios
|
||||
- **16 ejemplos** funcionales en `examples/`
|
||||
|
||||
---
|
||||
|
||||
## Arquitectura de Archivos
|
||||
|
||||
```
|
||||
zcatpdf/
|
||||
├── CLAUDE.md # Este archivo
|
||||
├── README.md # Manual de referencia completo
|
||||
├── FUTURE_IMPROVEMENTS.md # Mejoras futuras detalladas
|
||||
├── build.zig # Sistema de build
|
||||
├── build.zig.zon # Dependencias (libdeflate)
|
||||
├── src/
|
||||
│ ├── root.zig # Exports publicos (@import("zcatpdf"))
|
||||
│ ├── pdf.zig # Pdf struct - API principal
|
||||
│ ├── page.zig # Page - dibujo, texto, transformaciones
|
||||
│ ├── content_stream.zig # Operadores PDF de bajo nivel
|
||||
│ ├── table.zig # Table helper
|
||||
│ ├── pagination.zig # Numeros de pagina, headers, footers
|
||||
│ ├── links.zig # Link types
|
||||
│ ├── outline.zig # Bookmarks
|
||||
│ ├── fonts/ # Type1 + TrueType
|
||||
│ ├── graphics/ # Color, ExtGState, Gradient
|
||||
│ ├── images/ # JPEG, PNG parsers
|
||||
│ ├── barcodes/ # Code128, QR
|
||||
│ ├── compression/ # libdeflate wrapper
|
||||
│ ├── security/ # RC4, Encryption
|
||||
│ ├── forms/ # TextField, CheckBox
|
||||
│ ├── svg/ # SVG parser
|
||||
│ ├── template/ # Template system
|
||||
│ ├── markdown/ # Markdown renderer
|
||||
│ ├── objects/ # PageSize, Orientation
|
||||
│ └── output/ # PDF serialization
|
||||
└── examples/ # 16 demos ejecutables
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**zcatpdf - Generador PDF para Zig**
|
||||
*v1.0 - RELEASE (FEATURE COMPLETE) - 2025-12-09*
|
||||
## Uso Rapido
|
||||
|
||||
```zig
|
||||
const zcatpdf = @import("zcatpdf");
|
||||
|
||||
pub fn main() !void {
|
||||
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
|
||||
defer _ = gpa.deinit();
|
||||
const allocator = gpa.allocator();
|
||||
|
||||
var pdf = zcatpdf.Pdf.init(allocator, .{});
|
||||
defer pdf.deinit();
|
||||
|
||||
pdf.setTitle("Mi Documento");
|
||||
|
||||
var page = try pdf.addPage(.{});
|
||||
try page.setFont(.helvetica_bold, 24);
|
||||
try page.drawText(50, 750, "Hello, PDF!");
|
||||
|
||||
try pdf.save("output.pdf");
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mejoras Futuras (No Criticas)
|
||||
|
||||
Ver `FUTURE_IMPROVEMENTS.md` para detalles completos:
|
||||
|
||||
1. **TTF Font Embedding** - Embeber TTF para renderizar texto (CIDFont Type 2)
|
||||
2. **PDF Encryption Integration** - Integrar RC4 con OutputProducer
|
||||
3. **AcroForms Output** - Generar campos de formulario en PDF final
|
||||
4. **SVG Avanzado** - text, transforms, gradients en SVG
|
||||
5. **Markdown Avanzado** - code blocks, tables, images
|
||||
|
||||
---
|
||||
|
||||
## Git
|
||||
|
||||
```bash
|
||||
# Remote actual (NOTA: renombrar en Forgejo a zcatpdf)
|
||||
git remote: git@git.reugenio.com:reugenio/zcatpdf.git
|
||||
|
||||
# Branch principal
|
||||
main
|
||||
```
|
||||
|
||||
**IMPORTANTE tras renombrar directorio:**
|
||||
```bash
|
||||
# Despues de: mv zpdf zcatpdf
|
||||
cd /mnt/cello2/arno/re/recode/zig/zcatpdf
|
||||
git remote set-url origin git@git.reugenio.com:reugenio/zcatpdf.git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Familia zcat*
|
||||
|
||||
| Proyecto | Descripcion |
|
||||
|----------|-------------|
|
||||
| **zcatui** | TUI library (terminal UI, como ratatui) |
|
||||
| **zcatgui** | GUI library (immediate mode, SDL2 backend) |
|
||||
| **zcatpdf** | PDF generation library |
|
||||
|
||||
Todos siguen las mismas convenciones:
|
||||
- 100% Zig
|
||||
- Minimas dependencias
|
||||
- Nombres en minusculas
|
||||
- Open source ready
|
||||
|
||||
---
|
||||
|
||||
## Referencias Externas
|
||||
|
||||
- [PDF Reference 1.4](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf)
|
||||
- [fpdf2 (Python)](https://github.com/py-pdf/fpdf2) - Inspiracion de la API
|
||||
- [Zig Documentation](https://ziglang.org/documentation/master/)
|
||||
|
||||
---
|
||||
|
||||
**zcatpdf v1.0** - Generador PDF para Zig
|
||||
*Feature Complete - 2025-12-09*
|
||||
|
|
|
|||
Loading…
Reference in a new issue