sparc-visualization 0.1.0__tar.gz

sparc_visualization-0.1.0/LICENCE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Florian Valentin Wunderlich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 

sparc_visualization-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: sparc-visualization
+Version: 0.1.0
+Summary: 
+License-Expression: MIT
+License-File: LICENCE.txt
+Author: Florian Valentin Wunderlich
+Author-email: florian.valentin.wunderlich@gmail.com
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: Pillow (>=12)
+Description-Content-Type: text/markdown
+
+## Overview
+
+SPaRC (sparc-puzzle) provides a comprehensive framework for evaluating language models on spatial reasoning tasks inspired by "The Witness" puzzle game.
+This package (sparc-visualization) includes various visual puzzle representations and an improved visual reasoning prompt to complement the functionality of the sparc-puzzle package.
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+pip install sparc-visualization
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/flowun/sparc-visualization.git
+cd sparc-visualization
+pip install -e .
+```
+
+
+
+### Example Usage
+
+
+```python
+from sparc_visualization.plot import get_puzzle_image
+from sparc_visualization.prompt import generate_prompt
+from sparc.validation import extract_solution_path, validate_solution, analyze_path
+from datasets import load_dataset
+
+# Load the dataset
+dataset = load_dataset("lkaesberg/SPaRC", "all", split="test")
+puzzle = dataset[0]
+
+puzzle_image = get_puzzle_image(puzzle, plot_type="path_cell_annotated")
+
+# Generate prompt and image, e.g.
+plot_type = "path_cell_annotated"
+prompt_type = "prompt_engineering"
+
+b64_image = get_puzzle_image(puzzle, plot_type=plot_type, base_64_image=True)
+text_prompt = generate_prompt(puzzle, plot_type, prompt_type)
+
+# create message array and payload for an LLM
+puzzle_prompt = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": f"data:image/png;base64,{b64_image}"
+                    }
+                },
+                {
+                    "type": "text",
+                    "text": text_prompt
+                }
+            ]
+        }
+    ]
+
+payload = {
+    "model": your_model_name,
+    "messages": puzzle_prompt,
+    "temperature": temperature,
+    "max_tokens": max_tokens,
+}
+
+# Your model generates a response
+model_response = "... model response with path coordinates ..."
+
+# Analysis using sparc-puzzle package
+
+# Extract the path from model response
+extracted_path = extract_solution_path(model_response, puzzle)
+# Returns: [{"x": 0, "y": 2}, {"x": 0, "y": 1}, ...]
+
+# Validate against ground truth
+is_correct = validate_solution(extracted_path, puzzle)
+# Returns: True/False
+
+# Get detailed analysis
+analysis = analyze_path(extracted_path, puzzle)
+# Returns: {
+#   "starts_at_start_ends_at_exit": True,
+#   "connected_line": True,
+#   "non_intersecting_line": True,
+#   "no_rule_crossing": True,
+#   "fully_valid_path": True
+# }
+```
+
+### Core Functions
+
+`get_puzzle_image(puzzle: Dict, plot_type: str = "original", base_64_image: bool = False, show_plot: bool = False, save_to_disk: bool = False, save_dir: str = ".", save_filename: str = "puzzle_image.png") -> PIL.Image.Image | str`
+Renders a SPaRC puzzle into one of the supported visual representations (`plot_type` values). To get a base64-encoded string of the image suitable for LLM input, set `base_64_image=True`.
+Besides returning the image object or base64 string, the function has options to display the image (`show_plot=True`) or save it to disk (`save_to_disk=True`).
+
+`generate_prompt(puzzle: Dict, plot_type: str = "original", prompt_type: str = "prompt_engineering") -> str`
+Generates the text prompt (based on `prompt_type` values) that should be paired with the rendered image for an LLM call.
+Available `prompt_type` values are:
+- "default_tr": visual prompt from the SPaRC paper (with textual coordinates)
+- "default_no_tr": visual prompt from the SPaRC paper (however with textual coordinates removed)
+- "prompt_engineering": improved vision-only prompt with prompt engineering (no textual coordinates)
+`puzzle` and `plot_type` should be provided the same as in `get_puzzle_image` to allow small prompt adjustments.
+
+### Available Puzzle Representations (`plot_type`)
+
+<table>
+  <tr>
+    <td align="center">
+      <code>original</code><br/>
+      <img src="docs/images/original.png" alt="original" width="200" />
+    </td>
+    <td align="center">
+      <code>start_end_marked</code><br/>
+      <img src="docs/images/start_end_marked.png" alt="start_end_marked" width="200" />
+    </td>
+    <td align="center">
+      <code>coordinate_grid</code><br/>
+      <img src="docs/images/coordinate_grid.png" alt="coordinate_grid" width="200" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <code>coordinate_grid_and_start_end_marked</code><br/>
+      <img src="docs/images/coordinate_grid_and_start_end_marked.png" alt="coordinate_grid_and_start_end_marked" width="200" />
+    </td>
+    <td align="center">
+      <code>path_cell_annotated</code><br/>
+      <img src="docs/images/path_cell_annotated.png" alt="path_cell_annotated" width="200" />
+    </td>
+    <td align="center">
+      <code>text</code><br/>
+      <img src="docs/images/text.png" alt="text" width="200" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <code>low_contrast</code><br/>
+      <img src="docs/images/low_contrast.png" alt="low_contrast" width="200" />
+    </td>
+    <td align="center">
+      <code>low_contrast_and_path_cell_annotated</code><br/>
+      <img src="docs/images/low_contrast_and_path_cell_annotated.png" alt="low_contrast_and_path_cell_annotated" width="200" />
+    </td>
+    <td align="center">
+      <code>low_resolution</code><br/>
+      <img src="docs/images/low_resolution.png" alt="low_resolution" width="200" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <code>low_resolution_and_path_cell_annotated</code><br/>
+      <img src="docs/images/low_resolution_and_path_cell_annotated.png" alt="low_resolution_and_path_cell_annotated" width="200" />
+    </td>
+    <td align="center">
+      <code>rotated</code><br/>
+      <img src="docs/images/rotated.png" alt="rotated" width="200" />
+    </td>
+    <td align="center">
+      <code>rotated_and_path_cell_annotated</code><br/>
+      <img src="docs/images/rotated_and_path_cell_annotated.png" alt="rotated_and_path_cell_annotated" width="200" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <code>black_frame</code><br/>
+      <img src="docs/images/black_frame.png" alt="black_frame" width="200" />
+    </td>
+    <td align="center">
+      <code>black_frame_and_path_cell_annotated</code><br/>
+      <img src="docs/images/black_frame_and_path_cell_annotated.png" alt="black_frame_and_path_cell_annotated" width="200" />
+    </td>
+    <td></td>
+  </tr>
+</table>
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit pull requests or open issues.
+
+## Citation
+
+If you use SPaRC in your research, please cite:
+
+```bibtex
+@article{kaesberg2025sparc,
+  title     = {SPaRC: A Spatial Pathfinding Reasoning Challenge},
+  author    = {Kaesberg, Lars Benedikt and Wahle, Jan Philip and Ruas, Terry and Gipp, Bela},
+  year      = {2025},
+  url       = {https://arxiv.org/abs/2505.16686}
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Links
+
+- 🌐 **Website**: [sparc.gipplab.org](https://sparc.gipplab.org/)
+- 📚 **Dataset**: [Hugging Face](https://huggingface.co/datasets/lkaesberg/SPaRC)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/flowun/sparc-visualization/issues)
+- 📖 **Documentation**: [GitHub Repository](https://github.com/flowun/sparc-visualization)
+
+

sparc_visualization-0.1.0/README.md

@@ -0,0 +1,210 @@
+## Overview
+
+SPaRC (sparc-puzzle) provides a comprehensive framework for evaluating language models on spatial reasoning tasks inspired by "The Witness" puzzle game.
+This package (sparc-visualization) includes various visual puzzle representations and an improved visual reasoning prompt to complement the functionality of the sparc-puzzle package.
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+pip install sparc-visualization
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/flowun/sparc-visualization.git
+cd sparc-visualization
+pip install -e .
+```
+
+
+
+### Example Usage
+
+
+```python
+from sparc_visualization.plot import get_puzzle_image
+from sparc_visualization.prompt import generate_prompt
+from sparc.validation import extract_solution_path, validate_solution, analyze_path
+from datasets import load_dataset
+
+# Load the dataset
+dataset = load_dataset("lkaesberg/SPaRC", "all", split="test")
+puzzle = dataset[0]
+
+puzzle_image = get_puzzle_image(puzzle, plot_type="path_cell_annotated")
+
+# Generate prompt and image, e.g.
+plot_type = "path_cell_annotated"
+prompt_type = "prompt_engineering"
+
+b64_image = get_puzzle_image(puzzle, plot_type=plot_type, base_64_image=True)
+text_prompt = generate_prompt(puzzle, plot_type, prompt_type)
+
+# create message array and payload for an LLM
+puzzle_prompt = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": f"data:image/png;base64,{b64_image}"
+                    }
+                },
+                {
+                    "type": "text",
+                    "text": text_prompt
+                }
+            ]
+        }
+    ]
+
+payload = {
+    "model": your_model_name,
+    "messages": puzzle_prompt,
+    "temperature": temperature,
+    "max_tokens": max_tokens,
+}
+
+# Your model generates a response
+model_response = "... model response with path coordinates ..."
+
+# Analysis using sparc-puzzle package
+
+# Extract the path from model response
+extracted_path = extract_solution_path(model_response, puzzle)
+# Returns: [{"x": 0, "y": 2}, {"x": 0, "y": 1}, ...]
+
+# Validate against ground truth
+is_correct = validate_solution(extracted_path, puzzle)
+# Returns: True/False
+
+# Get detailed analysis
+analysis = analyze_path(extracted_path, puzzle)
+# Returns: {
+#   "starts_at_start_ends_at_exit": True,
+#   "connected_line": True,
+#   "non_intersecting_line": True,
+#   "no_rule_crossing": True,
+#   "fully_valid_path": True
+# }
+```
+
+### Core Functions
+
+`get_puzzle_image(puzzle: Dict, plot_type: str = "original", base_64_image: bool = False, show_plot: bool = False, save_to_disk: bool = False, save_dir: str = ".", save_filename: str = "puzzle_image.png") -> PIL.Image.Image | str`
+Renders a SPaRC puzzle into one of the supported visual representations (`plot_type` values). To get a base64-encoded string of the image suitable for LLM input, set `base_64_image=True`.
+Besides returning the image object or base64 string, the function has options to display the image (`show_plot=True`) or save it to disk (`save_to_disk=True`).
+
+`generate_prompt(puzzle: Dict, plot_type: str = "original", prompt_type: str = "prompt_engineering") -> str`
+Generates the text prompt (based on `prompt_type` values) that should be paired with the rendered image for an LLM call.
+Available `prompt_type` values are:
+- "default_tr": visual prompt from the SPaRC paper (with textual coordinates)
+- "default_no_tr": visual prompt from the SPaRC paper (however with textual coordinates removed)
+- "prompt_engineering": improved vision-only prompt with prompt engineering (no textual coordinates)
+`puzzle` and `plot_type` should be provided the same as in `get_puzzle_image` to allow small prompt adjustments.
+
+### Available Puzzle Representations (`plot_type`)
+
+<table>
+  <tr>
+    <td align="center">
+      <code>original</code><br/>
+      <img src="docs/images/original.png" alt="original" width="200" />
+    </td>
+    <td align="center">
+      <code>start_end_marked</code><br/>
+      <img src="docs/images/start_end_marked.png" alt="start_end_marked" width="200" />
+    </td>
+    <td align="center">
+      <code>coordinate_grid</code><br/>
+      <img src="docs/images/coordinate_grid.png" alt="coordinate_grid" width="200" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <code>coordinate_grid_and_start_end_marked</code><br/>
+      <img src="docs/images/coordinate_grid_and_start_end_marked.png" alt="coordinate_grid_and_start_end_marked" width="200" />
+    </td>
+    <td align="center">
+      <code>path_cell_annotated</code><br/>
+      <img src="docs/images/path_cell_annotated.png" alt="path_cell_annotated" width="200" />
+    </td>
+    <td align="center">
+      <code>text</code><br/>
+      <img src="docs/images/text.png" alt="text" width="200" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <code>low_contrast</code><br/>
+      <img src="docs/images/low_contrast.png" alt="low_contrast" width="200" />
+    </td>
+    <td align="center">
+      <code>low_contrast_and_path_cell_annotated</code><br/>
+      <img src="docs/images/low_contrast_and_path_cell_annotated.png" alt="low_contrast_and_path_cell_annotated" width="200" />
+    </td>
+    <td align="center">
+      <code>low_resolution</code><br/>
+      <img src="docs/images/low_resolution.png" alt="low_resolution" width="200" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <code>low_resolution_and_path_cell_annotated</code><br/>
+      <img src="docs/images/low_resolution_and_path_cell_annotated.png" alt="low_resolution_and_path_cell_annotated" width="200" />
+    </td>
+    <td align="center">
+      <code>rotated</code><br/>
+      <img src="docs/images/rotated.png" alt="rotated" width="200" />
+    </td>
+    <td align="center">
+      <code>rotated_and_path_cell_annotated</code><br/>
+      <img src="docs/images/rotated_and_path_cell_annotated.png" alt="rotated_and_path_cell_annotated" width="200" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <code>black_frame</code><br/>
+      <img src="docs/images/black_frame.png" alt="black_frame" width="200" />
+    </td>
+    <td align="center">
+      <code>black_frame_and_path_cell_annotated</code><br/>
+      <img src="docs/images/black_frame_and_path_cell_annotated.png" alt="black_frame_and_path_cell_annotated" width="200" />
+    </td>
+    <td></td>
+  </tr>
+</table>
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit pull requests or open issues.
+
+## Citation
+
+If you use SPaRC in your research, please cite:
+
+```bibtex
+@article{kaesberg2025sparc,
+  title     = {SPaRC: A Spatial Pathfinding Reasoning Challenge},
+  author    = {Kaesberg, Lars Benedikt and Wahle, Jan Philip and Ruas, Terry and Gipp, Bela},
+  year      = {2025},
+  url       = {https://arxiv.org/abs/2505.16686}
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Links
+
+- 🌐 **Website**: [sparc.gipplab.org](https://sparc.gipplab.org/)
+- 📚 **Dataset**: [Hugging Face](https://huggingface.co/datasets/lkaesberg/SPaRC)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/flowun/sparc-visualization/issues)
+- 📖 **Documentation**: [GitHub Repository](https://github.com/flowun/sparc-visualization)
+

sparc_visualization-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "sparc-visualization"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "Florian Valentin Wunderlich",email = "florian.valentin.wunderlich@gmail.com"}
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "Pillow>=12",
+]
+
+[tool.poetry]
+name = "sparc-visualization"
+description = ""
+authors = ["Florian Valentin Wunderlich <florian.valentin.wunderlich@gmail.com>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+Pillow = ">=12"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

sparc_visualization-0.1.0/sparc_visualization/objects/board.py

@@ -0,0 +1,50 @@
+import json
+
+from sparc_visualization.objects.tile import Tile
+
+def get_board_from_data(data):
+    return Board(
+        height=data['grid_size']['height'],
+        width=data['grid_size']['width'],
+        difficulty_level=data['difficulty_level'],
+        difficulty_score=data['difficulty_score'],
+        id=data['id'],
+        polyshapes=data['polyshapes'],
+        puzzle_array=data['puzzle_array'],
+        solution_count=data['solution_count'],
+        solutions=data['solutions']
+    )
+
+
+class Board:
+    def __init__(self, height, width, difficulty_level, difficulty_score, id, polyshapes, puzzle_array, solution_count, solutions):
+        self.height = height * 2 + 1
+        self.width = width * 2 + 1
+        self.difficulty_level = difficulty_level
+        self.difficulty_score = difficulty_score
+        self.id = id
+        self.polyshapes = json.loads(polyshapes)
+        self.puzzle_array = puzzle_array
+        self.solution_count = solution_count
+        self.solutions = solutions
+        self.grid = [[None for _ in range(self.width)] for _ in range(self.height)]
+        self.place_all_objects()
+
+    def place_object(self, x, y, obj):
+        if 0 <= x < self.width and 0 <= y < self.height:
+            self.grid[y][x] = obj
+        else:
+            raise ValueError("Coordinates out of bounds")
+
+    def place_all_objects(self):
+        for y in range(self.height):
+            for x in range(self.width):
+                obj_abbr = self.puzzle_array[y][x]
+                obj = Tile(obj_abbr)
+                self.place_object(x, y, obj)
+
+    def get_object(self, x, y):
+        if 0 <= x < self.width and 0 <= y < self.height:
+            return self.grid[y][x]
+        else:
+            raise ValueError("Coordinates out of bounds")

sparc_visualization-0.1.0/sparc_visualization/objects/tile.py

@@ -0,0 +1,35 @@
+def get_type_from_abbreviation(abbreviation):
+    translation_dict = {
+            'S': 'Start',
+            'E': 'End',
+            '+': 'Walkable',
+            'N': 'Empty Rule',
+            'G': 'Gap',
+            '.': 'Dot',
+            'o': 'Stone',
+            '*': 'Star',
+            'A': 'Triangle',
+            'B': 'Triangle',
+            'C': 'Triangle',
+            'D': 'Triangle',
+            'P': 'Positive Polyshape',
+            'Y': 'Negative Polyshape'
+            }
+    return translation_dict[abbreviation]
+
+class Tile:
+    def __init__(self, abbreviation):
+        self.abbreviation = abbreviation
+        self.is_walkable = abbreviation in ['S', 'E', '+', '.']
+        self.is_rule_cell = abbreviation.startswith(('N', 'o', '*', 'A', 'B', 'C', 'D', 'P', 'Y'))
+        self.type = get_type_from_abbreviation(abbreviation[0])
+        self.color = None
+        self.shape_id = None
+        if '-' in abbreviation:
+            self.color = abbreviation.split('-')[1]
+        if self.abbreviation.startswith(('P', 'Y')):
+            parts = abbreviation.split('-')
+            self.shape_id = parts[2]
+        if self.abbreviation.startswith(('A', 'B', 'C', 'D')):
+            self.triangle_count = {'A': 1, 'B': 2, 'C': 3, 'D': 4}[abbreviation[0]]
+        # print(f"Created Tile: {self.name}, Walkable: {self.is_walkable}")

sparc_visualization-0.1.0/sparc_visualization/plot.py

@@ -0,0 +1,63 @@
+from sparc_visualization.plots.plot import get_plot_class
+from sparc_visualization.objects.board import get_board_from_data
+from sparc_visualization.util import encode_image_to_base64
+
+
+def get_puzzle_image(
+        puzzle,
+        plot_type="original",
+        base_64_image=False,
+        show_plot=False,
+        save_to_disk=False,
+        save_dir=".",
+        save_filename="puzzle_image.png",
+):
+    """Render a SPaRC puzzle and return it as a PIL image (or base64).
+
+    Parameters
+    ----------
+    puzzle:
+        The puzzle data of a single SPaRC puzzle.
+    plot_type:
+        - "original" (default)
+        - "start_end_marked"
+        - "coordinate_grid"
+        - "coordinate_grid_and_start_end_marked"
+        - "path_cell_annotated"
+        - "text"
+        - "low_contrast"
+        - "low_contrast_and_path_cell_annotated"
+        - "low_resolution"
+        - "low_resolution_and_path_cell_annotated"
+        - "rotated"
+        - "rotated_and_path_cell_annotated"
+        - "black_frame"
+        - "black_frame_and_path_cell_annotated"
+    base_64_image:
+        If True, returns a base64-encoded string instead of a PIL Image.
+    show_plot:
+        If True, shows the plot in a GUI window.
+    save_to_disk:
+        If True, saves the plot to disk.
+    save_dir:
+        Directory to save the plot if ``save_to_disk=True``.
+    save_filename:
+        Filename to save the plot if ``save_to_disk=True``.
+
+    Returns
+    -------
+    PIL.Image.Image | str
+        Either a PIL Image (default) or a base64-encoded string if ``base_64_image=True``.
+    """
+    board = get_board_from_data(puzzle)
+    plot = get_plot_class(plot_type, board, size=(board.width, board.height))
+    plot.render()
+    if save_to_disk:
+        plot.save(dir=save_dir, filename=save_filename)
+    if show_plot:
+        plot.show()
+    if base_64_image:
+        return encode_image_to_base64(plot._img)
+    else:
+        return plot._img
+