6a050339f7
Pasted captions with swapped or non-numeric bbox values produced negative or NaN regions, so the editor could not select them. Coordinates are now swapped and clamped to the 0-1000 range from the Ideogram 4 caption schema, and unreadable bboxes keep the non-overlapping grid slot for that element. Saved regions with NaN coordinates are dropped on restore. Co-authored-by: AE <by-ae@users.noreply.github.com> Co-authored-by: Cursor Agent <cursoragent@cursor.com>
132 lines
6.7 KiB
Markdown
132 lines
6.7 KiB
Markdown
# ComfyUI-ByAE-IdeogramTools
|
|
|
|
An improved version of [Kijai](https://github.com/kijai)'s excellent **Ideogram 4 Prompt Builder** from [ComfyUI-KJNodes](https://github.com/kijai/ComfyUI-KJNodes). Same node (literally built on top of), replacement drop in, but with workflow and live editor QoL layered on top.
|
|
|
|
I may add other Ideogram 4 tools here in future, hence the name.
|
|
|
|
|
|
|
|
## Nodes
|
|
|
|
| Node | Role |
|
|
|------|------|
|
|
| **Ideogram 4 Prompt Builder Pro (based on the KJ node)** | Main visual prompt builder |
|
|
| **Ideogram 4 Prompt Builder Pro - Preview BG Update** | Feeds a workflow image into the builder's canvas background |
|
|
|
|
## Improvements over the KJ builder
|
|
|
|
- **Character/Object store** — Save, Save As, and Load named characters/objects
|
|
- **Save/Load entire scenes** — save and restore full scenes (boxes, overview, aesthetic, style colors, and the rest); add imported boxes (selected by default) or wipe and replace the entire scene
|
|
- **Multi-select (Shift+click individual or Shift-drag to select and move/scale them all)** — Shift+drag a selection rectangle; any partially overlapping box is included, the entire selection can be moved around or scaled uniformly on the sides or corners. Shift+click a box to add or remove it from the selection
|
|
- **Live background image** — Preview BG Update pushes a workflow image onto the builder canvas; opacity slider blends it over black
|
|
- **Copy and paste** — Ctrl+C / Ctrl+V for selected boxes (geometry and field data)
|
|
- **Scale mode on resize** — center, corner anchors, or stretch when canvas width/height change. Non-stretch modes scale from the bounding box of your regions and crop unused canvas space when narrowing
|
|
- **Paste JSON resize dialog** — when pasting layout JSON, choose how the source canvas was sized (don't care / same / dimensions / aspect ratio) and it will perform content-aware scaling of the pasted regions.
|
|
- **Width and height outputs** — separate INT sockets for downstream workflow use
|
|
- **Update Size button** — width/height edits apply only when you click Update Size (with chosen scale mode).
|
|
|
|
## Installation
|
|
|
|
1. Clone into `ComfyUI/custom_nodes/`:
|
|
```bash
|
|
# open a terminal in the ComfyUI/custom_nodes directory
|
|
git clone https://github.com/by-ae/ComfyUI-ByAE-IdeogramTools.git
|
|
```
|
|
2. Restart ComfyUI
|
|
|
|
**ComfyUI-KJNodes does not need to be installed.**
|
|
|
|
## Usage
|
|
|
|
After installation, the nodes appear in the node menu under **ByAE/Ideogram**:
|
|
|
|
1. **Ideogram 4 Prompt Builder Pro** - Add this node to start building your prompt visually
|
|
2. **Preview BG Update** (optional) - Connect a workflow image and the builder's `guid` output to display it as the canvas background
|
|
|
|
The builder outputs a structured JSON prompt compatible with Ideogram 4's API format, plus a preview image showing your layout.
|
|
|
|
## Troubleshooting
|
|
|
|
### Nodes don't appear in the menu
|
|
|
|
- Ensure ComfyUI restarted completely after cloning
|
|
- Check the ComfyUI console for import errors
|
|
- Verify the folder is named `ComfyUI-ByAE-IdeogramTools` (not `ComfyUI-ByAE-IdeogramTools-main`)
|
|
- Make sure you are running a recent version of ComfyUI (the comfy_api module is required)
|
|
|
|
### "Failed to load stores" or route errors in console
|
|
|
|
This is usually harmless. The store routes register on startup, and if they fail, character/object/scene save features may not work, but the builder itself will function normally. Check file permissions on your ComfyUI user directory.
|
|
|
|
**Store location:** Character, object, and scene presets are stored in `<ComfyUI user directory>/byae-ideogram-tools/` as JSON files (`characters.json`, `objects.json`, `scenes.json`).
|
|
|
|
**Unicode support:** Preset names can include Unicode characters (e.g. 角色, Персонаж, Émilie). Names must start with a letter, number, or underscore, and can contain letters, numbers, spaces, underscores, and hyphens (up to 64 characters).
|
|
|
|
**Corrupt file recovery:** If a store file becomes corrupted (invalid JSON), it will be automatically moved to a backup file named `<bucket>.json.corrupt-<timestamp>` and the bucket will be treated as empty. Other buckets continue to work normally, and saves to the recovered bucket will work immediately.
|
|
|
|
### Failed to save character/object/scene
|
|
|
|
- Check the browser console (F12) for detailed error messages
|
|
- Verify the name meets requirements: starts with letter/number/underscore, contains only letters, numbers, spaces, underscores, or hyphens
|
|
- Ensure the ComfyUI user directory is writable
|
|
- Try a shorter name (max 64 characters)
|
|
|
|
### Background image not updating
|
|
|
|
- Verify the `guid` output from the builder is connected to Preview BG Update's `guid` input
|
|
- Check the ComfyUI console for a line starting with `[ByAE Ideogram BG]`. A failed save names the reason: no image, an empty or invalid guid, an image that could not be converted, or a disk write error
|
|
- The temp directory must be writable (usually `ComfyUI/temp`)
|
|
|
|
### Saved workflows break after updating
|
|
|
|
Node names and internal IDs are stable. If a workflow breaks, check:
|
|
- Width/height inputs are valid numbers (64-16384)
|
|
- JSON import input (if used) contains valid JSON
|
|
- No custom modifications were made to widget names
|
|
|
|
For bugs or feature requests, please open an issue on GitHub.
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Install test dependencies
|
|
pip install pytest pytest-asyncio aiohttp
|
|
|
|
# Run all tests
|
|
python -m pytest tests/ -v
|
|
|
|
# Region layout helpers (no Python dependencies)
|
|
node --test tests/caption_layout.test.js
|
|
|
|
# Run specific test file
|
|
python -m pytest tests/test_store.py -v
|
|
```
|
|
|
|
### JavaScript Linting
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run linter
|
|
npm run lint
|
|
```
|
|
|
|
## API
|
|
|
|
The extension exposes HTTP routes for programmatic access to the character/object/scene store:
|
|
|
|
- **GET** `/byae/ideogram/stores` — Load all stores (returns `{"characters": {...}, "objects": {...}, "scenes": {...}}`)
|
|
- **PUT** `/byae/ideogram/stores/{bucket}/{name}` — Save an entry (body: JSON object; bucket: `characters`, `objects`, or `scenes`)
|
|
- **DELETE** `/byae/ideogram/stores/{bucket}/{name}` — Delete an entry (returns 404 if not found, 200 on success)
|
|
|
|
## License
|
|
|
|
This project is a derivative work based on **ComfyUI-KJNodes**, in particular `Ideogram4PromptBuilderKJ` and shared frontend utilities.
|
|
|
|
- Licensed under **GNU General Public License v3.0** — same as [ComfyUI-KJNodes](https://github.com/kijai/ComfyUI-KJNodes). See [LICENSE](LICENSE).
|
|
- Copyright for the original Ideogram 4 Prompt Builder and related KJNodes code belongs to [Kijai](https://github.com/kijai) and other KJNodes contributors.
|
|
- Enhancements in this repository are provided under the same GPL-3.0 terms. If you distribute this pack, keep the license file and preserve appropriate attribution to Kijai / ComfyUI-KJNodes.
|