78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
# ComfyUI Compass Paths
|
|
|
|
A pair of ComfyUI custom nodes for loading and saving images using a structured compass-direction directory convention. Organize your project frames by direction (n, ne, e, se, s, sw, w, nw) and modality (image, depth, openpose), then load or save them directly within your workflows.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
input/ or output/
|
|
<base_path>/ e.g., "rosella/walk"
|
|
[direction]/ optional: n, ne, e, se, s, sw, w, nw
|
|
<modality>/ image, depth, or openpose
|
|
frame_0001.png
|
|
frame_0002.png
|
|
...
|
|
```
|
|
|
|
With direction: `output/rosella/walk/s/depth/frame_0001.png`
|
|
Without direction: `input/rosella/walk/image/frame_0001.png`
|
|
|
|
## Nodes
|
|
|
|
### Compass Image Loader
|
|
Loads images from a compass-path directory tree under ComfyUI's `input/` or `output/`. Auto-discovers valid directory paths, supports single-frame or batch loading with optional resize, and outputs image data along with path information for downstream nodes.
|
|
|
|
**Inputs**
|
|
- **src_base** — Choose `input` or `output` as the root directory
|
|
- **directory** — Auto-populated path picker that drills into your project structure (e.g., `rosella/walk`). Hierarchical autocomplete lets you navigate deep folder trees segment by segment
|
|
- **direction** — One of 8 compass directions or blank. Determines whether a direction subfolder is included in the resolved path
|
|
- **modality** — `image`, `depth`, or `openpose`. The final subfolder beneath the base (and optional direction)
|
|
- **frame** — 0-based frame index, or leave blank to load all images as a batch
|
|
- **width** / **height** — Resize controls. Zero = no resize on that dimension. One non-zero = proportional scale. Both non-zero = cover + center-crop
|
|
|
|
**Outputs**
|
|
- **IMAGE** — Tensor `(B, H, W, C)`. Batch size 1 for single frame, N for batch
|
|
- **path** — Absolute filesystem path to the loaded file or directory
|
|
- **direction** — The resolved direction string. Chainable into another loader's `direction_override` input
|
|
- **width** / **height** — Final pixel dimensions after any resizing
|
|
- **frame_count** — Number of frames in the output batch
|
|
|
|
### Save Compass Images
|
|
Saves incoming ComfyUI images to the compass-path directory structure under ComfyUI's `output/`, with auto-numbered filenames and embedded workflow metadata. The mirror node to the loader — what you load with one, you can save with the other.
|
|
|
|
**Inputs**
|
|
- **images** — Standard ComfyUI image tensor batch
|
|
- **base_path** — Subdirectory under `output/` (e.g., `rosella/walk`)
|
|
- **direction** — Compass direction or blank
|
|
- **modality** — `image`, `depth`, or `openpose`
|
|
- **direction_override** — Optional string input that overrides the direction widget. Connect a loader's `direction` output here to chain both nodes on the same direction
|
|
|
|
## Chaining Direction
|
|
|
|
Both nodes support a `direction_override` input that takes precedence over the direction dropdown. This lets you chain multiple loaders (or loader-to-saver) so they all share the same compass direction from one selection point.
|
|
|
|
```
|
|
[Loader1]--direction--> [Loader2 . direction_override]
|
|
\--[Saver . direction_override]
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
cd ComfyUI/custom_nodes/
|
|
git clone https://github.com/<your-repo>/ComfyUI-compass-paths.git
|
|
```
|
|
|
|
Restart ComfyUI. The nodes will be available under **Image > Loaders** and **Image > Compass**.
|
|
|
|
## Resize Modes
|
|
|
|
| width | height | Behavior |
|
|
|-------|--------|----------|
|
|
| 0 | 0 | No resize |
|
|
| N | 0 | Scale proportionally to fit width |
|
|
| 0 | N | Scale proportionally to fit height |
|
|
| W | H | Scale to cover both dimensions, then center-crop |
|
|
|
|
Resampling uses Lanczos for maximum quality.
|