---

name: constraint-generation description: "Headless iGAN constrained generation from color, mask, and edge images with safe command planning and input validation." disable-model-invocation: true metadata: disco-role: operating license: MIT

constraint-generation

Use this sub-skill when the user needs iGAN's non-UI constrained generation workflow. The workflow starts from three image constraints, plans a native command, and explains the legacy backend needed to actually optimize latent vectors. Keep the agent in command-planning and validation mode unless the user has already provided a compatible iGAN checkout, model artifact, and legacy Theano runtime.

Read when

• The task mentions the script-without-UI path for iGAN.
• The task supplies a color image, color mask, and edge image.
• The user wants a command for constrained generation without launching PyQt UI controls.
• The user asks about batch_size, n_iters, top_k, or d_weight for constrained optimization.
• The user wants to validate constraint image paths, dimensions, or image headers before a native run.
• The user needs to plan the output result grid produced by the headless script.
• The user has an iGAN model file and wants a low-iteration smoke command.
• A previous native run failed while loading Theano, OpenCV, PyQt4, CUDA, cuDNN, or model artifacts.

Do not use for

• Interactive brush controls, keyboard shortcuts, drawing pad behavior, candidate clicks, sliders, or UI launch details; route to interactive-ui.
• Downloading, locating, naming, or checking pretrained DCGAN artifacts beyond passing --model_file; route setup questions to model-inference.
• Projecting an existing image into latent space with iGAN_predict.py; route to image-projection.
• Training DCGAN models, creating HDF5 datasets, packing trained caches, or predictor training; route to the training/data sub-skill if present.
• Claiming that CPU-only validation proves Theano optimization works; it only proves static command and input contracts.

Native workflow summary

• The headless script loads a DCGAN model class by model_type and an optimizer backend by framework.
• Default model selection is model_name=outdoor_64, model_type=dcgan_theano, and framework=theano.
• If --model_file is omitted, the native script derives a model path from the model name and model type.
• The script reads input_color, input_color_mask, and input_edge images with OpenCV.
• Each image is resized to the model resolution when its dimensions do not match the model's npx.
• Color constraints use the RGB color image.
• Color-mask constraints use the first channel of the color mask after OpenCV loading.
• Edge constraints use the RGB edge image plus the first channel as the edge mask.
• Optimization initializes a batch of latent vectors, runs n_iters update steps, keeps the lowest-cost candidates, and writes one visualization image.
• The visualization contains the three input panels followed by selected generated candidates, then is enlarged by a fixed 2x resize in the native script.

First actions

1. Ask for the three constraint image paths if any are missing.
2. Ask whether the user wants only dry planning or has a prepared legacy runtime for native execution.
3. Validate paths and headers with scripts/validate_constraint_inputs.py before constructing a native command.
4. Use scripts/build_constraint_command.py to build a deterministic shell command instead of hand-assembling flags.
5. Send model-file preparation questions to model-inference rather than inventing artifact paths.
6. If the user requests GUI interaction, stop this route and use interactive-ui.

Bundled references

• Constraint workflows gives command recipes, dry-run planning, native execution prerequisites, and output grid math.
• Data formats defines image path, channel, mask, dimension, and resize expectations.
• Troubleshooting maps concrete failure symptoms to causes and recovery steps for this workflow.
• Use root troubleshooting for cross-cutting installation failures when the integrated root skill provides it.

Bundled scripts

• scripts/validate_constraint_inputs.py performs safe existence, readability, header, dimension, and channel-family checks without importing OpenCV, Theano, or PyQt4.
• scripts/build_constraint_command.py prints a dry native command plus an output-layout plan; it does not run iGAN, import Theano, download files, train models, or touch the GPU.
• Both scripts support --help and are deterministic for the same arguments.
• Prefer the scripts over ad hoc shell snippets because they encode the exact CLI flags and validation assumptions for this workflow.

Required inputs

