chess2img 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +121 -126
- package/assets/readme/chesscom-opening-e4-cburnett.png +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,26 +1,56 @@
|
|
|
1
1
|
# chess2img
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
<div align="center">
|
|
4
|
+
<img src="./assets/themes/cburnett/wK.png" alt="chess2img king icon" width="88" />
|
|
5
|
+
<p>Generate PNG chessboard images from FEN, PGN, or board arrays in Node.js.</p>
|
|
6
|
+
<p>
|
|
7
|
+
<a href="https://www.npmjs.com/package/chess2img"><img src="https://img.shields.io/npm/v/chess2img" alt="npm version" /></a>
|
|
8
|
+
<a href="https://www.npmjs.com/package/chess2img"><img src="https://img.shields.io/npm/dm/chess2img" alt="npm downloads" /></a>
|
|
9
|
+
<a href="https://www.npmjs.com/package/chess2img"><img src="https://img.shields.io/npm/l/chess2img" alt="license" /></a>
|
|
10
|
+
<a href="https://github.com/ZiriloXXX/chess2img"><img src="https://img.shields.io/github/stars/ZiriloXXX/chess2img" alt="GitHub stars" /></a>
|
|
11
|
+
</p>
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
## Overview
|
|
15
|
+
|
|
16
|
+
`chess2img` renders chessboard PNGs from FEN, PGN, or board-array inputs with a small Promise-based API for JavaScript and TypeScript users on Node.js.
|
|
17
|
+
|
|
18
|
+
## Features
|
|
19
|
+
|
|
20
|
+
- Render PNG chessboard images from `fen`, `pgn`, or `board` input.
|
|
21
|
+
- Use five bundled built-in themes: `merida`, `alpha`, `cburnett`, `cheq`, and `leipzig`.
|
|
22
|
+
- Highlight squares such as the last move or key tactical ideas.
|
|
23
|
+
- Customize board colors, size, padding, and board orientation.
|
|
24
|
+
- Use either the functional `renderChess(...)` API or the `ChessImageGenerator` class API.
|
|
25
|
+
- Register custom themes globally or pass a theme inline for one-off rendering.
|
|
26
|
+
- Consume the package from both JavaScript and TypeScript projects.
|
|
5
27
|
|
|
6
|
-
|
|
28
|
+
## Example Output
|
|
7
29
|
|
|
8
|
-
|
|
30
|
+
Opening `1.e4` with a Chess.com-like board palette, highlighted origin and destination squares, and the built-in `cburnett` piece set.
|
|
9
31
|
|
|
10
|
-
|
|
32
|
+
<img src="./assets/readme/chesscom-opening-e4-cburnett.png" alt="Opening 1.e4 example board" width="480" />
|
|
33
|
+
|
|
34
|
+
## Quick Start
|
|
11
35
|
|
|
12
36
|
```bash
|
|
13
37
|
npm install chess2img
|
|
14
38
|
```
|
|
15
39
|
|
|
16
|
-
Render a board image:
|
|
17
|
-
|
|
18
40
|
```ts
|
|
19
41
|
import { writeFile } from "node:fs/promises";
|
|
20
42
|
import { renderChess } from "chess2img";
|
|
21
43
|
|
|
22
44
|
const png = await renderChess({
|
|
23
|
-
fen: "rnbqkbnr/pppppppp/8/8/
|
|
45
|
+
fen: "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
|
|
46
|
+
size: 480,
|
|
47
|
+
style: "cburnett",
|
|
48
|
+
colors: {
|
|
49
|
+
lightSquare: "#EEEED2",
|
|
50
|
+
darkSquare: "#769656",
|
|
51
|
+
highlight: "rgba(246, 246, 105, 0.6)",
|
|
52
|
+
},
|
|
53
|
+
highlightSquares: ["e2", "e4"],
|
|
24
54
|
});
|
|
25
55
|
|
|
26
56
|
await writeFile("board.png", png);
|
|
@@ -28,19 +58,13 @@ await writeFile("board.png", png);
|
|
|
28
58
|
|
|
29
59
|
`renderChess(...)` returns a `Promise<Buffer>` containing PNG data.
|
|
30
60
|
|
|
31
|
-
## Example Output
|
|
32
|
-
|
|
33
|
-
Example board rendered with a built-in theme:
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
61
|
## Installation
|
|
38
62
|
|
|
39
63
|
```bash
|
|
40
64
|
npm install chess2img
|
|
41
65
|
```
|
|
42
66
|
|
|
43
|
-
|
|
67
|
+
### Node And Canvas Requirements
|
|
44
68
|
|
|
45
69
|
- Node.js `18+`
|
|
46
70
|
- native build support for `canvas`
|
|
@@ -48,116 +72,60 @@ npm install chess2img
|
|
|
48
72
|
|
|
49
73
|
If `canvas` fails to install, verify your system packages first. The library ships `canvas` as a direct dependency, but native prerequisites still need to exist on the host.
|
|
50
74
|
|
|
51
|
-
##
|
|
75
|
+
## Basic Usage
|
|
52
76
|
|
|
53
|
-
|
|
54
|
-
const { ChessImageGenerator } = require("chess2img");
|
|
55
|
-
|
|
56
|
-
async function main() {
|
|
57
|
-
const generator = new ChessImageGenerator({
|
|
58
|
-
size: 800,
|
|
59
|
-
style: "alpha",
|
|
60
|
-
});
|
|
61
|
-
|
|
62
|
-
await generator.loadPGN("1. e4 e5 2. Nf3 Nc6 3. Bb5 a6");
|
|
63
|
-
generator.setHighlights(["e4", "e5"]);
|
|
64
|
-
|
|
65
|
-
const buffer = await generator.toBuffer();
|
|
66
|
-
await generator.toFile("board.png");
|
|
67
|
-
}
|
|
68
|
-
|
|
69
|
-
main().catch(console.error);
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
## TypeScript Usage
|
|
77
|
+
### Functional API
|
|
73
78
|
|
|
74
79
|
```ts
|
|
75
|
-
import {
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
[null, null, null, null, null, null, null, null],
|
|
83
|
-
[null, null, null, null, null, null, null, null],
|
|
84
|
-
[null, null, null, null, null, null, null, null],
|
|
85
|
-
["P", "P", "P", "P", "P", "P", "P", "P"],
|
|
86
|
-
["R", "N", "B", "Q", "K", "B", "N", "R"],
|
|
87
|
-
],
|
|
88
|
-
size: 640,
|
|
89
|
-
style: "cburnett",
|
|
80
|
+
import { writeFile } from "node:fs/promises";
|
|
81
|
+
import { renderChess } from "chess2img";
|
|
82
|
+
|
|
83
|
+
const png = await renderChess({
|
|
84
|
+
fen: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
|
|
85
|
+
size: 480,
|
|
86
|
+
style: "merida",
|
|
90
87
|
});
|
|
91
88
|
|
|
92
|
-
|
|
93
|
-
await generator.loadFEN("4k3/8/8/3p4/4P3/8/8/4K3 w - - 0 1");
|
|
94
|
-
await generator.toFile("board.png");
|
|
89
|
+
await writeFile("board.png", png);
|
|
95
90
|
```
|
|
96
91
|
|
|
97
|
-
## API
|
|
98
|
-
|
|
99
92
|
### Class API
|
|
100
93
|
|
|
101
94
|
```ts
|
|
95
|
+
import { ChessImageGenerator } from "chess2img";
|
|
96
|
+
|
|
102
97
|
const generator = new ChessImageGenerator({
|
|
103
98
|
size: 800,
|
|
104
|
-
style: "
|
|
105
|
-
flipped: false,
|
|
99
|
+
style: "alpha",
|
|
106
100
|
});
|
|
107
101
|
|
|
108
|
-
await generator.
|
|
109
|
-
generator.setHighlights(["e4", "
|
|
102
|
+
await generator.loadPGN("1. e4 e5 2. Nf3 Nc6 3. Bb5 a6");
|
|
103
|
+
generator.setHighlights(["e4", "e5"]);
|
|
110
104
|
|
|
111
|
-
const buffer = await generator.toBuffer();
|
|
112
105
|
await generator.toFile("board.png");
|
|
113
106
|
```
|
|
114
107
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
- `loadFEN(fen: string): Promise<void>`
|
|
118
|
-
- `loadPGN(pgn: string): Promise<void>`
|
|
119
|
-
- `loadBoard(board: BoardArray): Promise<void>`
|
|
120
|
-
- `setHighlights(squares: Square[]): void`
|
|
121
|
-
- `clearHighlights(): void`
|
|
122
|
-
- `toBuffer(): Promise<Buffer>`
|
|
123
|
-
- `toFile(filePath: string): Promise<void>`
|
|
108
|
+
### JavaScript Usage
|
|
124
109
|
|
|
125
|
-
|
|
110
|
+
```js
|
|
111
|
+
const { renderChess } = require("chess2img");
|
|
112
|
+
const { writeFile } = require("node:fs/promises");
|
|
126
113
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
114
|
+
async function main() {
|
|
115
|
+
const png = await renderChess({
|
|
116
|
+
fen: "4k3/8/8/8/8/8/8/4K3 w - - 0 1",
|
|
117
|
+
style: "merida",
|
|
118
|
+
});
|
|
131
119
|
|
|
132
|
-
|
|
120
|
+
await writeFile("board.png", png);
|
|
121
|
+
}
|
|
133
122
|
|
|
134
|
-
|
|
135
|
-
const buffer = await renderChess({
|
|
136
|
-
fen,
|
|
137
|
-
size: 800,
|
|
138
|
-
style: "merida",
|
|
139
|
-
});
|
|
123
|
+
main().catch(console.error);
|
|
140
124
|
```
|
|
141
125
|
|
|
142
|
-
|
|
126
|
+
## Built-In Themes
|
|
143
127
|
|
|
144
|
-
-
|
|
145
|
-
- `pgn`
|
|
146
|
-
- `board`
|
|
147
|
-
|
|
148
|
-
## Options Reference
|
|
149
|
-
|
|
150
|
-
- `size`: board size in pixels
|
|
151
|
-
- `padding`: `[top, right, bottom, left]`
|
|
152
|
-
- `flipped`: render from black's perspective when `true`
|
|
153
|
-
- `style`: built-in theme alias
|
|
154
|
-
- `theme`: built-in theme name, registered custom theme name, or inline `ThemeDefinition`
|
|
155
|
-
- `highlightSquares`: array of algebraic squares such as `["e4", "d5"]`
|
|
156
|
-
- `colors.lightSquare`
|
|
157
|
-
- `colors.darkSquare`
|
|
158
|
-
- `colors.highlight`
|
|
159
|
-
|
|
160
|
-
## Built-In Styles
|
|
128
|
+
Bundled built-in themes:
|
|
161
129
|
|
|
162
130
|
- `merida`
|
|
163
131
|
- `alpha`
|
|
@@ -165,6 +133,8 @@ const buffer = await renderChess({
|
|
|
165
133
|
- `cheq`
|
|
166
134
|
- `leipzig`
|
|
167
135
|
|
|
136
|
+
Built-in themes are vendored in-package and render through the same theme pipeline as custom themes.
|
|
137
|
+
|
|
168
138
|
## Custom Themes
|
|
169
139
|
|
|
170
140
|
Register a reusable theme globally:
|
|
@@ -176,7 +146,7 @@ registerTheme({
|
|
|
176
146
|
name: "custom-theme",
|
|
177
147
|
displayName: "Custom Theme",
|
|
178
148
|
license: "MIT",
|
|
179
|
-
attribution: "
|
|
149
|
+
attribution: "Theme author or package source",
|
|
180
150
|
pieces: {
|
|
181
151
|
// 12 canonical pieces required
|
|
182
152
|
},
|
|
@@ -193,7 +163,54 @@ Custom themes may use either:
|
|
|
193
163
|
- `svg` assets
|
|
194
164
|
- `png` assets
|
|
195
165
|
|
|
196
|
-
##
|
|
166
|
+
## API
|
|
167
|
+
|
|
168
|
+
### Public Exports
|
|
169
|
+
|
|
170
|
+
- `new ChessImageGenerator(options?)`
|
|
171
|
+
- `renderChess(options)`
|
|
172
|
+
- `registerTheme(theme)`
|
|
173
|
+
|
|
174
|
+
### Functional API
|
|
175
|
+
|
|
176
|
+
`renderChess(...)` accepts exactly one position source:
|
|
177
|
+
|
|
178
|
+
- `fen`
|
|
179
|
+
- `pgn`
|
|
180
|
+
- `board`
|
|
181
|
+
|
|
182
|
+
### Class API
|
|
183
|
+
|
|
184
|
+
Methods:
|
|
185
|
+
|
|
186
|
+
- `loadFEN(fen: string): Promise<void>`
|
|
187
|
+
- `loadPGN(pgn: string): Promise<void>`
|
|
188
|
+
- `loadBoard(board: BoardArray): Promise<void>`
|
|
189
|
+
- `setHighlights(squares: Square[]): void`
|
|
190
|
+
- `clearHighlights(): void`
|
|
191
|
+
- `toBuffer(): Promise<Buffer>`
|
|
192
|
+
- `toFile(filePath: string): Promise<void>`
|
|
193
|
+
|
|
194
|
+
Semantics:
|
|
195
|
+
|
|
196
|
+
- `setHighlights` replaces the current highlight set
|
|
197
|
+
- `clearHighlights` removes all highlights
|
|
198
|
+
- loading a new position clears highlights
|
|
199
|
+
- constructor defaults persist across position loads
|
|
200
|
+
|
|
201
|
+
### Options
|
|
202
|
+
|
|
203
|
+
- `size`: board size in pixels
|
|
204
|
+
- `padding`: `[top, right, bottom, left]`
|
|
205
|
+
- `flipped`: render from black's perspective when `true`
|
|
206
|
+
- `style`: built-in theme alias
|
|
207
|
+
- `theme`: built-in theme name, registered custom theme name, or inline `ThemeDefinition`
|
|
208
|
+
- `highlightSquares`: array of algebraic squares such as `["e4", "d5"]`
|
|
209
|
+
- `colors.lightSquare`
|
|
210
|
+
- `colors.darkSquare`
|
|
211
|
+
- `colors.highlight`
|
|
212
|
+
|
|
213
|
+
### Errors
|
|
197
214
|
|
|
198
215
|
The library exports:
|
|
199
216
|
|
|
@@ -203,30 +220,8 @@ The library exports:
|
|
|
203
220
|
- `RenderError`
|
|
204
221
|
- `IOError`
|
|
205
222
|
|
|
206
|
-
##
|
|
207
|
-
|
|
208
|
-
- `core` parses and validates chess position input into a canonical board model
|
|
209
|
-
- `themes` validates, registers, and resolves built-in or custom themes
|
|
210
|
-
- `render` rasterizes SVG or PNG theme assets and renders PNG output through `canvas`
|
|
211
|
-
- `api` orchestrates parsing, theme resolution, rendering, and file output
|
|
212
|
-
|
|
213
|
-
## Migration From `chess-image-generator`
|
|
214
|
-
|
|
215
|
-
| Old | New | Difference |
|
|
216
|
-
| --- | --- | --- |
|
|
217
|
-
| `loadArray` | `loadBoard` | renamed for clarity |
|
|
218
|
-
| `highlightSquares([...])` | `setHighlights([...])` | replacement semantics are explicit |
|
|
219
|
-
| `generateBuffer()` | `toBuffer()` | same role, new naming |
|
|
220
|
-
| `generatePNG(path)` | `toFile(path)` | IO is explicit in the API name |
|
|
221
|
-
| `style` only | `style` or `theme` | `theme` is the canonical path |
|
|
222
|
-
|
|
223
|
-
## Troubleshooting
|
|
224
|
-
|
|
225
|
-
- `canvas` install failures usually indicate missing native prerequisites on the host
|
|
226
|
-
- `ValidationError` from `renderChess` usually means multiple position inputs were provided or an option shape is invalid
|
|
227
|
-
- `ThemeError` usually indicates an unknown theme name or an incomplete custom theme definition
|
|
228
|
-
- `RenderError` usually indicates asset decoding/rasterization problems
|
|
223
|
+
## License
|
|
229
224
|
|
|
230
|
-
|
|
225
|
+
`chess2img` is distributed under the MIT license in package metadata.
|
|
231
226
|
|
|
232
227
|
Bundled built-in themes are derived from the upstream `andyruwruw/chess-image-generator` resource packs and are vendored in-package for deterministic installs. Provenance and licensing notes live in [ATTRIBUTION.md](./ATTRIBUTION.md).
|
|
Binary file
|