Update README.md

README.md

@@ -4,4 +4,129 @@ license: apache-2.0
 
 Our models are trained based on [Jedi models](https://huggingface.co/xlangai/Jedi-3B-1080p) via an efficient continual training strategy, which enhances the models' text dragging performance while perserving their original click-based performance.
 
-For details of how to employ the models, please refer to our [repo](https://github.com/OSU-NLP-Group/GUI-Drag/blob/48a3480fe580e93fb747f0eb8ae549d5eb18f57b/evaluation/cli_run_drag.sh#L14) examples.
+For details of how to employ the models, please refer to our [repo](https://github.com/OSU-NLP-Group/GUI-Drag/blob/48a3480fe580e93fb747f0eb8ae549d5eb18f57b/evaluation/cli_run_drag.sh#L14) examples.
+
+Below is the code of a quick demo:
+
+```
+# pip install "vllm>=0.4" transformers pillow huggingface_hub
+import json
+import re
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+from huggingface_hub import hf_hub_download
+from transformers import AutoTokenizer
+from transformers.models.qwen2_vl.image_processing_qwen2_vl_fast import smart_resize as qwen_smart_resize
+from vllm import LLM, SamplingParams
+
+MODEL_ID = "osunlp/GUI-Drag-7B"
+
+FN_CALL_TEMPLATE = """You are a helpful assistant.
+# Tools
+You may call one or more functions to assist with the user query.
+You are provided with function signatures within <tools></tools> XML tags:
+<tools>
+{"type": "function", "function": {"name": "computer_use", "description": "Use a mouse and keyboard to interact with a computer, and take screenshots.\n* This is an interface to a desktop GUI. You do not have access to a terminal or applications menu. You must click on desktop icons to start applications.\n* Some applications may take time to start or process actions, so you may need to wait and take successive screenshots to see the results of your actions. E.g. if you click on Firefox and a window doesn't open, try wait and taking another screenshot.\n* The screen's resolution is {width}x{height}.\n* Whenever you intend to move the cursor to click on an element like an icon, you should consult a screenshot to determine the coordinates of the element before moving the cursor.\n* If you tried clicking on a program or link but it failed to load, even after waiting, try adjusting your cursor position so that the tip of the cursor visually falls on the element that you want to click.\n* Make sure to click any buttons, links, icons, etc with the cursor tip in the center of the element. Don't click boxes on their edges unless asked.", "parameters": {"properties": {"action": {"description": "The action to perform. The available actions are:\n* `key`: Performs key down presses on the arguments passed in order, then performs key releases in reverse order.\n* `type`: Type a string of text on the keyboard.\n* `mouse_move`: Move the cursor to a specified (x, y) pixel coordinate on the screen.\n* `left_click`: Click the left mouse button.\n* `left_click_drag`: Click and drag the cursor to a specified (x, y) pixel coordinate on the screen.\n* `right_click`: Click the right mouse button.\n* `middle_click`: Click the middle mouse button.\n* `double_click`: Double-click the left mouse button.\n* `scroll`: Performs a scroll of the mouse scroll wheel.\n* `wait`: Wait specified seconds for the change to happen.\n* `terminate`: Terminate the current task and report its completion status.", "enum": ["key", "type", "mouse_move", "left_click", "left_click_drag", "right_click", "middle_click", "double_click", "scroll", "wait", "terminate"], "type": "string"}, "keys": {"description": "Required only by `action=key`.", "type": "array"}, "text": {"description": "Required only by `action=type`.", "type": "string"}, "coordinate": {"description": "(x, y): The x (pixels from the left edge) and y (pixels from the top edge) coordinates to move the mouse to. Required only by `action=mouse_move`, `action=left_click_drag`, `action=left_click`, `action=right_click`, `action=double_click`.", "type": "array"}, "pixels": {"description": "The amount of scrolling to perform. Positive values scroll up, negative values scroll down. Required only by `action=scroll`.", "type": "number"}, "time": {"description": "The seconds to wait. Required only by `action=wait`.", "type": "number"}, "status": {"description": "The status of the task. Required only by `action=terminate`.", "type": "string", "enum": ["success", "failure"]}}, "required": ["action"], "type": "object"}}}
+</tools>
+For each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:
+<tool_call>
+{"name": <function-name>, "arguments": <args-json-object>}
+</tool_call>
+"""
+
+
+def parse_drag_coordinates(response: str):
+    """Match the first mouse_move/left_click + left_click_drag pair."""
+    matches = re.findall(r"<tool_call>\s*(\{.*?\})\s*</tool_call>", response, flags=re.DOTALL)
+    if len(matches) < 2:
+        return None
+
+    first = json.loads(matches[0])
+    second = json.loads(matches[1])
+
+    first_action = first["arguments"].get("action")
+    second_action = second["arguments"].get("action")
+    if first_action not in ("mouse_move", "left_click"):
+        return None
+    if second_action != "left_click_drag":
+        return None
+
+    start = first["arguments"].get("coordinate")
+    end = second["arguments"].get("coordinate")
+    if not start or not end:
+        return None
+
+    return start, end
+
+
+def resize_back(coord, original_size, resized_size):
+    ox, oy = original_size
+    rx, ry = resized_size
+    return round(coord[0] * ox / rx), round(coord[1] * oy / ry)
+
+
+def annotate_drag(image: Image.Image, start, end, save_path: Path):
+    draw = ImageDraw.Draw(image)
+    draw.ellipse((start[0] - 8, start[1] - 8, start[0] + 8, start[1] + 8), outline="lime", width=2)
+    draw.ellipse((end[0] - 8, end[1] - 8, end[0] + 8, end[1] + 8), outline="red", width=2)
+    draw.line((*start, *end), fill="yellow", width=3)
+    image.save(save_path)
+
+
+def main():
+    image = Image.open("demo_image.png")
+    instruction = "Drag to select the highlighted paragraph."
+
+    resized_h, resized_w = qwen_smart_resize(image.height, image.width, max_pixels=2_116_800, min_pixels=12_544)
+
+    # vLLM + tokenizer initialisation
+    llm = LLM(model=MODEL_ID, trust_remote_code=True, tokenizer_mode="slow", dtype="bfloat16")
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, trust_remote_code=True, use_fast=False)
+    chat_tpl_path = hf_hub_download(repo_id=MODEL_ID, filename="chat_template.json")
+    tokenizer.chat_template = json.loads(Path(chat_tpl_path).read_text())["chat_template"]
+
+    messages = [
+        {
+            "role": "system",
+            "content": [{"type": "text", "text": FN_CALL_TEMPLATE.format(width=resized_w, height=resized_h)}],
+        },
+        {
+            "role": "user",
+            "content": [
+                {"type": "image"},
+                {"type": "text", "text": instruction},
+            ],
+        },
+    ]
+
+    prompt_token_ids = tokenizer.apply_chat_template(messages, add_generation_prompt=True)
+    sampling = SamplingParams(temperature=0.01, top_k=1, max_tokens=1024)
+
+    outputs = llm.generate(
+        {
+            "prompt_token_ids": prompt_token_ids,
+            "multi_modal_data": {"image": image},
+        },
+        sampling_params=sampling,
+    )
+
+    generated_ids = outputs[0].outputs[0].token_ids
+    response = tokenizer.decode(generated_ids, skip_special_tokens=True)
+    drag = parse_drag_coordinates(response)
+    if not drag:
+        print("Model did not produce a valid drag action.")
+        return
+
+    # map coordinates back to the original resolution
+    raw_start, raw_end = drag
+    start = resize_back(raw_start, image.size, (resized_w, resized_h))
+    end = resize_back(raw_end, image.size, (resized_w, resized_h))
+
+    print("Predicted drag:", start, "→", end)
+    annotate_drag(image.copy(), start, end, Path("GUI-Drag-7B_demo.png"))
+
+
+if __name__ == "__main__":
+    main()
+```