Skip to content

Commit d74debd

Browse files
KTS-o7KTS-o7
authored
Merge pull request #19 from KTS-o7/pr-18
Pr 18
2 parents f2d7fa3 + 10e081c commit d74debd

File tree

6 files changed

+620
-338
lines changed

6 files changed

+620
-338
lines changed

‎README.md

Lines changed: 146 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,193 @@
11
# Better Bing Image Downloader
22

3+
A powerful Python tool for downloading images from Bing and Google image search engines.
4+
5+
[![GitHub top language](https://img.shields.io/github/languages/top/KTS-o7/better_bing_image_downloader)](https://github.com/KTS-o7/better_bing_image_downloader)
6+
[![GitHub](https://img.shields.io/github/license/KTS-o7/better-bing-image-downloader)](https://github.com/KTS-o7/better-bing-image-downloader/blob/main/LICENSE)
7+
[![PyPI version](https://badge.fury.io/py/better-bing-image-downloader.svg)](https://pypi.org/project/better-bing-image-downloader/)
8+
[![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FKTS-o7%2Fbetter_bing_image_downloader&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false)](https://hits.seeyoufarm.com)
9+
10+
## Features
11+
12+
- Download images from Bing and Google search engines
13+
- Parallel downloading for significantly faster performance
14+
- Multiple filtering options (image type, color, adult content, etc.)
15+
- Support for both API and browser-based image retrieval
16+
- Command-line interface and Python API
17+
- Multiple browser support (Firefox, Chrome, headless options)
18+
- Proxy support
19+
320
## Table of Contents
421

5-
- [Disclaimer](#disclaimer)
622
- [Installation](#installation)
723
- [Usage](#usage)
24+
- [Python API](#python-api)
25+
- [Command Line Interface](#command-line-interface)
26+
- [Parameters](#parameters)
27+
- [Examples](#examples)
828
- [License](#license)
29+
- [Disclaimer](#disclaimer)
30+
- [Changelog](#changelog)
931
- [Contact](#contact)
1032

11-
### Disclaimer<br />
33+
## Installation
1234

13-
This program lets you download tons of images from Bing.
14-
Please do not download or use any image that violates its copyright terms.
35+
### Using pip
1536

16-
![GitHub top language](https://img.shields.io/github/languages/top/KTS-o7/better_bing_image_downloader)
17-
![GitHub](https://img.shields.io/github/license/KTS-o7/better-bing-image-downloader)
18-
[![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FKTS-o7%2Fbetter_bing_image_downloader&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false)](https://hits.seeyoufarm.com)
37+
```bash
38+
pip install better-bing-image-downloader
39+
```
1940

20-
### Installation <br />
41+
### From source
2142

2243
```bash
23-
git clone https://github.com/KTS-o7better_bing_image_downloader
24-
python -m venv ./env
25-
source env/bin/activate
44+
git clone https://github.com/KTS-o7/better_bing_image_downloader
2645
cd better_bing_image_downloader
46+
python -m venv ./env
47+
source env/bin/activate # On Windows: env\Scripts\activate
48+
pip install -r requirements.txt
2749
pip install .
2850
```
2951

30-
or
52+
## Usage
3153

32-
```bash
33-
pip install better-bing-image-downloader
54+
### Python API
55+
56+
```python
57+
from better_bing_image_downloader import downloader
58+
59+
# Basic usage
60+
downloader("cute puppies", limit=50)
61+
62+
# Advanced usage
63+
downloader(
64+
query="cute puppies",
65+
limit=100,
66+
output_dir="my_images",
67+
adult_filter_off=True,
68+
force_replace=False,
69+
timeout=60,
70+
filter="photo", # Options: "line", "photo", "clipart", "gif", "transparent"
71+
verbose=True,
72+
badsites=["stock.adobe.com", "shutterstock.com"],
73+
name="Puppy",
74+
max_workers=8 # Parallel downloads
75+
)
3476
```
3577

36-
### PyPi <br />
78+
### Command Line Interface
3779

38-
[Package Link](https://pypi.org/project/better-bing-image-downloader/)
80+
The package provides two command-line interfaces:
3981

40-
### Usage <br />
82+
#### 1. Simple CLI (Bing-only)
4183

42-
#### Using as a Package:
84+
```bash
85+
python -m better_bing_image_downloader.download "query" [options]
86+
```
4387

44-
```python
45-
from better_bing_image_downloader import downloader
88+
#### 2. Advanced CLI (Bing and Google)
4689

47-
downloader(query_string, limit=100, output_dir='dataset', adult_filter_off=True,
48-
force_replace=False, timeout=60, filter="", verbose=True, badsites= [], name='Image')
90+
```bash
91+
python -m better_bing_image_downloader.multidownloader "query" [options]
4992
```
5093

51-
`query_string` : String to be searched.<br />
52-
`limit` : (optional, default is 100) Number of images to download.<br />
53-
`output_dir` : (optional, default is 'dataset') Name of output dir.<br />
54-
`adult_filter_off` : (optional, default is True) Enable of disable adult filteration.<br />
55-
`force_replace` : (optional, default is False) Delete folder if present and start a fresh download.<br />
56-
`timeout` : (optional, default is 60) timeout for connection in seconds.<br />
57-
`filter` : (optional, default is "") filter, choose from [line, photo, clipart, gif, transparent]<br />
58-
`verbose` : (optional, default is True) Enable downloaded message.<br />
59-
`bad-sites` : (optional, defualt is empty list) Can limit the query to not access the bad sites.<br/>
60-
`name` : (optional, default is 'Image') Can add a custom name for the images that are downloaded.<br/>
94+
## Parameters
95+
96+
### Python API Parameters
97+
98+
| Parameter | Type | Default | Description |
99+
| ---------------- | ---- | ---------- | ---------------------------------------------------------- |
100+
| query | str | (required) | Search term |
101+
| limit | int | 100 | Maximum number of images to download |
102+
| output_dir | str | 'dataset' | Directory to save images |
103+
| adult_filter_off | bool | True | Disable adult content filter |
104+
| force_replace | bool | False | Replace existing files and directories |
105+
| timeout | int | 60 | Connection timeout in seconds |
106+
| filter | str | "" | Image type filter (line, photo, clipart, gif, transparent) |
107+
| verbose | bool | True | Display detailed output |
108+
| badsites | list | [] | List of sites to exclude from results |
109+
| name | str | 'Image' | Base name for downloaded images |
110+
| max_workers | int | 4 | Number of parallel download threads |
111+
112+
### Command Line Arguments (multidownloader.py)
113+
114+
| Argument | Short | Default | Description |
115+
| -------------- | ----- | ------------------- | ---------------------------------------------------- |
116+
| --engine | -e | "Bing" | Search engine ("Google" or "Bing") |
117+
| --driver | -d | "firefox_headless" | Browser driver to use |
118+
| --max-number | -n | 100 | Maximum number of images to download |
119+
| --num-threads | -j | 50 | Number of concurrent download threads |
120+
| --timeout | -t | 10 | Download timeout in seconds |
121+
| --output | -o | "./download_images" | Output directory |
122+
| --safe-mode | -S | False | Enable safe search mode |
123+
| --face-only | -F | False | Only search for faces |
124+
| --proxy_http | -ph | None | HTTP proxy address (e.g., 192.168.0.2:8080) |
125+
| --proxy_socks5 | -ps | None | SOCKS5 proxy address (e.g., 192.168.0.2:1080) |
126+
| --type | -ty | None | Image type filter (clipart, linedrawing, photograph) |
127+
| --color | -cl | None | Color filter for images |
128+
129+
## Examples
130+
131+
### Basic Search
61132

62-
#### Using as a Command Line Tool:
133+
```python
134+
from better_bing_image_downloader import downloader
63135

64-
```bash
65-
git clone https://github.com/KTS-o7/better_bing_image_downloader.git
66-
cd better_bing_image_downloader
67-
python -m venv ./env
68-
source env/bin/activate
69-
pip install -r requirements.txt
70-
cd better_bing_image_downloader
71-
# This is an example query
72-
python multidownloader.py "cool doggos" --engine "Bing" --max-number 50 --num-threads 5 --driver "firefox_headless"
136+
# Download 100 cat images to ./dataset/cats
137+
downloader("cats", limit=100)
73138
```
74139

75-
#### Command Line Arguments:
140+
### Advanced Search with Filters
76141

77-
```bash
78-
multidownloader.py "keywords" [-h] [--engine {Google,Bing}] [--driver {chrome_headless,chrome,api,firefox,firefox_headless}] [--max-number MAX_NUMBER] [--num-threads NUM_THREADS] [--timeout TIMEOUT] [--output OUTPUT] [--safe-mode] [--face-only] [--proxy_http PROXY_HTTP] [--proxy_socks5 PROXY_SOCKS5] [--type {clipart,linedrawing,photograph}] [--color COLOR]
142+
```python
143+
# Download 50 transparent clipart images with parallel processing
144+
downloader(
145+
query="logo design",
146+
limit=50,
147+
filter="transparent",
148+
max_workers=8,
149+
output_dir="logos"
150+
)
79151
```
80152

81-
- `"keywords"`: Keywords to search. ("in quotes")
82-
- `-h, --help`: Show the help message and exit
83-
- `--engine, -e`: Image search engine. Choices are "Google" and "Bing". Default is "Bing".
84-
- `--driver, -d`: Image search engine. Choices are "chrome_headless", "chrome", "api", "firefox", "firefox_headless". Default is "firefox_headless".
85-
- `--max-number, -n`: Max number of images download for the keywords. Default is 100.
86-
- `--num-threads, -j`: Number of threads to concurrently download images. Default is 50.
87-
- `--timeout, -t`: Seconds to timeout when download an image. Default is 10.
88-
- `--output, -o`: Output directory to save downloaded images. Default is "./download_images".
89-
- `--safe-mode, -S`: Turn on safe search mode. (Only effective in Google)
90-
- `--face-only, -`F: Only search for faces.
91-
- `--proxy_http, -ph`: Set http proxy (e.g. 192.168.0.2:8080)
92-
- `--proxy_socks5, -ps`: Set socks5 proxy (e.g. 192.168.0.2:1080)
93-
- -`-type, -ty`: What kinds of images to download. Choices are "clipart", "linedrawing", "photograph".
94-
- `--color, -cl`: Specify the color of desired images.
153+
### Command Line Usage
95154

96155
```bash
97-
# Example usage
98-
python multidownloader.py "Cool Doggos" --engine "Google" --driver "chrome_headless" --max-number 50 --num-threads 10 --timeout 60 --output "./doggo_images" --safe-mode --proxy_http "192.168.0.2:8080" --type "photograph" --color "blue"
156+
# Download 50 landscape photographs using Google
157+
python -m better_bing_image_downloader.multidownloader "mountain landscape" --engine "Google" --max-number 50 --type "photograph"
158+
159+
# Download 100 cat images using Bing with Firefox headless
160+
python -m better_bing_image_downloader.multidownloader "cats" --engine "Bing" --driver "firefox_headless" --max-number 100
99161
```
100162

101-
---
163+
## Disclaimer
102164

103-
## Star History
165+
This program lets you download images from search engines. Please do not download or use any image that violates its copyright terms. The developers of this tool are not responsible for any misuse.
104166

105-
[![Star History Chart](https://api.star-history.com/svg?repos=KTS-o7/better-bing-image-downloader&type=Date)](https://www.star-history.com/#KTS-o7/better-bing-image-downloader&Date)
167+
## Changelog
168+
169+
### 2.0.0
170+
171+
- Added parallel downloading for significantly faster image retrieval
172+
- Improved error handling and recovery
173+
- Better memory management and code organization
174+
- Fixed progress bar display issues
175+
- Added max_workers parameter to control parallel downloads
176+
- Added new requirements
106177

107-
### License
178+
### 1.1.3
108179

109-
This project is licensed under the terms of the MIT license.
180+
- Fixed issue with invalid image types
181+
- Replaced imghdr with filetype for more reliable image type detection
110182

111-
### Contact
183+
## License
112184

113-
If you have any questions or feedback, please contact us at [email](mailto:shentharkrishnatejaswi@gmail.com).
185+
This project is licensed under the MIT License - see the LICENSE file for details.
114186

115-
### Changelog
187+
## Contact
116188

117-
- 1.1.3:
118-
- Fixed issue with invalid image types. Deleted imghdr and used filetype to check image types.
189+
If you have any questions or feedback, please contact the developer at [shentharkrishnatejaswi@gmail.com](mailto:shentharkrishnatejaswi@gmail.com).
190+
191+
## Star History
192+
193+
[![Star History Chart](https://api.star-history.com/svg?repos=KTS-o7/better-bing-image-downloader&type=Date)](https://www.star-history.com/#KTS-o7/better-bing-image-downloader&Date)

0 commit comments

Comments
 (0)