How 1038lab/comfyui-minimax-remover works
1. This repository is a ComfyUI custom node package for MiniMax object removal. Its purpose is to plug into ComfyUI’s graph execution model and provide image/video inpainting-style removal using a pretrained MiniMax model.
2. The architecture is split into two main layers:
- nodes/: ComfyUI-facing node definitions and input/output plumbing.
- Minimax/: the actual inference implementation, including the pipeline and transformer wrapper that drive model execution.
3. The runtime data flow is graph-based and centered on masks:
- a source image or video is loaded,
- a mask indicates the object to remove,
- optional dimension adjustment normalizes inputs,
- the model loader provides reusable VAE / transformer / scheduler components,
- the image remover or video remover node runs inference,
- the processed frame(s) are returned back into the ComfyUI graph.
4. The node boundary is important:
- MinimaxModelLoader is a shared dependency node that loads model components once and can be reused by other nodes.
- MinimaxImageRemover is the single-image execution node.
- MinimaxVideoRemover is the multi-frame/video execution node.
- MinimaxVideoLoader handles video ingestion.
- ImageSizeAdjuster exists as a preprocessing helper to keep dimensions compatible with the model.
5. The Minimax/pipeline_minimax_remover.py and Minimax/transformer_minimax_remover.py files likely form the core inference engine:
- the transformer wraps the learned removal model,
- the pipeline orchestrates scheduling, conditioning, and iterative denoising/removal steps,
- this is where the model-specific logic lives rather than in the ComfyUI node wrappers.
6. The repo is designed around model reuse and caching rather than embedding weights in the package. The README and file layout indicate that model artifacts are downloaded from HuggingFace into ComfyUI/models/MiniMax-Remover/, with local folders for vae, transformer, and scheduler.
7. Video support is a distinct subsystem, not just “image repeated N times.” The presence of decord and a dedicated video_loader/video_remover path suggests frame extraction, per-frame or temporal processing, and reassembly are part of the architecture. This is a key boundary for diagramming because video introduces a separate I/O and batching flow.
8. Preprocessing and compatibility handling are first-class concerns:
- ImageSizeAdjuster helps align dimensions to model constraints,
- the README notes requirements like divisibility by 16 and mask/image compatibility,
- mask cleanup and dimension fixes are part of the input boundary, before inference starts.
9. The package depends on PyTorch + Diffusers-style model execution, with supporting libraries like accelerate, einops, scipy, opencv-python, and huggingface_hub. These materially affect the architecture because they imply GPU-backed inference, scheduler selection, and model download/caching behavior.
10. The project is optimized for ComfyUI graph composition rather than a standalone CLI or server. That means the main integration point is the node API, not REST endpoints or persistent services. The output of each node becomes input to downstream ComfyUI nodes.
11. The example_workflows/ directory contains ready-made ComfyUI workflows for image and video object removal, which is useful for understanding expected node connectivity and the typical end-to-end path through the graph.
12. Packaging and release are lightweight:
- pyproject.toml and requirements.txt define install/build metadata,
- .github/workflows/publish.yml indicates automated publishing/release support,
- there is no evidence of a backend database, queue, or external application server.
13. In architecture-diagram terms, the most important boundaries are:
- ComfyUI graph layer vs. MiniMax model execution layer,
- image path vs. video path,
- shared model loading vs. per-request inference,
- local preprocessing vs. remote HuggingFace model acquisition.
14. Overall, this repo is a thin ComfyUI integration wrapper around a pretrained object-removal model, with the substantial logic concentrated in the model pipeline and the surrounding nodes focused on input normalization, model lifecycle, and graph-friendly execution.
Main entry points: model_loader_node.py Model loader · minimax_image_remover_node.py Image remover · minimax_video_remover_node.py Video remover · pipeline_minimax_remover.py Removal pipeline
Components 17
ComfyUI integration
Node-facing entry points and graph plumbing.
- Package entry · Registers the custom nodes for ComfyUI.
__init__.py - Model loader · Loads reusable MiniMax components for downstream nodes.
nodes/model_loader_node.py - Image remover · Runs single-image object removal inside the ComfyUI graph.
nodes/minimax_image_remover_node.py - Video remover · Runs multi-frame/video object removal inside the ComfyUI graph.
nodes/minimax_video_remover_node.py - Size adjuster · Normalizes dimensions to match model constraints.
nodes/image_size_adjuster_node.py - Video loader · Loads video input and prepares it for downstream processing.
nodes/video_loader_node.py - Node utils · Shared node-side helper logic.
nodes/utils.py
MiniMax engine
Shared model loading and inference runtime.
- Removal pipeline · Orchestrates conditioning, scheduling, and iterative removal steps.
Minimax/pipeline_minimax_remover.py - Transformer · Wraps the learned MiniMax removal model.
Minimax/transformer_minimax_remover.py - Engine init · MiniMax engine package boundary.
Minimax/__init__.py - VAE · Latent encoder/decoder component loaded from local model storage.
- Scheduler · Inference scheduler component used by the pipeline.
- Model cache · Local HuggingFace-backed MiniMax model directory under ComfyUI models.
- HuggingFace · Remote source for pretrained artifacts.
Video path
Video ingestion and frame-based removal flow.
- Frame flow · Represents frame extraction, batching, and reassembly in the video path.
Examples
Ready-made workflows demonstrating typical usage.
- Image workflow · Example ComfyUI graph for image object removal.
example_workflows/MiniMax Image Object Remover.json - Video workflow · Example ComfyUI graph for video object removal.
example_workflows/MiniMax video Object Remover.json
Connections 27
- Package entry → Model loader: registers · Exposes the shared model loader node to ComfyUI.
- Package entry → Image remover: registers · Exposes the image removal node to ComfyUI.
- Package entry → Video remover: registers · Exposes the video removal node to ComfyUI.
- Package entry → Size adjuster: registers · Exposes preprocessing support to ComfyUI.
- Package entry → Video loader: registers · Exposes the video input node to ComfyUI.
- Model loader → Model cache: loads · Resolves local model artifacts and reusable components.
- Model cache → HuggingFace: syncs from · Artifacts are obtained from HuggingFace and cached locally.
- Model loader → VAE: provides · Makes the VAE available to inference nodes.
- Model loader → Scheduler: provides · Makes the scheduler available to inference nodes.
- Model loader → Transformer: provides · Makes the transformer available to the pipeline.
- Image remover → Size adjuster: preprocesses · Adjusts image and mask dimensions before inference.
- Image remover → Removal pipeline: runs · Invokes the core removal pipeline for image inputs.
- Image remover → Model loader: depends on · Uses shared loaded components rather than reloading weights.
- Video loader → Frame flow: feeds · Video ingestion produces frames for downstream processing.
- Video remover → Frame flow: processes · Operates on extracted frames and reassembles results.
- Video remover → Removal pipeline: runs · Invokes the core removal pipeline for video inputs.
- Video remover → Model loader: depends on · Uses the shared model bundle for video inference.
- Removal pipeline → Transformer: uses · The pipeline delegates learned-model execution to the transformer wrapper.
- Removal pipeline → Scheduler: steps with · Coordinates iterative denoising/removal steps through the scheduler.
- Removal pipeline → VAE: encodes with · Uses the VAE for latent-space conversion.
- Node utils → Image remover: supports · Shared helper logic used by node-side execution.
- Node utils → Video remover: supports · Shared helper logic used by node-side execution.
- Engine init → Removal pipeline: packages · Defines the engine module boundary for imports.
- Engine init → Transformer: packages · Defines the engine module boundary for imports.
- Image workflow → Image remover: demonstrates · Example workflow shows the image-removal path.
- Video workflow → Video loader: demonstrates · Example workflow shows the video ingestion path.
- Video workflow → Video remover: demonstrates · Example workflow shows the video-removal path.