# 1038lab/comfyui-minimax-remover architecture
> Architecture diagram of the GitHub repository 1038lab/comfyui-minimax-remover, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/1038lab/comfyui-minimax-remover
- Repository: https://github.com/1038lab/comfyui-minimax-remover
## Overview
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: [`nodes/model_loader_node.py`](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/model_loader_node.py) (Model loader), [`nodes/minimax_image_remover_node.py`](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/minimax_image_remover_node.py) (Image remover), [`nodes/minimax_video_remover_node.py`](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/minimax_video_remover_node.py) (Video remover), [`Minimax/pipeline_minimax_remover.py`](https://github.com/1038lab/comfyui-minimax-remover/blob/main/Minimax/pipeline_minimax_remover.py) (Removal pipeline)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_group_comfyui["ComfyUI integration"]
node_node_root["Package entry
comfyui-package
[__init__.py]"]
node_node_model_loader["Model loader
shared-loader"]
node_node_image_remover["Image remover
inference-node"]
node_node_video_remover["Video remover
inference-node"]
node_node_size_adjuster["Size adjuster
preprocess-node"]
node_node_video_loader["Video loader
input-node"]
node_node_utils["Node utils
helpers
[utils.py]"]
end
subgraph group_group_engine["MiniMax engine"]
node_node_pipeline["Removal pipeline
inference-pipeline"]
node_node_transformer["Transformer
model-wrapper"]
node_node_engine_init["Engine init
package-core
[__init__.py]"]
node_node_vae[("VAE
model-component")]
node_node_scheduler["Scheduler
model-component"]
node_node_weights[("Model cache
local-models")]
node_node_hf(("HuggingFace
model-source"))
end
subgraph group_group_video["Video path"]
node_node_frame_flow{{"Frame flow
video-processing"}}
end
subgraph group_group_docs["Examples"]
node_node_image_wf["Image workflow
example-workflow"]
node_node_video_wf["Video workflow
example-workflow"]
end
node_node_root -->|"registers"| node_node_model_loader
node_node_root -->|"registers"| node_node_image_remover
node_node_root -->|"registers"| node_node_video_remover
node_node_root -->|"registers"| node_node_size_adjuster
node_node_root -->|"registers"| node_node_video_loader
node_node_model_loader -->|"loads"| node_node_weights
node_node_weights -.->|"syncs from"| node_node_hf
node_node_model_loader -->|"provides"| node_node_vae
node_node_model_loader -->|"provides"| node_node_scheduler
node_node_model_loader -->|"provides"| node_node_transformer
node_node_image_remover -->|"preprocesses"| node_node_size_adjuster
node_node_image_remover -->|"runs"| node_node_pipeline
node_node_image_remover -->|"depends on"| node_node_model_loader
node_node_video_loader -->|"feeds"| node_node_frame_flow
node_node_video_remover -->|"processes"| node_node_frame_flow
node_node_video_remover -->|"runs"| node_node_pipeline
node_node_video_remover -->|"depends on"| node_node_model_loader
node_node_pipeline -->|"uses"| node_node_transformer
node_node_pipeline -->|"steps with"| node_node_scheduler
node_node_pipeline -->|"encodes with"| node_node_vae
node_node_utils -.->|"supports"| node_node_image_remover
node_node_utils -.->|"supports"| node_node_video_remover
node_node_engine_init -->|"packages"| node_node_pipeline
node_node_engine_init -->|"packages"| node_node_transformer
node_node_image_wf -.->|"demonstrates"| node_node_image_remover
node_node_video_wf -.->|"demonstrates"| node_node_video_loader
node_node_video_wf -.->|"demonstrates"| node_node_video_remover
click node_node_root "https://github.com/1038lab/comfyui-minimax-remover/blob/main/__init__.py"
click node_node_model_loader "https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/model_loader_node.py"
click node_node_image_remover "https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/minimax_image_remover_node.py"
click node_node_video_remover "https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/minimax_video_remover_node.py"
click node_node_size_adjuster "https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/image_size_adjuster_node.py"
click node_node_video_loader "https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/video_loader_node.py"
click node_node_utils "https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/utils.py"
click node_node_pipeline "https://github.com/1038lab/comfyui-minimax-remover/blob/main/Minimax/pipeline_minimax_remover.py"
click node_node_transformer "https://github.com/1038lab/comfyui-minimax-remover/blob/main/Minimax/transformer_minimax_remover.py"
click node_node_engine_init "https://github.com/1038lab/comfyui-minimax-remover/blob/main/Minimax/__init__.py"
click node_node_image_wf "https://github.com/1038lab/comfyui-minimax-remover/blob/main/example_workflows/MiniMax Image Object Remover.json"
click node_node_video_wf "https://github.com/1038lab/comfyui-minimax-remover/blob/main/example_workflows/MiniMax video Object Remover.json"
classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_root,node_node_model_loader,node_node_image_remover,node_node_video_remover,node_node_size_adjuster,node_node_video_loader,node_node_utils toneBlue
class node_node_pipeline,node_node_transformer,node_node_engine_init,node_node_vae,node_node_scheduler,node_node_weights,node_node_hf toneAmber
class node_node_frame_flow toneMint
class node_node_image_wf,node_node_video_wf toneRose
```
## Components
### ComfyUI integration
Node-facing entry points and graph plumbing.
- [Package entry](https://github.com/1038lab/comfyui-minimax-remover/blob/main/__init__.py): comfyui-package · Registers the custom nodes for ComfyUI. · `__init__.py`
- [Model loader](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/model_loader_node.py): shared-loader · Loads reusable MiniMax components for downstream nodes. · `nodes/model_loader_node.py`
- [Image remover](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/minimax_image_remover_node.py): inference-node · Runs single-image object removal inside the ComfyUI graph. · `nodes/minimax_image_remover_node.py`
- [Video remover](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/minimax_video_remover_node.py): inference-node · Runs multi-frame/video object removal inside the ComfyUI graph. · `nodes/minimax_video_remover_node.py`
- [Size adjuster](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/image_size_adjuster_node.py): preprocess-node · Normalizes dimensions to match model constraints. · `nodes/image_size_adjuster_node.py`
- [Video loader](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/video_loader_node.py): input-node · Loads video input and prepares it for downstream processing. · `nodes/video_loader_node.py`
- [Node utils](https://github.com/1038lab/comfyui-minimax-remover/blob/main/nodes/utils.py): helpers · Shared node-side helper logic. · `nodes/utils.py`
### MiniMax engine
Shared model loading and inference runtime.
- [Removal pipeline](https://github.com/1038lab/comfyui-minimax-remover/blob/main/Minimax/pipeline_minimax_remover.py): inference-pipeline · Orchestrates conditioning, scheduling, and iterative removal steps. · `Minimax/pipeline_minimax_remover.py`
- [Transformer](https://github.com/1038lab/comfyui-minimax-remover/blob/main/Minimax/transformer_minimax_remover.py): model-wrapper · Wraps the learned MiniMax removal model. · `Minimax/transformer_minimax_remover.py`
- [Engine init](https://github.com/1038lab/comfyui-minimax-remover/blob/main/Minimax/__init__.py): package-core · MiniMax engine package boundary. · `Minimax/__init__.py`
- **VAE**: model-component · Latent encoder/decoder component loaded from local model storage.
- **Scheduler**: model-component · Inference scheduler component used by the pipeline.
- **Model cache**: local-models · Local HuggingFace-backed MiniMax model directory under ComfyUI models.
- **HuggingFace**: model-source · Remote source for pretrained artifacts.
### Video path
Video ingestion and frame-based removal flow.
- **Frame flow**: video-processing · Represents frame extraction, batching, and reassembly in the video path.
### Examples
Ready-made workflows demonstrating typical usage.
- [Image workflow](https://github.com/1038lab/comfyui-minimax-remover/blob/HEAD/example_workflows/MiniMax%20Image%20Object%20Remover.json): example-workflow · Example ComfyUI graph for image object removal. · `example_workflows/MiniMax Image Object Remover.json`
- [Video workflow](https://github.com/1038lab/comfyui-minimax-remover/blob/HEAD/example_workflows/MiniMax%20video%20Object%20Remover.json): example-workflow · Example ComfyUI graph for video object removal. · `example_workflows/MiniMax video Object Remover.json`
## Connections
- 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.