{"id":31068630,"url":"https://github.com/wasasquatch/was_affine","last_synced_at":"2025-09-15T21:56:12.039Z","repository":{"id":312328949,"uuid":"1046746114","full_name":"WASasquatch/was_affine","owner":"WASasquatch","description":"Apply AFFINE transforms to latent space to improve image quality, especially with light loras","archived":false,"fork":false,"pushed_at":"2025-09-10T02:17:32.000Z","size":33697,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-10T02:21:43.882Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WASasquatch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-29T06:48:27.000Z","updated_at":"2025-09-10T02:17:35.000Z","dependencies_parsed_at":"2025-08-29T22:47:40.653Z","dependency_job_id":null,"html_url":"https://github.com/WASasquatch/was_affine","commit_stats":null,"previous_names":["wasasquatch/was_affine"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/WASasquatch/was_affine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2Fwas_affine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2Fwas_affine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2Fwas_affine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2Fwas_affine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WASasquatch","download_url":"https://codeload.github.com/WASasquatch/was_affine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2Fwas_affine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275327135,"owners_count":25445049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-15T21:56:09.182Z","updated_at":"2025-09-15T21:56:12.026Z","avatar_url":"https://github.com/WASasquatch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Affine Logo](was_affine.png)\r\n\r\n# AFFINE\r\n## Adaptive Field Filtering by Intermittent Noise Enhancement\r\n\r\n**AFFINE** is a comprehensive ComfyUI node suite that performs sparse **Adaptive Field Filtering by Intermittent Noise Enhancement** in latent space to steer diffusion results during sampling.  \r\nIt works by applying controlled scale and bias (`z' = scale * z + bias`) to masked regions of the latent tensor, enabling precise control over brightness, contrast, and detail enhancement without collapsing noise structure.\r\n\r\nThe suite includes:\r\n- **Core Affine Nodes** - Basic latent space transformations\r\n- **Integrated Samplers** - KSampler and Custom Sampling with built-in affine scheduling\r\n- **Ultimate SD Upscaler Ports** - Tiled upscaling with affine enhancement\r\n- **Pattern Noise Generation** - AFFINE augmented random noise for custom sampling\r\n- **Modular Options System** - Granular control over all parameters (also a super options node for the adventurous)\r\n\r\n### Example\r\nHere we use some aggressive settings to give a neutral cinematic look without hard contrast.\r\n- [Affine WAN Example](https://youtu.be/2IgdGCjVCcg)\r\n- [Affine USDU 720p -\u003e 2k Example](https://www.youtube.com/watch?v=-VsFb6-6xog) (Nevermind the base generation, was playing with I2T2V experiment. \u003c.\u003c)\r\n\r\n**Things to take note of:**\r\n- The background rock quality is improved.\r\n- The trees and brush look more naturally dispersed.\r\n- Roads are more realistic\r\n- The foreground detail is *essentially* better preserved.\r\n- The overall contrast is reduced.\r\n\r\n---\r\n\r\n## 🧠 How it works (ELI5)\r\n\r\n- **Controlled enhancement**: Apply scale and bias transforms to specific regions defined by procedural masks.\r\n- **Pattern-based masking**: Choose from 20+ patterns including Perlin noise, spectral noise types, geometric patterns, and content-aware masks.\r\n- **Temporal consistency**: Static or per-frame mask generation for stable video processing.\r\n- **External gating**: Use custom mask images to limit where effects are applied.\r\n- **Modular configuration**: Mix and match common options with pattern-specific parameters.\r\n- **Integrated workflows**: Built-in samplers handle scheduling automatically, or use manual latent transforms between sampling passes.\r\n\r\nThe core transformation: `z' = scale * z + bias` where the mask determines the blend between original and transformed values.\r\n\r\n---\r\n\r\n## ✨ Why AFFINE?\r\n\r\n- **Improves Quality** – Enhance detail in light LoRA outputs or tame overly contrasted/burned results from speed-boosting LoRAs.\r\n- **Works in latent space** – Avoids costly VAE decode/encode cycles and raster-space artifacts.  \r\n- **Sparse control** – Apply adjustments selectively using sophisticated mask patterns.  \r\n- **Stable video** – Temporal modes maintain consistency or controlled variation across frames.  \r\n- **Flexible integration** – Use standalone transforms, integrated samplers, or tiled upscaling workflows.\r\n- **Advanced patterns** – 20+ mask types from simple geometric to complex spectral and content-aware patterns.\r\n- **Ultimate SD Upscaler compatibility** – Tiled processing with world-aligned noise and affine enhancement.\r\n\r\n---\r\n\r\n## 🔧 Workflow Options\r\n\r\n### Option 1: Manual Latent Transform (Classic)\r\n1. Run **KSampler Advanced** or **Custom Sampling** for high-noise steps\r\n2. Apply **Latent Affine** or **Latent Affine Simple** \r\n3. Resume with second sampler for low-noise steps\r\n\r\n### Option 2: Integrated Samplers\r\n- Use **KSampler Affine** or **KSampler Affine Advanced** for automatic scheduling\r\n- Use **Custom Sampler Affine Advanced** for custom sampling workflows\r\n- Configure affine schedule, interval, and pattern parameters directly\r\n\r\n### Option 3: Tiled Upscaling\r\n- Use **Ultimate Affine KSampler - USDU** nodes for large image processing\r\n- Combines upscaling, tiling, and affine enhancement in one step\r\n- Supports custom samplers and sigma schedules\r\n- \r\n---\r\n\r\n## 📋 Node Reference\r\n\r\n### Core Affine Nodes\r\n\r\n#### Latent Affine\r\nThe main affine transformation node with full configurability.\r\n\r\n**Inputs:**\r\n- `latent` – Input latent tensor\r\n- `scale` – Multiplicative factor (1.0 = no change, \u003c1 darkens, \u003e1 brightens)\r\n- `bias` – Additive offset (-2.0 to 2.0)\r\n- `pattern` – Mask pattern (20+ options including procedural, spectral, and content-aware)\r\n- `temporal_mode` – `static` or `per_frame` for video\r\n- `seed` – Random seed for procedural patterns\r\n- `external_mask` – Optional IMAGE input for custom masking\r\n- `options` – Base options DICT (use WASLatentAffineCommonOptions)\r\n- `noise_options` – Pattern-specific options DICT\r\n\r\n**Returns:**\r\n- `latent` – Transformed latent\r\n- `mask` – Generated mask for visualization\r\n\r\n#### Latent Affine Simple\r\nStreamlined version with auto-tuned parameters for quick results.\r\n\r\n**Inputs:**\r\n- `latent` – Input latent\r\n- `scale` – Multiplicative gain (0.95-0.98 for subtle darkening)\r\n- `noise_pattern` – Auto-tuned mask pattern\r\n- `seed` – Random seed\r\n- `temporal_mode` – `static` or `per_frame`\r\n- `frame_seed_stride` – Seed increment per frame\r\n\r\n**Returns:**\r\n- `latent` – Adjusted latent\r\n- `mask` – Generated mask\r\n\r\n### Integrated Samplers\r\n\r\n#### KSampler Affine / KSampler Affine Advanced\r\nDrop-in replacements for standard KSamplers with built-in affine scheduling.\r\n\r\n**Key Parameters:**\r\n- `affine_interval` – Apply affine every N steps\r\n- `max_scale` / `max_bias` – Peak transformation values\r\n- `affine_schedule` – WASAffineScheduleOptions DICT for timing curve\r\n- `affine_seed` / `affine_seed_increment` – Seed management\r\n- All standard KSampler parameters\r\n\r\n#### Custom Sampler Affine Advanced\r\nAdvanced custom sampling with affine integration.\r\n\r\n**Inputs:**\r\n- `noise` / `guider` / `sampler` / `sigmas` – Standard custom sampling inputs\r\n- `latent_image` – Input latent\r\n- Affine parameters (same as KSampler variants)\r\n\r\n**Returns:**\r\n- `output` – Final latent\r\n- `denoised_output` – Denoised latent\r\n\r\n### Ultimate SD Upscaler Ports\r\n\r\n#### Ultimate Affine KSampler - USDU\r\nFull upscaling with model-based upscaling and affine enhancement.\r\n\r\n**Key Features:**\r\n- `upscale_model` / `upscale_factor` – Upscaling configuration\r\n- Tiling parameters (`tile_width`, `tile_height`, `tile_padding`)\r\n- Seam fixing options\r\n- Full affine parameter set\r\n- World-aligned noise for consistent tiling\r\n\r\n#### Ultimate Affine KSampler (No Upscale) - USDU\r\nTiled processing without initial upscaling.\r\n\r\n#### Ultimate Affine KSampler (Custom) - USDU\r\nSupports custom samplers and sigma schedules.\r\n\r\n### Pattern Noise Generation\r\n\r\n#### Affine Pattern Noise\r\nGenerates structured noise by augmenting base ComfyUI noise with procedural patterns.\r\n\r\n**Inputs:**\r\n- `pattern` – Noise pattern type\r\n- `seed` – Random seed\r\n- `affine_scale` – Pattern amplitude multiplier\r\n- `normalize` – Center and scale pattern\r\n- `affine_bias` – Additive bias\r\n- `options` / `noise_options` – Pattern parameters\r\n\r\n**Returns:**\r\n- `noise` – Structured noise generator\r\n\r\n---\r\n\r\n## 🎨 Available Patterns\r\n\r\n### Spectral Noise Types\r\n- **white_noise** – Uniform frequency spectrum\r\n- **pink_noise** – 1/f frequency falloff (natural)\r\n- **brown_noise** / **red_noise** – 1/f² falloff (warmer)\r\n- **blue_noise** – High-frequency emphasis\r\n- **violet_noise** / **purple_noise** – f² emphasis (harsh)\r\n- **green_noise** – Mid-frequency band-pass\r\n- **black_noise** – Sparse narrowband spectrum\r\n\r\n### Geometric Patterns\r\n- **checker** – Checkerboard tiles\r\n- **bayer** – Ordered dithering matrix\r\n- **solid** – Constant alpha mask\r\n\r\n### Procedural Patterns\r\n- **perlin** – Smooth fractal noise (organic)\r\n- **worley_edges** – Cellular noise emphasizing edges\r\n- **poisson_blue_mask** – Blue-noise Poisson-disk distance field\r\n- **cross_hatch** – Oriented gratings and cross-hatch\r\n- **tile_oriented_lines** – Per-tile oriented lines\r\n- **dot_screen_jitter** – Halftone dots with jitter\r\n- **velvet_noise** – Sparse high-frequency impulses\r\n\r\n### Frequency Domain\r\n- **ring_noise** – Narrow annulus in frequency domain\r\n- **highpass_white** – High-pass filtered white noise\r\n\r\n### Content-Aware (from latent)\r\n- **detail_region** – High texture/variance areas\r\n- **smooth_region** – Low detail areas\r\n- **edges_sobel** – Sobel edge detection\r\n- **edges_laplacian** – Laplacian edge detection\r\n\r\n### External\r\n- **external_mask** – Use provided IMAGE directly\r\n\r\n---\r\n\r\n## 🔧 Options System\r\n\r\n### Common Options (WASLatentAffineCommonOptions)\r\nBase parameters that apply to all patterns:\r\n\r\n- **mask_strength** – Scales mask intensity (0.0-2.0)\r\n- **threshold** – Binarize mask if \u003e 0 (0.0-1.0)\r\n- **invert_mask** – Invert after threshold/blur\r\n- **blur_ksize** / **blur_sigma** – Gaussian blur for soft edges\r\n- **clamp** / **clamp_min** / **clamp_max** – Output value clamping\r\n- **frame_seed_stride** – Seed increment per frame (temporal mode)\r\n- **compute_device** – Where to generate masks (auto/cuda/cpu)\r\n- **sharpen_enable** / **sharpen_sigma** / **sharpen_amount** – Unsharp masking\r\n\r\n### Pattern-Specific Options\r\nEach pattern type has dedicated option nodes:\r\n\r\n#### WASPerlinOptions\r\n- `perlin_scale` – Base feature size (larger = smoother)\r\n- `perlin_octaves` – Number of octaves (1-8)\r\n- `perlin_persistence` – Amplitude falloff per octave\r\n- `perlin_lacunarity` – Frequency multiplier per octave\r\n\r\n#### WASWorleyEdgesOptions  \r\n- `worley_points_per_kpx` – Cell density per 1000 pixels\r\n- `worley_metric` – Distance metric (L2/L1)\r\n- `worley_edge_sharpness` – Edge emphasis exponent\r\n\r\n#### WASPoissonBlueOptions\r\n- `poisson_radius_px` – Minimum dot spacing\r\n- `poisson_softness` – Distance field smoothing\r\n\r\n#### WASCrossHatchOptions\r\n- `hatch_freq_cyc_px` – Line frequency\r\n- `hatch_angle1_deg` / `hatch_angle2_deg` – Hatch angles\r\n- `hatch_square` – Square wave vs sine\r\n- `hatch_phase_jitter` – Random phase variation\r\n- `hatch_supersample` – Anti-aliasing factor\r\n\r\n#### WASRingNoiseOptions\r\n- `ring_center_frac` – Ring center (fraction of Nyquist)\r\n- `ring_bandwidth_frac` – Ring thickness\r\n\r\n#### WASHighpassWhiteOptions\r\n- `highpass_cutoff_frac` – Butterworth cutoff\r\n- `highpass_order` – Filter steepness\r\n\r\n#### WASTileLinesOptions\r\n- `tile_line_tile_size` – Tile dimensions\r\n- `tile_line_freq_cyc_px` – Line frequency per tile\r\n- `tile_line_jitter` – Orientation randomness\r\n\r\n#### WASDotScreenOptions\r\n- `dot_cell_size` – Halftone cell size\r\n- `dot_jitter_px` – Dot center randomness\r\n- `dot_fill_ratio` – Coverage per cell\r\n\r\n#### WASGreenNoiseOptions / WASBlackNoiseOptions / WASVelvetOptions\r\n- Spectral and impulse noise parameters\r\n- See node tooltips for detailed ranges\r\n\r\n#### WASCheckerOptions / WASBayerOptions\r\n- `checker_size` / `bayer_size` – Pattern scale\r\n\r\n#### WASDetailRegionOptions / WASSmoothRegionOptions\r\n- `content_window` – Kernel size for content analysis\r\n\r\n### Affine Schedule Options (WASAffineScheduleOptions)\r\nControls timing and intensity curves for integrated samplers:\r\n\r\n- **start** / **end** – Active range (0.0-1.0 of total steps)\r\n- **bias** – Curve bias toward start/end\r\n- **exponent** – Power curve shaping\r\n- **curve** – Easing function (linear, sine, cubic, etc.)\r\n- **start_offset** / **end_offset** – Value adjustments\r\n\r\n**Returns:** Schedule DICT + visualization plot\r\n\r\n---\r\n\r\n## 🏞️ External Mask Gating\r\n\r\nUse external masks to limit where affine effects are applied:\r\n\r\n- Connect a grayscale IMAGE to `external_mask` input\r\n- Set `pattern` to any procedural pattern (not `external_mask`)\r\n- The generated pattern mask is multiplied by your external mask\r\n- Affine transforms only apply where both masks are bright\r\n\r\n**Use Cases:**\r\n- Apply effects only to specific objects or regions\r\n- Combine with segmentation masks for targeted enhancement\r\n- Create complex composite effects with multiple mask layers\r\n\r\n\r\n---\r\n\r\n## 📂 Installation\r\n\r\n### Manual\r\n1. Clone the repository to your `ComfyUI/custom_nodes` directory:\r\n   ```bash\r\n   cd ComfyUI/custom_nodes\r\n   git clone https://github.com/WASasquatch/was_affine.git\r\n   ```\r\n2. Restart ComfyUI via [Manager](https://github.com/Comfy-Org/ComfyUI-Manager) or console\r\n\r\n### Manager\r\n1. Open [Manager](https://github.com/Comfy-Org/ComfyUI-Manager) and click \"Install Custom Nodes\"\r\n2. Search \"**WAS Affine**\" and click install on the custom node by author WAS.\r\n3. Restart ComfyUI via Manager's main menu.\r\n\r\n\r\n**Dependencies:** Standard ComfyUI installation (torch, numpy). ***[Ultimate SD Upscaler](https://github.com/ssitu/ComfyUI_UltimateSDUpscale) nodes require the UltimateSDUpscale extension.***\r\n\r\n---\r\n\r\n## 🧪 Tips \u0026 Best Practices\r\n\r\n### General Guidelines\r\n- **Start subtle**: Latent space is sensitive - `scale=0.95` can be quite strong\r\n- **Model sensitivity varies**: Some models respond more dramatically than others\r\n- **Flux/Krea models**: May need positive scale values (inverted behavior)\r\n- **Lightning LoRAs**: Combine with lower CFG (1-2) for best results\r\n\r\n### Pattern Selection\r\n- **Organic content**: perlin, worley_edges work naturally\r\n- **Architectural/geometric**: checker, bayer, cross_hatch\r\n- **Fine detail work**: velvet_noise, highpass_white, ring_noise\r\n- **Content-aware**: detail_region for textures, smooth_region for skies\r\n\r\n---\r\n\r\n## 📜 License\r\n\r\n[MIT](LICENSE) – Free to use, modify, and share with attribution.\r\n\r\n---\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- ComfyUI team for the excellent software\r\n- Ultimate SD Upscaler and ComfyUI wrapper developers\r\n- Community feedback and testing contributions like \"Ansel\" and \"Lucifer\". \r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwasasquatch%2Fwas_affine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwasasquatch%2Fwas_affine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwasasquatch%2Fwas_affine/lists"}