RES4SHO

High-frequency detail sampling for ComfyUI: a family of exponential-integrator samplers with spectral high-frequency emphasis (HFE), a set of detail-biased S-curve schedulers, and two custom-sampling nodes — Sigma Curves for per-step sigma editing and Manual Sampler for tunable, savable sampler presets.

Installation

Clone or copy this folder into your ComfyUI custom_nodes directory:

ComfyUI/
  custom_nodes/
    RES4SHO/
      __init__.py
      sampling.py
      nodes.py
      manual_sampler.py
      ...

Restart ComfyUI. The samplers and schedulers below will appear in every KSampler / KSamplerAdvanced / SamplerCustom dropdown. The two custom nodes appear under sampling/custom_sampling/.

What changed recently

If you're upgrading from an earlier version, note:

• hfe3_*, hfe4_*, hfe5_* (and their _auto siblings) are removed. Higher-stage integration is now reachable from any hfe_* sampler via the Manual Sampler node by setting stages=3..5. One sampler entry in the dropdown, your choice of stages.
• karras_tan is removed. Use atan_focused or atan_steep for similar shapes, or build a hybrid via the Sigma Curves node.
• Sigma Curves and Manual Sampler are new — see their sections below.
• New schedulers: cosine, kumaraswamy, laplacian, linear, plus asymmetric atan_structure / atan_detail / logistic_structure / logistic_detail. (ComfyUI's built-in beta is left alone — the Kumaraswamy curve we ship is closed-form and a different shape, so it lives under its own name.)

Old names are explicitly unregistered on load, so saved workflows that reference them will need to be repointed at the current equivalents.

Samplers

All samplers are exponential integrators with phi-function coefficients. The HFE enhancement extracts high-frequency detail from inter-stage correction deltas via a 3×3 spatial high-pass filter and re-injects it with configurable strength.

Fixed-strength HFE presets

Eight strength levels, two-stage integrator by default. Manual Sampler can promote any of them to 3–5 stages for higher integration accuracy.

Sampler	Description
hfe_s1 … hfe_s8	s1 = no emphasis (clean res_2s), s8 = maximum sharpness

Adaptive HFE

Sampler	Description
hfe_auto	Per-step adaptive eta driven by sigma envelope and content gating; defaults to 2 stages, stages=3..5 via Manual Sampler

How the adaptive gate works:

• Sigma envelope (smoothstep) — suppresses emphasis at high noise (early steps), full strength in the detail-forming range.
• Content gate — reduces emphasis when the model correction is already HF-rich; increases it when the correction is smooth and needs boosting.

Experimental modes (hfx_*)

Ten enhancement modes, each operating in a different mathematical domain. All use a 2-stage exponential integrator base. Each has four graduated strength presets (_s1 … _s4) on top of the bare entry, e.g. hfx_sharp, hfx_sharp_s1 … hfx_sharp_s4.

Mode	Domain	Method
hfx_sharp	spatial	unsharp mask on eps_2 via 3×3 box blur residual
hfx_detail	spatial	post-step HF injection from denoised_2
hfx_boost	value	uniform eps_2 magnitude scaling (effective lying-sigma)
hfx_focus	value	power-law contrast on eps_2 magnitudes
hfx_spectral	frequency	FFT distance-based power-law boost
hfx_coherence	frequency	FFT phase gating between eps_1 and eps_2
hfx_momentum	temporal	EMA across steps on denoised differences
hfx_stochastic	temporal	structure-aware SDE noise injection (non-deterministic)
hfx_orthogonal	inter-stage	Gram-Schmidt projection of eps_2 orthogonal to eps_1
hfx_refine	inter-stage	curvature-adaptive emphasis using `

A per-step safety cap limits eps_2 modifications to a fixed fraction of its RMS, preventing compounding artifacts at the higher strength levels.

Schedulers

Detail-biased S-curve schedulers that concentrate step density in the detail-forming sigma range. All print an ASCII sigma chart to the console on first use.

Symmetric atan family

Scheduler	Concentration
atan_gentle	mild mid-sigma
atan_focused	moderate detail-range
atan_steep	aggressive detail-range

Alternative curves

Scheduler	Character
logistic	sigmoid S-curve, sharper transition than atan
cosine	smoothest, no inflection
kumaraswamy	closed-form beta-like CDF, asymmetric tails (distinct from ComfyUI's beta)
laplacian	exponential decay through mid sigmas
linear	reference baseline

Asymmetric two-stage curves

Independent slopes for the σ_max → σ_mid (structure) and σ_mid → σ_min (detail) halves of the schedule.

Scheduler	Bias
atan_structure	steep early stage, gentle late stage
atan_detail	gentle early stage, steep late stage
logistic_structure	logistic variant biased toward structure
logistic_detail	logistic variant biased toward detail

Sigma Curves node

Sigma Curves (category sampling/custom_sampling/schedulers) is a per-step sigma editor with a canvas widget. It outputs a SIGMAS tensor ready for SamplerCustom / SamplerCustomAdvanced.

What it does

• Pick any registered scheduler as the baseline — the canvas seeds with that scheduler's natural shape, computed against your actual connected model (BasicScheduler is run on the loader at the other end of the model socket, no need to run the workflow first).
• Each sampling step is one draggable control point on the curve. Drag to reshape; the y-axis is normalized to your model's [σ_min, σ_max].
• Right-drag the plot to select a step range; the toolbar's interpolation picker (linear, sigmoid, cosine, smoothstep, ease, exp, …) reshapes the selected range. Combine multiple curve archetypes in one schedule — e.g. sigmoid head, bezier middle, step tail.
• Header tag tells you whether the displayed shape came from your real model (✓ from your model) or a synthetic fallback (≈ approximate).

Toolbar controls

All controls live in a two-row in-canvas toolbar above the plot:

• Row 1: [interp ▾] [k tension] [apply curve] ‧ [select all] [clear] [flatten]
• Row 2: [reset to default] ‧ [save…] [load…] [delete…]

Hover any button for a one-line description in the header strip.

Saving and loading sigma curves

Saved curves are stored at presets/sigma_curves.json and registered as ComfyUI schedulers under the prefix sigma_curve_<name>. After saving, the new entry appears in every scheduler dropdown (KSampler, KSamplerAdvanced, BasicScheduler, …) once the frontend refreshes node defs — Sigma Curves triggers that refresh automatically.

At runtime, a saved curve resamples to whatever step count the consuming node requests and denormalizes against the active model's σ_min / σ_max, so a curve authored at 20 steps still works correctly at 8 or 60.

Manual Sampler node

Manual Sampler (category sampling/custom_sampling/samplers) wraps any registered k-diffusion sampler — the built-in ones, this repo's hfe_* / hfx_* variants, and any third-party samplers — with adjustable eta / s_noise / stages overrides. It outputs a SAMPLER ready for SamplerCustom.

Inputs

Input	Effect
base_sampler	Any sampler in the global registry
stages	Integrator stages (2–5). Honored by hfe_* and hfe_auto; silently dropped for samplers that don't accept it
eta_override	-1.0 = use the base sampler's default; 0 = deterministic; >0 = noisier / sharper. Hidden if the base sampler doesn't accept eta
s_noise	Noise scale for stochastic samplers; hidden if not accepted

The frontend probes the chosen base sampler's signature on each change and hides the widgets it doesn't accept, so the UI honestly reflects what's actually tunable.

Saving and loading samplers

Saved presets are stored at presets/manual_samplers.json and registered as ComfyUI samplers under the prefix manual_sampler_<name>. After saving, the new sampler appears in every sampler dropdown once the frontend refreshes node defs.

This is the supported path for creating new samplers in this repo: pick a known-good integrator, dial in eta / s_noise / stages, save with a name. There's no facility for hand-writing integrator code from a node — that's deliberate: every saved preset is guaranteed to be a sensible integrator that won't NaN.

Recommended combinations

Getting started

Goal	Sampler	Scheduler	Notes
General use	hfe_auto	atan_focused	Best all-rounder; adaptive emphasis handles most content
Subtle enhancement	hfe_s3	atan_gentle	Light touch, minimal artifact risk
Strong detail	hfe_s6	atan_steep	Noticeably sharper textures and edges
Maximum sharpness	hfe_s7 / hfe_s8	atan_steep	Aggressive — inspect for over-sharpening

By content type

Content	Sampler	Scheduler	Why
Portraits / faces	hfe_auto	atan_focused	Auto gate protects skin while sharpening eyes / hair / pores
Landscapes / nature	hfe_s5	atan_gentle	Mid-strength avoids over-enhancing skies
Architecture / hard surfaces	hfe_s7	atan_steep	Strong emphasis on edges and geometric detail
Text / UI renders	hfx_sharp	atan_steep	Spatial high-pass targets glyph edges
Fabric / organic texture	hfx_spectral	atan_focused	Frequency-domain emphasis across texture scales
Illustrations / anime	hfe_s4	atan_gentle	Light emphasis preserves flat shading

Higher integration accuracy

Wrap any hfe_* sampler in Manual Sampler with stages=3..5 for better ODE accuracy at low step counts or with difficult models:

Wrapped sampler	stages	Use case
hfe_auto	3	Solid balance of accuracy and speed
hfe_auto	4	High accuracy for complex prompts
hfe_auto	5	Maximum integration accuracy
hfe_s5	4	Fixed-strength detail + 4-stage accuracy

Save the configured Manual Sampler as a preset (e.g. hfe_auto_5stage) so it appears as manual_sampler_hfe_auto_5stage in every sampler dropdown without the wrapper node in your graph.

Experimental combinations

Sampler	Scheduler	Character
hfx_sharp	atan_focused	Spatial high-pass, good default experimental choice
hfx_spectral	atan_steep	Frequency-domain power-law sharpening
hfx_refine	atan_focused	Curvature-adaptive — sharpens where the model is least certain
hfx_coherence	atan_focused	Phase-coherence gating — amplifies structurally confident frequencies
hfx_orthogonal	atan_focused	Novel-information extraction via Gram-Schmidt
hfx_momentum	atan_gentle	Temporal accumulation — builds detail across steps
hfx_focus	atan_focused	Value-domain contrast — amplifies dominant correction directions
hfx_stochastic	atan_gentle	Stochastic texture injection — adds micro-variation
hfx_boost	atan_gentle	Uniform eps amplification — simple signal boost
hfx_detail	atan_focused	Post-step HF injection from denoised output

Scheduler pairings

Scheduler	Best with	Character
atan_gentle	low-strength samplers (s1–s4), stochastic modes	mild concentration, safe for any content
atan_focused	auto samplers, mid-strength presets (s4–s6)	balanced step density in detail range
atan_steep	high-strength samplers (s6–s8), architecture	aggressive detail-range concentration
logistic	any	sharper transition through detail range, flatter extremes
atan_structure / logistic_structure	high stage counts via Manual Sampler	bias toward composition / form
atan_detail / logistic_detail	high-strength HFE / HFX modes	bias toward texture / micro-detail
cosine	low-step counts	smoothest transition, no inflection

How it works

Base integrator. Multi-stage singlestep exponential integrator (res_Ns) with phi-function coefficients, giving exact treatment of exponential decay and higher-order corrections from intermediate evaluations. stages=2 is the default; 3..5 are reachable via Manual Sampler.

HFE enhancement (hfe_*). The inter-stage correction delta captures what the model reveals at lower noise — texture, edges, micro-structure. A spatial high-pass (residual after a 3×3 box blur in latent space) extracts the fine-detail component, which is re-injected with extra weight eta. This compounds across every step, with eta scheduled by sigma envelope (suppress at high noise) and content gate (boost smooth corrections, restrain HF-rich ones) for the _auto variant.

HFX modes (hfx_*). Each mode modifies the second-stage prediction (eps_2) using a different mathematical operation before the integrator update step. The 10 modes span 5 domains:

• Spatial — high-pass filtering (sharp), post-step HF injection (detail).
• Value — uniform scaling (boost), nonlinear power-law contrast (focus).
• Frequency — FFT power-law reshaping (spectral), inter-stage phase coherence gating (coherence).
• Temporal — EMA across steps (momentum), stochastic noise injection (stochastic).
• Inter-stage — Gram-Schmidt novel-component extraction (orthogonal), ODE curvature-adaptive gain (refine).

Schedulers. atan_* and logistic_* apply a curve function in two stages (σ_max → σ_mid for structure, σ_mid → σ_min for detail), each with its own slope normalized by step count. cosine / kumaraswamy / laplacian / linear apply a single curve across the whole range. The _structure / _detail variants make the two stages asymmetric.

Sigma Curves. Stores a normalized [0, 1] y-array per step alongside the originally chosen baseline scheduler. At runtime the values are resampled to the consumer's step count and denormalized against the active model's σ_min / σ_max. Workflows persist the curve in the node's curve_data widget; saved presets live at presets/sigma_curves.json.

Manual Sampler. Builds a thin wrapper around the chosen base sampler's function in comfy.samplers.k_diffusion_sampling, injecting eta / s_noise / stages only when the base sampler accepts them. Saved presets live at presets/manual_samplers.json and re-register as samplers on every ComfyUI startup.

Safety. A per-step cap limits eps_2 modifications to a small fraction of the original RMS, preventing compounding artifacts. A sigma warmup gate suppresses enhancement at high noise levels (early steps). An img2img denoise gate scales down enhancement for partial-denoise schedules.

Cost. One 3×3 avg_pool per step for spatial variants; one FFT pair for spectral / coherence modes. All negligible vs. model evaluation. Auto samplers add a few scalar ops on top.

License

MIT