remove claude.md
This commit is contained in:
dreevelle
@@ -1,157 +0,0 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## What this is
|
||||
|
||||
A single-file ComfyUI custom node package. All code lives in `__init__.py`; there
|
||||
is no build step, test suite, or linter config. Three nodes —
|
||||
`ResolutionPreset`, `ResolutionSelectorMP` and `ResolutionAlignToGrid` — all pure
|
||||
integer maths with no torch/numpy involvement.
|
||||
|
||||
`ResolutionPreset`'s combo options are **generated at import time** by
|
||||
`build_presets()` from the same `lattice_step()` the solver uses, so the list can
|
||||
never disagree with `solve_exact()`. Do not hand-edit resolutions into it. The
|
||||
per-ratio grid choice (coarsest alignment yielding `PRESET_MIN_ENTRIES` sizes)
|
||||
exists because fine-lattice ratios like 1:1 have L=16 and would otherwise emit
|
||||
~105 entries; changing `PRESET_MIN_MP` / `PRESET_MAX_MP` / `PRESET_MIN_ENTRIES`
|
||||
silently reshapes every label, and **labels are the public API** — a saved
|
||||
workflow stores the selected label string, so altering the format or the tuning
|
||||
constants breaks existing graphs.
|
||||
|
||||
Registered through ComfyUI's **V3 schema API**, not the legacy
|
||||
`NODE_CLASS_MAPPINGS` dict: `comfy_entrypoint()` returns a `ComfyExtension` whose
|
||||
`get_node_list()` yields `IO.ComfyNode` subclasses. Inputs are declared in
|
||||
`define_schema()` and arrive as named kwargs to `execute()`.
|
||||
|
||||
## Local environment
|
||||
|
||||
- ComfyUI checkout: `/home/dreevelle/comfy/ComfyUI`
|
||||
- Python venv: `/home/dreevelle/comfy-env/bin/python`
|
||||
- The package is published, and `ComfyUI/custom_nodes/comfyui-resolution-tools`
|
||||
(lowercase, the registry id) is a **ComfyUI-Manager install** that tracks
|
||||
registry releases. This working tree is not wired into ComfyUI.
|
||||
|
||||
To test a change before releasing it, symlink this tree in under its CamelCase
|
||||
name so it doesn't collide with the Manager install:
|
||||
|
||||
```bash
|
||||
ln -sfn /home/dreevelle/Projects/ComfyUI-ResolutionTools \
|
||||
/home/dreevelle/comfy/ComfyUI/custom_nodes/ComfyUI-ResolutionTools
|
||||
```
|
||||
|
||||
**Remove that symlink before doing anything in ComfyUI-Manager for this
|
||||
package.** Manager's remove/replace path does `shutil.rmtree` on the *resolved*
|
||||
path, so it deletes the symlink target's contents instead of unlinking — on
|
||||
2026-08-09 that wiped this working tree, `.git` included, and it had to be
|
||||
restored by re-cloning. Commit and push before any Manager operation, and never
|
||||
leave a symlinked dev copy in place while installing or updating the published
|
||||
version.
|
||||
|
||||
## Verifying changes
|
||||
|
||||
`__init__.py` imports `comfy_api.latest` at module scope, so it needs ComfyUI on
|
||||
`sys.path` — but the maths functions are module-level and dependency-free, so
|
||||
they can be exercised directly:
|
||||
|
||||
```bash
|
||||
cd /home/dreevelle/comfy/ComfyUI && PYTHONPATH=/home/dreevelle/comfy/ComfyUI \
|
||||
/home/dreevelle/comfy-env/bin/python -c "
|
||||
import importlib.util
|
||||
spec = importlib.util.spec_from_file_location('rt', '/home/dreevelle/Projects/ComfyUI-ResolutionTools/__init__.py')
|
||||
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
|
||||
print(m.solve_exact(9, 16, 16, 2.36e6)) # -> (1152, 2048)
|
||||
"
|
||||
```
|
||||
|
||||
Two invariants any change to `solve_exact` must preserve, and which are worth
|
||||
re-fuzzing over random `(ratio, alignment, target)` triples:
|
||||
|
||||
1. `width % alignment == 0 and height % alignment == 0`
|
||||
2. `width * h_ratio == height * w_ratio` (ratio held exactly, no drift)
|
||||
|
||||
Known-good anchors: `9:16 @ m=16, 2.36 MP -> 1152x2048`;
|
||||
`16:9 @ m=32, 1.33 MP -> 1536x864`; `21:9 @ m=16, 2.37 MP -> 2352x1008`.
|
||||
|
||||
## Why the maths is what it is
|
||||
|
||||
**Real megapixels.** Core's `comfy_extras/nodes_resolution.py:78` uses
|
||||
`megapixels * 1024 * 1024`. That's the SDXL-era convention where "1 MP" meant
|
||||
1024x1024. This package deliberately diverges to `* 1_000_000`. Do not "fix"
|
||||
this to match core — the divergence is the point, and the README documents it.
|
||||
|
||||
**Lattice solving.** `lattice_step()` computes the smallest scale increment that
|
||||
keeps both axes on the alignment grid while holding an exact ratio. Core rounds
|
||||
each axis independently, which drifts the ratio (9:16 at 2.36 MP becomes 0.5649
|
||||
instead of 0.5625). `solve_nearest()` preserves core's behaviour for when the
|
||||
lattice is too coarse; it is opt-in via `exact_ratio=False`.
|
||||
|
||||
**Alignment = VAE spatial downscale x DiT patch size.** Verified against the
|
||||
ComfyUI source rather than assumed:
|
||||
|
||||
- Krea 2 -> 16. `latent_formats.LatentFormat.spacial_downscale_ratio = 8`
|
||||
(inherited by `Wan21`, which `supported_models.Krea2` uses) x `patch=2` in
|
||||
`comfy/ldm/krea2/model.py`.
|
||||
- MiniMax H3 -> 32. `latent_formats.MiniMaxH3Video.spacial_downscale_ratio = 16`
|
||||
x `patch_size=(1, 2, 2)` in `comfy/ldm/minimax/model.py`.
|
||||
- SDXL/SD1.5 -> 64. UNet, no patchify; three downsample stages on an 8x VAE.
|
||||
|
||||
The failure mode when unaligned is `comfy.ldm.common_dit.pad_to_patch_size`,
|
||||
which pads with `padding_mode="circular"` and appends only at the end — hence a
|
||||
bottom/right band, never top/left. If a future model changes VAE or patch size,
|
||||
the alignment table in the README and `ALIGNMENT_TOOLTIP` both need updating.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Version is duplicated in `__version__` (`__init__.py`) and `[project].version`
|
||||
(`pyproject.toml`) — bump both.
|
||||
- `dependencies` stays empty; this package is stdlib-only by design.
|
||||
- Node IDs (`ResolutionSelectorMP`, `ResolutionAlignToGrid`) are the public API.
|
||||
Renaming one breaks every saved workflow that uses it.
|
||||
|
||||
## Releasing
|
||||
|
||||
Intended for the Comfy Registry as `comfyui-resolution-tools` under publisher
|
||||
`dreevelle`, same setup as ComfyUI-FastImageSequence.
|
||||
|
||||
**Changing `[project].version` in `pyproject.toml` on `main` publishes a
|
||||
release.** `.github/workflows/publish_action.yml` watches that path and runs
|
||||
`Comfy-Org/publish-node-action` with the `REGISTRY_ACCESS_TOKEN` repo secret.
|
||||
Don't touch the version field unless a release is intended; republishing an
|
||||
existing version fails with `400 The node version already exists`.
|
||||
|
||||
`.comfyignore` keeps `CLAUDE.md` and `.github/` out of the published archive.
|
||||
`comfy node validate` runs the registry checks locally; `comfy node pack`
|
||||
produces the exact archive that would be uploaded.
|
||||
|
||||
`assets/icon.png` is the registry icon, pointed at by `[tool.comfy] Icon` as a
|
||||
raw GitHub URL on `main`. The registry stores the *URL*, not the bytes, and the
|
||||
Manager hotlinks it, so **replacing this file on `main` restyles every card with
|
||||
no republish**. Only changing the URL needs a version bump, because `icon` is
|
||||
node-level metadata written as a side effect of publishing a version.
|
||||
|
||||
The background is **transparent on purpose**. The frontend's `PackBanner` draws
|
||||
the icon twice into a 7:3 box — once as a backdrop, `bg-cover` plus `blur(10px)`
|
||||
at `opacity-30`, and once `object-contain` on top. An opaque icon therefore shows
|
||||
as a hard rectangle: `bg-cover` crops to the centre and zooms ~2.3x, so it samples
|
||||
mostly glow and lifts the surround to ~47, while the contained copy still shows
|
||||
the icon's own near-black corners at ~17. Deriving alpha from luminance removes
|
||||
the edge completely, and it is the right derivation because the artwork is
|
||||
additive glow on near-black. The cost, accepted deliberately, is that the pale
|
||||
mark washes out on ComfyUI's light theme.
|
||||
|
||||
Regenerate from the brand original, capped at the registry's 400x400 square
|
||||
maximum. Downscale in linear light; the naive sRGB-space resize dulls the ring
|
||||
stroke and blurs the bar separations inside the D:
|
||||
|
||||
```bash
|
||||
magick ~/Projects/alora/dev/assets/brand/dreevelle_pfp.png \
|
||||
-colorspace RGB -filter Lanczos -resize 400x400 -colorspace sRGB \
|
||||
\( +clone -grayscale Rec601Luma -level 7.45%,100% \) \
|
||||
-alpha off -compose CopyOpacity -composite \
|
||||
-background none -alpha Background -strip assets/icon.png
|
||||
oxipng -o max --strip safe assets/icon.png
|
||||
```
|
||||
|
||||
Do not set `[tool.comfy] Banner`. `PackBanner` resolves `banner_url || icon`, so
|
||||
a banner *replaces* the mark rather than sitting behind it.
|
||||
Reference in New Issue
Block a user