• --input_color: image containing desired color strokes or regions.
• --input_color_mask: mask image indicating where the color image should constrain the generator.
• --input_edge: image containing edge or sketch constraints.
• --model_name: model configuration name, commonly outdoor_64 for the documented constraint example.
• --model_type: model implementation name; this repo's headless path uses dcgan_theano.
• --framework: optimizer backend name; this repo's implemented native backend is theano.
• --batch_size: number of random latent initializations optimized in parallel.
• --n_iters: total latent optimization iterations.
• --top_k: maximum number of low-cost candidates selected for the output visualization.
• --d_weight: discriminator realism cost weight; 0.0 disables discriminator cost in the native optimizer.
• --output_result: path for the generated visualization image.

Safe dry-run recipe

python scripts/validate_constraint_inputs.py \
  --input-color input_color.png \
  --input-color-mask input_color_mask.png \
  --input-edge input_edge.png \
  --target-size 64

python scripts/build_constraint_command.py \
  --model-name outdoor_64 \
  --input-color input_color.png \
  --input-color-mask input_color_mask.png \
  --input-edge input_edge.png \
  --output-result results/script_result.png \
  --batch-size 4 \
  --n-iters 3 \
  --top-k 4

Treat the printed command as a plan until the user confirms the legacy runtime and model artifact are present. The low-iteration recipe is for smoke planning, not for quality generation.

Native execution gate

Before running the native headless script, confirm all of the following:

• A compatible Python environment can import the repo's legacy dependencies.
• OpenCV is importable in that environment.
• The Theano backend can compile the model on the requested device.
• A CUDA/cuDNN stack is present when using the documented GPU flags.
• The requested model artifact exists and matches the model name/type.
• The three input images exist and validate under this sub-skill's validator.
• The output directory exists or can be created by the calling workflow.
• The user accepts that the native script may compile Theano functions and use the GPU.

If any gate fails, provide the dry command and a concrete blocker instead of attempting execution.

Output layout planning

• The native visualization begins with three input panels: color image, color mask, and edge image.
• Generated candidates are concatenated horizontally after those three panels.
• The maximum generated panel count is bounded by top_k, but the optimizer may keep fewer candidates after cost thresholding.
• With target size S, worst-case pre-resize width is S * (3 + top_k) and height is S.
• The native script applies a 2x resize before writing, so worst-case final dimensions are 2*S*(3 + top_k) by 2*S.
• If top_k > batch_size, warn the user because the batch cannot produce more unique candidates than initialized latent vectors.
• For quick smoke checks, set batch_size and top_k to a small equal value and use low n_iters.

Constraint semantics

• The color mask is a soft numeric mask after normalization to [0, 1], but binary black/white masks are easiest to reason about.
• White or nonzero mask areas increase the effect of the corresponding color image pixels.
• The edge path contributes both an edge image and an edge mask using its first channel.
• Edge pixels should be high-contrast; the optimizer compares HOG features under the edge mask.
• Empty masks make the corresponding constraint weak or ineffective.
• Fully white masks force global matching and can overwhelm the generator.
• If the model is grayscale, generated samples are tiled to RGB for visualization.

Parameter guidance

• Increase batch_size to search more random latent initializations, at higher memory cost.
• Increase n_iters for tighter constraint fitting, at higher runtime cost.
• Increase top_k only when the output visualization should show more candidate modes.
• Keep top_k <= batch_size for meaningful candidate selection.
• Start with d_weight=0.0 to match the documented script behavior.
• Try small positive d_weight only when the discriminator model loads successfully and realism should be weighted against constraint loss.
• Use explicit --model_file when the artifact is outside the native default model location.

Troubleshooting routing

• Missing image path, mismatched dimensions, unsupported headers, or weak masks: use Data formats and the validator.
• Missing model artifacts, unknown model names, or sample-generation smoke checks: use model-inference.
• Python2-era Theano, CUDA, cuDNN, OpenCV, PyQt4, Lasagne, or Fuel failures: use Troubleshooting first, then root troubleshooting if needed.
• No display, brush behavior, or candidate thumbnail UI issues: route to interactive-ui.
• iGAN_predict.py solver, AlexNet, or x -> z reconstruction issues: route to image-projection.

Verification stance

• This sub-skill can be verified statically with helper --help, command generation, and image header validation.
• Native constrained generation remains an optional CUDA/Theano/model case.
• The native candidate is the headless script with the documented sample input contract.
• Do not report native generation as verified unless the command actually writes the requested output image in a compatible runtime.
• Keep any unavailable legacy backend as an explicit known gap in the parent verification report.