Skip to content

Commit 8e5fca6

Browse files
acl21acl21
committed
changed documentation accordingly
1 parent 51eb7b5 commit 8e5fca6

10 files changed

+150
-274
lines changed

‎README.md

+5-194
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
[![PyPI version](https://badge.fury.io/py/image-bbox-slicer.svg)](https://badge.fury.io/py/image-bbox-slicer) [![](https://img.shields.io/github/license/mashape/apistatus.svg)](LICENSE)
2-
# image_bbox_slicer
2+
# Image and Bounding Box Slicer-Resizer (image_bbox_slicer)
33

44
This easy-to-use library is a data transformer sometimes useful in Object Detection tasks. It splits images and their bounding box annotations into tiles, both into specific sizes and into any arbitrary number of equal parts. It can also resize them, both by specific sizes and by a resizing/scaling factor. Of course it goes without saying that just image slicing could in Segmentation tasks (where input and labels both are images). Read the docs [here](https://image-bbox-slicer.readthedocs.io/en/latest/).
55

66
<div align="center">
7-
<img src="imgs/ibs_demo.jpg" alt="Partial Labels Example" />
7+
<img src="imgs/ibs_demo2.jpg" alt="Partial Labels Example" />
88
</div>
99

1010
Currently, this library only supports bounding box annotations in [PASCAL VOC](http://host.robots.ox.ac.uk/pascal/VOC/) format. And as of now, there is **no command line execution support**. Please raise an issue if needed.
@@ -14,203 +14,14 @@ Currently, this library only supports bounding box annotations in [PASCAL VOC](h
1414
$ pip install image_bbox_slicer
1515
```
1616

17-
This tool was tested on both Windows and Linx. Works with Python 3.4 and higher versions and requires:
17+
This tool was tested on both Windows and Linx. Works well with Python 3.8.
1818
```python
1919
Pillow
2020
numpy
2121
pascal-voc-writer
2222
matplotlib
2323
```
2424

25-
## Usage - A Quick Demo
26-
_Note: This usage demo can be found in `demo.ipynb` in the repo._
25+
## Slicing Demo: [Docs](https://image-bbox-slicer.readthedocs.io/en/latest/slicing-demo.html) and [Notebook](https://github.com/acl21/image_bbox_slicer/blob/master/Slicing_Demo.ipynb)
2726

28-
```python
29-
import image_bbox_slicer as ibs
30-
```
31-
32-
### Create And Configure `Slicer` Object
33-
34-
#### Setting Paths To Source And Destination Directories.
35-
You must configure paths to source and destination directories like the following.
36-
37-
```python
38-
im_src = './src/images'
39-
an_src = './src/annotations'
40-
im_dst = './dst/images'
41-
an_dst = './dst/annotations'
42-
43-
slicer = ibs.Slicer()
44-
slicer.config_dirs(img_src=im_src, ann_src=an_src,
45-
img_dst=im_dst, ann_dst=an_dst)
46-
```
47-
48-
#### Dealing With Partial Labels
49-
<div align="center">
50-
<img src="imgs/partial_labels.jpg" alt="Partial Labels Example" style="width: 850px;" />
51-
</div>
52-
53-
The above images show the difference in slicing with and without partial labels. In the image on the left, all the box annotations masked in <span style="color:green">**green**</span> are called Partial Labels.
54-
55-
Configure your slicer to either ignore or consider them by setting `Slicer` object's `keep_partial_labels` instance variable to `True` or `False` respectively. By default it is set to `False`.
56-
57-
58-
```python
59-
slicer.keep_partial_labels = True
60-
```
61-
62-
#### Dealing With Empty Tiles
63-
<img src="imgs/empty_tiles.png" alt="Empty Tiles Example" style="width: 850px;"/>
64-
65-
An empty tile is a tile with no "labels" in it. The definition of "labels" here is tightly coupled with the user's preference of partial labels. If you choose to keep the partial labels (i.e. `keep_partial_labels = True`), a tile with a partial label is not treated as empty. If you choose to not keep the partial labels (i.e. `keep_partial_labels = False`), a tile with one or more partial labels is considered empty.
66-
67-
Configure your slicer to either ignore or consider empty tiles by setting `Slicer` object's `ignore_empty_tiles` instance variable to `True` or `False` respectively. By default it is set to `True`.
68-
69-
70-
```python
71-
slicer.ignore_empty_tiles = False
72-
```
73-
74-
#### Before-After Mapping
75-
76-
You can choose to store the mapping between file names of the images before and after slicing by setting the `Slicer` object's `save_before_after_map` instance variable to `True`. By default it is set to `False`.
77-
78-
Typically, `mapper.csv` looks like the following:
79-
```
80-
| old_name | new_names |
81-
|------------|---------------------------------|
82-
| 2102 | 000001, 000002, 000003, 000004 |
83-
| 3931 | 000005, 000005, 000007, 000008 |
84-
| test_image | 000009, 000010, 000011, 000012 |
85-
| ... | ... |
86-
```
87-
88-
89-
```python
90-
slicer.save_before_after_map = True
91-
```
92-
93-
### Slicing
94-
95-
#### Images and Bounding Box Annotations Simultaneously
96-
97-
#### By Number Of Tiles
98-
99-
100-
```python
101-
slicer.slice_by_number(number_tiles=4)
102-
slicer.visualize_sliced_random()
103-
```
104-
105-
<div align="center">
106-
<img src="imgs/output_10_1.png" alt="Output1" style="width: 200px;" />
107-
108-
<img src="imgs/output_10_2.png" alt="Output2" style="width: 200px;" />
109-
</div>
110-
111-
112-
#### By Specific Size
113-
114-
```python
115-
slicer.slice_by_size(tile_size=(418,279), tile_overlap=0)
116-
slicer.visualize_sliced_random()
117-
```
118-
119-
120-
<div align="center">
121-
<img src="imgs/output_12_1.png" alt="Output3" style="width: 200px;" />
122-
123-
<img src="imgs/output_12_2.png" alt="Output4" style="width: 200px;" />
124-
</div>
125-
126-
*Note: `visualize_sliced_random()` randomly picks a recently sliced image from the directory for plotting.*
127-
128-
### Other Slicing Functions
129-
130-
#### By Number Of Tiles
131-
```python
132-
slicer.slice_images_by_number(number_tiles=4)
133-
```
134-
135-
#### By Specific Size
136-
```python
137-
slicer.slice_images_by_size(tile_size=(418,279), tile_overlap=0)
138-
```
139-
140-
#### Slicing Only Bounding Box Annotations
141-
#### By Number Of Tiles
142-
```python
143-
slicer.slice_bboxes_by_number(number_tiles=4)
144-
```
145-
146-
#### By Specifc Size
147-
```python
148-
slicer.slice_bboxes_by_size(tile_size=(418,279), tile_overlap=0)
149-
```
150-
151-
### Resizing
152-
![png](imgs/resize_demo.png)
153-
154-
#### Images and Bounding Box Annotations Simultaneously
155-
#### By Specific Size
156-
157-
158-
```python
159-
slicer.resize_by_size(new_size=(500,200))
160-
slicer.visualize_resized_random()
161-
```
162-
163-
164-
![png](imgs/output_18_0.png)
165-
166-
167-
![png](imgs/output_18_1.png)
168-
169-
170-
#### By A Resize Factor
171-
172-
173-
```python
174-
slicer.resize_by_factor(resize_factor=0.05)
175-
slicer.visualize_resized_random()
176-
```
177-
178-
![png](imgs/output_20_0.png)
179-
180-
181-
![png](imgs/output_20_1.png)
182-
183-
_Note:_
184-
185-
*`visualize_resized_random()` randomly picks a recently resized image from the destination directory for plotting.*
186-
187-
188-
### Other Resizing Functions
189-
190-
#### Resizing Separately
191-
192-
#### Only Images
193-
194-
* #### By Specific Size
195-
196-
```python
197-
slicer.resize_images_by_size(new_size=(500,200))
198-
```
199-
200-
* #### By Resize Factor
201-
202-
```python
203-
slicer.resize_images_by_factor(resize_factor=0.05)
204-
```
205-
206-
#### Only Bounding Box Annotations
207-
208-
* #### By Specific Size
209-
```python
210-
slicer.resize_bboxes_by_size(new_size=(500,200))
211-
```
212-
213-
* #### By Resize Factor
214-
```python
215-
slicer.resize_bboxes_by_factor(resize_factor=0.05)
216-
```
27+
## Resizing Demo: [Docs](https://image-bbox-slicer.readthedocs.io/en/latest/resizing-demo.html) and [Notebook](https://github.com/acl21/image_bbox_slicer/blob/master/Resizing_Demo.ipynb)

‎docs/img/ibs_demo.jpg

-56.1 KB
Loading

‎docs/index.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
# Image and Box Annotation Slicer
1+
# Image and Box Annotation Slicer-Resizer
22

33
This easy-to-use library is a data transformer sometimes useful in Object Detection tasks. It splits images and its bounding box annotations into tiles, both into specific sizes and into any arbitrary number of equal parts. It can also resize them, both by specific sizes and by a resizing/scaling factor.
44

55
<div align="center">
6-
<img src="img/ibs_demo.jpg" alt="Overview" />
6+
<img src="img/ibs_demo.jpg" alt="Overview" width="650" height="1200"/>
77
</div>
88
<br>
99
Currently, this library only supports bounding box annotations in [PASCAL VOC](http://host.robots.ox.ac.uk/pascal/VOC/) format. And as of now, there is **no command line execution support**.

‎docs/resizing-demo.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
## Create And Configure `Resizer` Object
2+
_Note: This usage demo can be found in `Resizing_Demo.ipynb` in the project's [repo](https://github.com/acl21/image_bbox_slicer)._
3+
4+
### Setting Paths To Source And Destination Directories
5+
You must configure paths to source and destination directories like the following.
6+
By default it takes the current working directory as the source folder for both images and annotations and also creates new folders:
7+
8+
* `/resized_images` and
9+
* `/resized_annotation`
10+
11+
in the current working directory.
12+
13+
```python
14+
import image_bbox_slicer as ibs
15+
16+
im_src = './src/images'
17+
an_src = './src/annotations'
18+
im_dst = './dst/images'
19+
an_dst = './dst/annotations'
20+
21+
resizer = ibs.Resizer()
22+
resizer.config_dirs(img_src=im_src, ann_src=an_src,
23+
img_dst=im_dst, ann_dst=an_dst)
24+
```
25+
26+
### Images and Bounding Box Annotations Simultaneously
27+
28+
** By Specific Size **
29+
30+
31+
```python
32+
resizer.resize_by_size(new_size=(500,200))
33+
resizer.visualize_resized_random()
34+
```
35+
36+
37+
![png](img/output_18_0.png)
38+
39+
40+
![png](img/output_18_1.png)
41+
42+
43+
** By A Resize Factor **
44+
45+
46+
```python
47+
resizer.resize_by_factor(resize_factor=0.05)
48+
resizer.visualize_resized_random()
49+
```
50+
51+
![png](img/output_20_0.png)
52+
53+
54+
![png](img/output_20_1.png)
55+
56+
_Note:_
57+
*`visualize_resized_random()` randomly picks a recently resized image from the destination directory for plotting.*
58+
59+

‎docs/quick-demo.md ‎docs/slicing-demo.md

+12-47
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
## Create And Configure `Slicer` Object
2-
_Note: This usage demo can be found in `demo.ipynb` in the project's [repo](https://github.com/akshaychandra21/image_bbox_slicer)._
2+
_Note: This usage demo can be found in `Slicing_Demo.ipynb` in the project's [repo](https://github.com/acl21/image_bbox_slicer)._
33

4-
Setting Paths To Source And Destination Directories
5-
You must configure paths to source and destination directories like the following.
4+
### Setting Paths To Source And Destination Directories
5+
You must configure paths to source and destination directories like the following. By default it takes the current working directory as the source folder for both images and annotations and also creates new folders:
6+
7+
* `/sliced_images` and
8+
* `/sliced_annotation`
9+
10+
in the current working directory.
611

712
```python
813
import image_bbox_slicer as ibs
@@ -17,7 +22,7 @@ slicer.config_dirs(img_src=im_src, ann_src=an_src,
1722
img_dst=im_dst, ann_dst=an_dst)
1823
```
1924

20-
## Partial Labels
25+
### Partial Labels
2126

2227
![partial](img/partial_labels.jpg)
2328

@@ -29,7 +34,7 @@ Configure your slicer to either ignore or consider them by setting `Slicer` obje
2934
slicer.keep_partial_labels = True
3035
```
3136

32-
## Empty Tiles
37+
### Empty Tiles
3338
![empty](img/empty_tiles.png)
3439

3540
An empty tile is a tile with no "labels" in it. The definition of "labels" here is tightly coupled with the user's preference of partial labels. If you choose to keep the partial labels (i.e. `keep_partial_labels = True`), a tile with a partial label is not treated as empty. If you choose to not keep the partial labels (i.e. `keep_partial_labels = False`), a tile with one or more partial labels is considered empty.
@@ -40,7 +45,7 @@ Configure your slicer to either ignore or consider empty tiles by setting `Slice
4045
slicer.ignore_empty_tiles = False
4146
```
4247

43-
## Before-After Mapping
48+
### Before-After Mapping
4449

4550
You can choose to store the mapping between file names of the images before and after slicing by setting the `Slicer` object's `save_before_after_map` instance variable to `True`. By default it is set to `False`.
4651

@@ -59,9 +64,7 @@ Typically, `mapper.csv` looks like the following:
5964
slicer.save_before_after_map = True
6065
```
6166

62-
## Slicing
63-
64-
Slicing both images and box annotations at the same time.
67+
### Slicing both images and box annotations at the same time.
6568

6669
** By Number Of Tiles **
6770

@@ -86,41 +89,3 @@ slicer.visualize_random()
8689
![output-4](img/output_12_2.png)
8790

8891
*Note: `visualize_sliced_random()` randomly picks a recently sliced image from the directory for plotting.*
89-
90-
## Resizing
91-
![png](img/resize_demo.png)
92-
93-
Images and Bounding Box Annotations Simultaneously
94-
95-
** By Specific Size **
96-
97-
98-
```python
99-
slicer.resize_by_size(new_size=(500,200))
100-
slicer.visualize_resized_random()
101-
```
102-
103-
104-
![png](img/output_18_0.png)
105-
106-
107-
![png](img/output_18_1.png)
108-
109-
110-
** By A Resize Factor **
111-
112-
113-
```python
114-
slicer.resize_by_factor(resize_factor=0.05)
115-
slicer.visualize_resized_random()
116-
```
117-
118-
![png](img/output_20_0.png)
119-
120-
121-
![png](img/output_20_1.png)
122-
123-
_Note:_
124-
*`visualize_resized_random()` randomly picks a recently resized image from the destination directory for plotting.*
125-
126-

0 commit comments

Comments
 (0)