# Long Screenshot Segmentation
[](https://pypi.org/project/long-screenshot-segmentation/)
[](https://github.com/Tinnci/Long-Screenshot-Segmentation/actions/workflows/python-publish.yml)
[](https://pypi.org/project/long-screenshot-segmentation/)
[](README-ZH.md)
[](README.md)
## Features
- **Dual Detection Methods** — Combines blank space detection and color-based splitting for accurate segmentation
- **Unicode File Support** — Handles filenames with Chinese characters and other non-ASCII characters
- **Export Segments** — Save individual segmented areas as standalone images
- **Auto-Crop** — Intelligently removes blank/white margins while preserving all text and content
- **Flexible Thresholds** — Customize detection sensitivity for different image types
- **Multiple Output Formats** — Get split points, draw lines, or export segments
- **Cross-Platform** — Works on Windows, Linux, and macOS
## Methodology
The segmentation process is based on two main computer vision techniques:
### 1. Blank Space Detection
This method identifies horizontal blank spaces in the screenshot. It works by calculating the **Laplacian variance** for each row of pixels in the image. A low variance indicates a region with little change, which is likely a blank space. The algorithm identifies these low-variance regions and marks their vertical midpoints as potential split points.
### 2. Color-Based Detection
This method detects sharp changes in color between adjacent rows of pixels. It calculates the average color for each row and then computes the color difference between consecutive rows. A large color difference suggests a visual separation and is marked as a potential split point.
### 3. Merging Split Points
After identifying all potential split points from both methods, the algorithm merges any points that are too close to each other. This is done to avoid over-segmentation and to ensure that the resulting images are meaningful and not too small.
## Installation
To install the package from this repository, navigate to the project's root directory and run:
```bash
pip install .
```
Or install directly from PyPI:
```bash
pip install long-screenshot-segmentation
```
Alternatively, for a more isolated and efficient installation of the command-line tools, you can use `uv tool install`:
```bash
uv tool install long-screenshot-segmentation
```
## Usage
### Command-Line Interface
This package provides three command-line tools for easy use:
#### `screenshot-segment`
This is the main tool for finding the split points in an image.
```bash
screenshot-segment <image_file> [OPTIONS]
```
**Options:**
- `-f, --file`: Path to the image file (required)
- `-s, --split`: Save image with split lines drawn (default: False)
- `-o, --output_dir`: Output directory for split image (default: `result`)
- `-ht, --height_threshold`: Blank area height threshold (default: 102)
- `-vt, --variation_threshold`: Variation threshold (default: 0.5)
- `-ct, --color_threshold`: Color difference threshold (default: 100)
- `-cvt, --color_variation_threshold`: Color variation threshold (default: 15)
- `-mt, --merge_threshold`: Minimum distance between split lines (default: 350)
- `-e, --export`: Export segments as separate images (default: False)
- `-seg, --segments_dir`: Directory to save segment images (default: `segments`)
- `-crop, --auto_crop`: Auto-crop blank areas from segment edges (default: False)
- `-crop_t, --crop_threshold`: Threshold for detecting blank areas (default: 240)
- `-crop_h, --crop_min_width`: Minimum width to preserve after cropping (default: 50)
**Examples:**
```bash
# Get the split points for an image
screenshot-segment my_screenshot.png
# Save the image with the split lines drawn
screenshot-segment my_screenshot.png -s True
# Export segments as separate images
screenshot-segment my_screenshot.png -e True
# Export segments with auto-crop to remove blank margins
screenshot-segment my_screenshot.png -e True -crop True
# Custom parameters
screenshot-segment my_screenshot.png \
-ht 150 \
-vt 0.3 \
-ct 120 \
-mt 400 \
-e True \
-crop True \
-crop_t 230
```
#### `screenshot-draw`
This tool allows you to draw lines on an image at specified heights.
```bash
screenshot-draw <image_file> --heights <h1, h2, ...> [--color <b,g,r>] [--output_dir <dir>]
```
- `<image_file>`: Path to the image file.
- `--heights`: A list of heights to draw lines at.
- `--color`: The color of the lines in B,G,R format (e.g., '0,0,255' for red).
- `--output_dir`: The directory to save the output image (default: `result`).
**Example:**
```bash
screenshot-draw my_screenshot.png --heights 100 200 300
```
#### `screenshot-split`
This tool splits an image into multiple parts based on a list of heights.
```bash
screenshot-split <image_file> --heights <h1, h2, ...> [--output_dir <dir>]
```
- `<image_file>`: Path to the image file.
- `--heights`: A list of heights to split the image at.
- `--output_dir`: The directory to save the split images (default: `split_images`).
**Example:**
```bash
screenshot-split my_screenshot.png --heights 868 1912 2672
```
### Python API
You can also use the library directly in your Python code:
#### `split_heights`
The `split_heights` function is the main function for finding the split points.
```python
from Web_page_Screenshot_Segmentation.master import split_heights
# Get the split points for an image
heights = split_heights("my_screenshot.png")
print(heights)
# Save the image with the split lines drawn
result_path = split_heights("my_screenshot.png", split=True)
print(f"Image saved to: {result_path}")
```
### `split_and_export_segments`
Export segmented areas as separate standalone images, with optional auto-crop.
```python
from Web_page_Screenshot_Segmentation.master import split_and_export_segments
# Export all segments without cropping
output_dir = split_and_export_segments(
"my_screenshot.png",
output_dir="segments"
)
print(f"Segments saved to: {output_dir}")
# Export with auto-crop to remove blank margins
output_dir = split_and_export_segments(
"my_screenshot.png",
output_dir="segments_cropped",
auto_crop=True,
crop_threshold=240,
crop_min_width=50
)
print(f"Cropped segments saved to: {output_dir}")
```
**Parameters:**
- `file_path`: Path to the image file
- `output_dir`: Directory to save segments (default: `segments`)
- `auto_crop`: Whether to remove blank areas (default: False)
- `crop_threshold`: Pixel threshold for blank detection (0-255, default: 240)
- `crop_min_width`: Minimum width to preserve (default: 50)
- `height_threshold`, `variation_threshold`, `color_threshold`, `color_variation_threshold`, `merge_threshold`: Same as `split_heights`
**Auto-Crop Algorithm:**
The auto-crop feature intelligently detects content by analyzing:
1. **Pixel Variance** — Text and graphics have varying pixel values
2. **Dark Pixels** — Content is typically darker than the white background
Any column with significant variance or dark pixels is preserved. Only truly blank columns are removed.
#### `draw_line_from_file`
The `draw_line_from_file` function allows you to draw lines on an image.
```python
from Web_page_Screenshot_Segmentation.drawer import draw_line_from_file
result_path = draw_line_from_file("my_screenshot.png", heights=[100, 200, 300])
print(f"Image saved to: {result_path}")
```
#### `split_and_save_image`
The `split_and_save_image` function splits an image into multiple parts.
```python
import cv2
from Web_page_Screenshot_Segmentation.spliter import split_and_save_image
image = cv2.imread("my_screenshot.png")
result_path = split_and_save_image(image, heights=[868, 1912, 2672], output_dir="my_split_images")
print(f"Images saved to: {result_path}")
```
## Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue.
To set up the development environment:
1. Clone the repository.
2. Create a virtual environment and activate it.
3. Install the dependencies: `pip install -e .[dev]`
## Acknowledgments
This project is a fork of the [Long-Screenshot-Segmentation](https://github.com/Tim-Saijun/Long-Screenshot-Segmentation) repository by [Tim-Saijun](https://github.com/Tim-Saijun). We are grateful for their original work.
Raw data
{
"_id": null,
"home_page": null,
"name": "long-screenshot-segmentation",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "opencv, website, image segmentation, screenshot, gpt",
"author": null,
"author_email": "Tinnci <t88444281@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5b/7d/66d295a0e40d180f376cfc05f40aab81658ace46c7adf60fa844e74262af/long_screenshot_segmentation-1.1.1.tar.gz",
"platform": null,
"description": "# Long Screenshot Segmentation\r\n\r\n[](https://pypi.org/project/long-screenshot-segmentation/)\r\n[](https://github.com/Tinnci/Long-Screenshot-Segmentation/actions/workflows/python-publish.yml)\r\n[](https://pypi.org/project/long-screenshot-segmentation/)\r\n[](README-ZH.md)\r\n[](README.md)\r\n\r\n## Features\r\n\r\n- **Dual Detection Methods** \u2014 Combines blank space detection and color-based splitting for accurate segmentation\r\n- **Unicode File Support** \u2014 Handles filenames with Chinese characters and other non-ASCII characters\r\n- **Export Segments** \u2014 Save individual segmented areas as standalone images\r\n- **Auto-Crop** \u2014 Intelligently removes blank/white margins while preserving all text and content\r\n- **Flexible Thresholds** \u2014 Customize detection sensitivity for different image types\r\n- **Multiple Output Formats** \u2014 Get split points, draw lines, or export segments\r\n- **Cross-Platform** \u2014 Works on Windows, Linux, and macOS\r\n\r\n## Methodology\r\n\r\nThe segmentation process is based on two main computer vision techniques:\r\n\r\n### 1. Blank Space Detection\r\n\r\nThis method identifies horizontal blank spaces in the screenshot. It works by calculating the **Laplacian variance** for each row of pixels in the image. A low variance indicates a region with little change, which is likely a blank space. The algorithm identifies these low-variance regions and marks their vertical midpoints as potential split points.\r\n\r\n### 2. Color-Based Detection\r\n\r\nThis method detects sharp changes in color between adjacent rows of pixels. It calculates the average color for each row and then computes the color difference between consecutive rows. A large color difference suggests a visual separation and is marked as a potential split point.\r\n\r\n### 3. Merging Split Points\r\n\r\nAfter identifying all potential split points from both methods, the algorithm merges any points that are too close to each other. This is done to avoid over-segmentation and to ensure that the resulting images are meaningful and not too small.\r\n\r\n## Installation\r\n\r\nTo install the package from this repository, navigate to the project's root directory and run:\r\n\r\n```bash\r\npip install .\r\n```\r\n\r\nOr install directly from PyPI:\r\n\r\n```bash\r\npip install long-screenshot-segmentation\r\n```\r\n\r\nAlternatively, for a more isolated and efficient installation of the command-line tools, you can use `uv tool install`:\r\n\r\n```bash\r\nuv tool install long-screenshot-segmentation\r\n```\r\n\r\n## Usage\r\n\r\n### Command-Line Interface\r\n\r\nThis package provides three command-line tools for easy use:\r\n\r\n#### `screenshot-segment`\r\n\r\nThis is the main tool for finding the split points in an image.\r\n\r\n```bash\r\nscreenshot-segment <image_file> [OPTIONS]\r\n```\r\n\r\n**Options:**\r\n- `-f, --file`: Path to the image file (required)\r\n- `-s, --split`: Save image with split lines drawn (default: False)\r\n- `-o, --output_dir`: Output directory for split image (default: `result`)\r\n- `-ht, --height_threshold`: Blank area height threshold (default: 102)\r\n- `-vt, --variation_threshold`: Variation threshold (default: 0.5)\r\n- `-ct, --color_threshold`: Color difference threshold (default: 100)\r\n- `-cvt, --color_variation_threshold`: Color variation threshold (default: 15)\r\n- `-mt, --merge_threshold`: Minimum distance between split lines (default: 350)\r\n- `-e, --export`: Export segments as separate images (default: False)\r\n- `-seg, --segments_dir`: Directory to save segment images (default: `segments`)\r\n- `-crop, --auto_crop`: Auto-crop blank areas from segment edges (default: False)\r\n- `-crop_t, --crop_threshold`: Threshold for detecting blank areas (default: 240)\r\n- `-crop_h, --crop_min_width`: Minimum width to preserve after cropping (default: 50)\r\n\r\n**Examples:**\r\n\r\n```bash\r\n# Get the split points for an image\r\nscreenshot-segment my_screenshot.png\r\n\r\n# Save the image with the split lines drawn\r\nscreenshot-segment my_screenshot.png -s True\r\n\r\n# Export segments as separate images\r\nscreenshot-segment my_screenshot.png -e True\r\n\r\n# Export segments with auto-crop to remove blank margins\r\nscreenshot-segment my_screenshot.png -e True -crop True\r\n\r\n# Custom parameters\r\nscreenshot-segment my_screenshot.png \\\r\n -ht 150 \\\r\n -vt 0.3 \\\r\n -ct 120 \\\r\n -mt 400 \\\r\n -e True \\\r\n -crop True \\\r\n -crop_t 230\r\n```\r\n\r\n#### `screenshot-draw`\r\n\r\nThis tool allows you to draw lines on an image at specified heights.\r\n\r\n```bash\r\nscreenshot-draw <image_file> --heights <h1, h2, ...> [--color <b,g,r>] [--output_dir <dir>]\r\n```\r\n\r\n- `<image_file>`: Path to the image file.\r\n- `--heights`: A list of heights to draw lines at.\r\n- `--color`: The color of the lines in B,G,R format (e.g., '0,0,255' for red).\r\n- `--output_dir`: The directory to save the output image (default: `result`).\r\n\r\n**Example:**\r\n\r\n```bash\r\nscreenshot-draw my_screenshot.png --heights 100 200 300\r\n```\r\n\r\n#### `screenshot-split`\r\n\r\nThis tool splits an image into multiple parts based on a list of heights.\r\n\r\n```bash\r\nscreenshot-split <image_file> --heights <h1, h2, ...> [--output_dir <dir>]\r\n```\r\n\r\n- `<image_file>`: Path to the image file.\r\n- `--heights`: A list of heights to split the image at.\r\n- `--output_dir`: The directory to save the split images (default: `split_images`).\r\n\r\n**Example:**\r\n\r\n```bash\r\nscreenshot-split my_screenshot.png --heights 868 1912 2672\r\n```\r\n\r\n### Python API\r\n\r\nYou can also use the library directly in your Python code:\r\n\r\n#### `split_heights`\r\n\r\nThe `split_heights` function is the main function for finding the split points.\r\n\r\n```python\r\nfrom Web_page_Screenshot_Segmentation.master import split_heights\r\n\r\n# Get the split points for an image\r\nheights = split_heights(\"my_screenshot.png\")\r\nprint(heights)\r\n\r\n# Save the image with the split lines drawn\r\nresult_path = split_heights(\"my_screenshot.png\", split=True)\r\nprint(f\"Image saved to: {result_path}\")\r\n```\r\n\r\n### `split_and_export_segments`\r\n\r\nExport segmented areas as separate standalone images, with optional auto-crop.\r\n\r\n```python\r\nfrom Web_page_Screenshot_Segmentation.master import split_and_export_segments\r\n\r\n# Export all segments without cropping\r\noutput_dir = split_and_export_segments(\r\n \"my_screenshot.png\",\r\n output_dir=\"segments\"\r\n)\r\nprint(f\"Segments saved to: {output_dir}\")\r\n\r\n# Export with auto-crop to remove blank margins\r\noutput_dir = split_and_export_segments(\r\n \"my_screenshot.png\",\r\n output_dir=\"segments_cropped\",\r\n auto_crop=True,\r\n crop_threshold=240,\r\n crop_min_width=50\r\n)\r\nprint(f\"Cropped segments saved to: {output_dir}\")\r\n```\r\n\r\n**Parameters:**\r\n- `file_path`: Path to the image file\r\n- `output_dir`: Directory to save segments (default: `segments`)\r\n- `auto_crop`: Whether to remove blank areas (default: False)\r\n- `crop_threshold`: Pixel threshold for blank detection (0-255, default: 240)\r\n- `crop_min_width`: Minimum width to preserve (default: 50)\r\n- `height_threshold`, `variation_threshold`, `color_threshold`, `color_variation_threshold`, `merge_threshold`: Same as `split_heights`\r\n\r\n**Auto-Crop Algorithm:**\r\nThe auto-crop feature intelligently detects content by analyzing:\r\n1. **Pixel Variance** \u2014 Text and graphics have varying pixel values\r\n2. **Dark Pixels** \u2014 Content is typically darker than the white background\r\n\r\nAny column with significant variance or dark pixels is preserved. Only truly blank columns are removed.\r\n\r\n#### `draw_line_from_file`\r\n\r\nThe `draw_line_from_file` function allows you to draw lines on an image.\r\n\r\n```python\r\nfrom Web_page_Screenshot_Segmentation.drawer import draw_line_from_file\r\n\r\nresult_path = draw_line_from_file(\"my_screenshot.png\", heights=[100, 200, 300])\r\nprint(f\"Image saved to: {result_path}\")\r\n```\r\n\r\n#### `split_and_save_image`\r\n\r\nThe `split_and_save_image` function splits an image into multiple parts.\r\n\r\n```python\r\nimport cv2\r\nfrom Web_page_Screenshot_Segmentation.spliter import split_and_save_image\r\n\r\nimage = cv2.imread(\"my_screenshot.png\")\r\nresult_path = split_and_save_image(image, heights=[868, 1912, 2672], output_dir=\"my_split_images\")\r\nprint(f\"Images saved to: {result_path}\")\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a pull request or open an issue.\r\n\r\nTo set up the development environment:\r\n\r\n1. Clone the repository.\r\n2. Create a virtual environment and activate it.\r\n3. Install the dependencies: `pip install -e .[dev]`\r\n\r\n## Acknowledgments\r\n\r\nThis project is a fork of the [Long-Screenshot-Segmentation](https://github.com/Tim-Saijun/Long-Screenshot-Segmentation) repository by [Tim-Saijun](https://github.com/Tim-Saijun). We are grateful for their original work.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Divide long web page screenshots into blocks to input models with shorter contexts. \u5c06\u957f\u7f51\u9875\u622a\u56fe\u8fdb\u884c\u533a\u5757\u5206\u5272\uff0c\u7528\u4e8e\u8f93\u5165\u4e0a\u4e0b\u6587\u8f83\u77ed\u7684\u6a21\u578b",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/Tinnci/Long-Screenshot-Segmentation/issues",
"Homepage": "https://github.com/Tinnci/Long-Screenshot-Segmentation",
"Repository": "https://github.com/Tinnci/Long-Screenshot-Segmentation",
"Upstream": "https://github.com/Ryaang/Web-page-Screenshot-Segmentation"
},
"split_keywords": [
"opencv",
" website",
" image segmentation",
" screenshot",
" gpt"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f9136356c0987219d95391a6de8011ab6a014d471d0917cc10e4b2061d8d5330",
"md5": "5184a7ad2a66b539cd5678a28138986a",
"sha256": "be28a3f1da63038eb67c4139c9b0e3f7bb408f0a31bad1987ff43d5dc4abdaca"
},
"downloads": -1,
"filename": "long_screenshot_segmentation-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5184a7ad2a66b539cd5678a28138986a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14964,
"upload_time": "2025-10-25T10:52:59",
"upload_time_iso_8601": "2025-10-25T10:52:59.731290Z",
"url": "https://files.pythonhosted.org/packages/f9/13/6356c0987219d95391a6de8011ab6a014d471d0917cc10e4b2061d8d5330/long_screenshot_segmentation-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b7d66d295a0e40d180f376cfc05f40aab81658ace46c7adf60fa844e74262af",
"md5": "95e35145b1bd401c04d41f6e63c36cf2",
"sha256": "e3456eeac824fef9f58a14bff1c3ddf1c760329d9c15adb61e2d6cff544640b8"
},
"downloads": -1,
"filename": "long_screenshot_segmentation-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "95e35145b1bd401c04d41f6e63c36cf2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17976,
"upload_time": "2025-10-25T10:53:01",
"upload_time_iso_8601": "2025-10-25T10:53:01.973854Z",
"url": "https://files.pythonhosted.org/packages/5b/7d/66d295a0e40d180f376cfc05f40aab81658ace46c7adf60fa844e74262af/long_screenshot_segmentation-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 10:53:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Tinnci",
"github_project": "Long-Screenshot-Segmentation",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "long-screenshot-segmentation"
}
JSON
