generate_hyper3d_model_via_images

Instructions

Generate 3D asset using Hyper3D by giving images of the wanted asset, and import the generated asset into Blender.
The 3D asset has built-in materials.
The generated model has a normalized size, so re-scaling after generation can be useful.

Parameters:
- input_image_paths: The **absolute** paths of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in MAIN_SITE mode.
- input_image_urls: The URLs of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in FAL_AI mode.
- bbox_condition: Optional. If given, it has to be a list of ints of length 3. Controls the ratio between [Length, Width, Height] of the model.

Only one of {input_image_paths, input_image_urls} should be given at a time, depending on the Hyper3D Rodin's current mode.
Returns a message indicating success or failure.

Implementation Reference

• src/blender_mcp/server.py:747-801 (handler)

  Handler function implementing the 'generate_hyper3d_model_via_images' tool. Processes input images (from paths or URLs), encodes them if from paths, and sends a 'create_rodin_job' command to the Blender connection with image data and optional bbox_condition. Returns task UUID and subscription key on success or error details.

  @mcp.tool()
  def generate_hyper3d_model_via_images(
      ctx: Context,
      input_image_paths: list[str]=None,
      input_image_urls: list[str]=None,
      bbox_condition: list[float]=None
  ) -> str:
      """
      Generate 3D asset using Hyper3D by giving images of the wanted asset, and import the generated asset into Blender.
      The 3D asset has built-in materials.
      The generated model has a normalized size, so re-scaling after generation can be useful.
      
      Parameters:
      - input_image_paths: The **absolute** paths of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in MAIN_SITE mode.
      - input_image_urls: The URLs of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in FAL_AI mode.
      - bbox_condition: Optional. If given, it has to be a list of ints of length 3. Controls the ratio between [Length, Width, Height] of the model.
  
      Only one of {input_image_paths, input_image_urls} should be given at a time, depending on the Hyper3D Rodin's current mode.
      Returns a message indicating success or failure.
      """
      if input_image_paths is not None and input_image_urls is not None:
          return f"Error: Conflict parameters given!"
      if input_image_paths is None and input_image_urls is None:
          return f"Error: No image given!"
      if input_image_paths is not None:
          if not all(os.path.exists(i) for i in input_image_paths):
              return "Error: not all image paths are valid!"
          images = []
          for path in input_image_paths:
              with open(path, "rb") as f:
                  images.append(
                      (Path(path).suffix, base64.b64encode(f.read()).decode("ascii"))
                  )
      elif input_image_urls is not None:
          if not all(urlparse(i) for i in input_image_paths):
              return "Error: not all image URLs are valid!"
          images = input_image_urls.copy()
      try:
          blender = get_blender_connection()
          result = blender.send_command("create_rodin_job", {
              "text_prompt": None,
              "images": images,
              "bbox_condition": _process_bbox(bbox_condition),
          })
          succeed = result.get("submit_time", False)
          if succeed:
              return json.dumps({
                  "task_uuid": result["uuid"],
                  "subscription_key": result["jobs"]["subscription_key"],
              })
          else:
              return json.dumps(result)
      except Exception as e:
          logger.error(f"Error generating Hyper3D task: {str(e)}")
          return f"Error generating Hyper3D task: {str(e)}"

• src/blender_mcp/server.py:702-709 (helper)

  Helper function used by the tool to normalize and validate the bbox_condition parameter into a list of integers scaled to 0-100 range.

  def _process_bbox(original_bbox: list[float] | list[int] | None) -> list[int] | None:
      if original_bbox is None:
          return None
      if all(isinstance(i, int) for i in original_bbox):
          return original_bbox
      if any(i<=0 for i in original_bbox):
          raise ValueError("Incorrect number range: bbox must be bigger than zero!")
      return [int(float(i) / max(original_bbox) * 100) for i in original_bbox] if original_bbox else None

• src/blender_mcp/server.py:747-747 (registration)

  The @mcp.tool() decorator registers this function as an MCP tool with the name 'generate_hyper3d_model_via_images' derived from the function name.

  @mcp.tool()

• src/blender_mcp/server.py:748-766 (schema)

  Input schema defined by function parameters with type hints and detailed docstring describing usage, requirements, and return value.

  def generate_hyper3d_model_via_images(
      ctx: Context,
      input_image_paths: list[str]=None,
      input_image_urls: list[str]=None,
      bbox_condition: list[float]=None
  ) -> str:
      """
      Generate 3D asset using Hyper3D by giving images of the wanted asset, and import the generated asset into Blender.
      The 3D asset has built-in materials.
      The generated model has a normalized size, so re-scaling after generation can be useful.
      
      Parameters:
      - input_image_paths: The **absolute** paths of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in MAIN_SITE mode.
      - input_image_urls: The URLs of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in FAL_AI mode.
      - bbox_condition: Optional. If given, it has to be a list of ints of length 3. Controls the ratio between [Length, Width, Height] of the model.
  
      Only one of {input_image_paths, input_image_urls} should be given at a time, depending on the Hyper3D Rodin's current mode.
      Returns a message indicating success or failure.
      """