ROS Package bob_flux2k 

ROS 2 node for the FLUX.2-klein text-to-image and image-to-image models from Black Forest Labs.

Supported Models

This node supports both the 4B and 9B variants of the FLUX.2-klein family:

FLUX.2-klein-4B: Optimized for speed and lower VRAM usage (Apache 2.0 license).
FLUX.2-klein-9B: Higher quality and better prompt following (requires ~22GB VRAM, fits on RTX 4090).

[!IMPORTANT] To use the 9B model, you must manually visit the model page, log in to Hugging Face, and agree to the terms and non-commercial license. You will also need to be logged in via huggingface-cli login on your machine for the node to download the weights.

You can switch models via the repo_id ROS parameter or the FLUX2K_REPO_ID environment variable.

Installation & Build

1. Clone the repository

cd ~/ros2_ws/src
git clone https://github.com/bob-ros2/bob_flux2k.git

2. Install dependencies

It is recommended to use a virtual environment.

pip install -r bob_flux2k/requirements.txt

3. Build the workspace

cd ~/ros2_ws
colcon build --packages-select bob_flux2k
source install/setup.bash

Usage

Run the node

You can run the node directly or provide a configuration file.

Basic run:

ros2 run bob_flux2k tti --ros-args -p repo_id:=black-forest-labs/FLUX.2-klein-4B

Using a configuration file:

ros2 run bob_flux2k tti --ros-args --params-file src/bob_flux2k/config/tti.yaml

Send a prompt

ros2 topic pub /prompt std_msgs/msg/String "{data: 'A futuristic city in the style of cyberpunk'}" --once

JSON Prompt Support (Dynamic ITI/TTI)

The node automatically detects if a prompt is plain text or a JSON string. Using JSON allows you to specify an input image dynamically for a single request:

Format:

{
  "content": "A high-quality photo of a cat",
  "image_url": "file:///path/to/image.jpg"
}

Features:

Text-to-Image: Just send plain text or JSON without an image_url.
Image-to-Image: Provide an image_url. Supports:
- Local files: file:///home/user/image.png
- Remote URLs: https://example.com/image.jpg
- Base64 encoded: data:image/png;base64,... (Ideal for web-app integrations).

Example (CLI):

ros2 topic pub /prompt std_msgs/msg/String "{data: '{\"content\": \"a robot dog\", \"image_url\": \"file:///tmp/dog.jpg\"}'}" --once

ROS API

Topics

The node interacts with the following ROS 2 topics:

Topic	Message Type	Direction	Description
`prompt`	`std_msgs/msg/String`	Sub	The input prompt for text-to-image or image-conditioned generation.
`generated_image`	`sensor_msgs/msg/Image`	Pub	The resulting image, published in `bgr8` encoding.

Parameters

Dynamic Parameters

These can be adjusted while the node is running using the rqt_reconfigure GUI.

Parameter	Env Variable	Default	Description
`keep_loaded`	`FLUX2K_KEEP_LOADED`	`true`	If true, keeps the model in memory.
`cpu_offload`	`FLUX2K_CPU_OFFLOAD`	`true`	If true, uses CPU offloading.
`num_inference_steps`	`FLUX2K_NUM_STEPS`	`4`	Number of denoising steps.
`guidance_scale`	`FLUX2K_GUIDANCE`	`1.0`	Prompt following strength.
`num_images_per_prompt`	`FLUX2K_NUM_IMAGES`	`1`	Batch generation count.
`max_sequence_length`	`FLUX2K_MAX_SEQ`	`512`	Max prompt length.
`frame_id`	`FLUX2K_FRAME_ID`	`flux2k`	The frame_id for the output.

Static Parameters

These are set at startup and cannot be changed while the node is running.

Parameter	Env Variable	Default	Description
`repo_id`	`FLUX2K_REPO_ID`	`black-forest-labs/FLUX.2-klein-4B`	Model repository ID.
`model_dir`	`FLUX2K_MODEL_DIR`	`./models`	Cache directory.
`device`	`FLUX2K_DEVICE`	`cuda:0`	Computing device.
`seed`	`FLUX2K_SEED`	`-1`	Random seed (-1 for random).
`image_path`	`FLUX2K_IMAGE_PATH`	`''`	Path for saving the output image. If empty, local saving is disabled.
`once`	`FLUX2K_ONCE`	`false`	Exit after first generation if true.
`height`	`FLUX2K_HEIGHT`	`1024`	Image height.
`width`	`FLUX2K_WIDTH`	`1024`	Image width.

Dynamic Reconfiguration GUI

To start the configuration GUI and adjust the dynamic parameters, run:

ros2 run rqt_reconfigure rqt_reconfigure

Configuration File

An example configuration file is provided at config/tti.yaml. This file contains all parameters with descriptions and can be used to set the initial behavior of the node without providing long command-line arguments.

Hardware Optimization

The node is optimized for NVIDIA consumer GPUs (like the RTX 4090) using torch.bfloat16. It also utilizes enable_model_cpu_offload() to ensure memory efficiency, allowing it to coexist with other GPU-intensive nodes.

ROS Package bob_flux2k