last infos about working with parts

README.md

@@ -55,11 +55,15 @@ print(parts)
 #        [ 10,   0,   0,   0]])
 
 ```
+### Visible Parts
 
 In order to filter by only visible parts use the [`utils.visible_part_locs`](nabirds/dataset/utils.py#L28) function. It returns the indices and the x-y positions of the visible parts:
 
 ```python
-idxs, xy = visible_part_locs(parts)
+from nabirds import utils
+
+idxs, xy = utils.visible_part_locs(parts)
+
 print(idxs)
 # array([0, 1, 2, 4, 5, 6, 8])
 print(xy)
@@ -70,4 +74,83 @@ x, y = xy
 plt.imshow(im)
 plt.scatter(x,y, marker="x", c=idxs)
 plt.show()
-```
+```
+
+### Uniform Parts
+In case you don't want to use the ground truth parts, you can generate parts uniformly distributed over the image. Here you need to pass the image as well as the ratio, which tells how many parts will be extracted (ratio of `1/5` extracts 5 by 5 parts, resulting in 25 parts). In case of uniform parts all of them are visible.
+
+
+```python
+from nabirds import utils
+
+parts = utils.uniform_parts(im, ratio=1/3)
+idxs, xy = utils.visible_part_locs(parts)
+
+print(idxs)
+# array([0, 1, 2, 3, 4, 5, 6, 7, 8])
+print(xy)
+# array([[140, 420, 700, 140, 420, 700, 140, 420, 700],
+#        [166, 166, 166, 499, 499, 499, 832, 832, 832]])
+
+x, y = xy
+plt.imshow(im)
+plt.scatter(x,y, marker="x", c=idxs)
+plt.show()
+```
+
+### Crop Extraction
+From the locations we can also extract some crops. Same as in [`utils.uniform_parts`](nabirds/dataset/utils.py#L9) you have to give a ratio with which the crops around the locations are created:
+
+```python
+from nabirds import utils
+
+part_crops = utils.visible_crops(im, parts, ratio=0.2)
+
+fig = plt.figure(figsize=(16,9))
+n_crops = part_crops.shape[0]
+rows = int(np.ceil(np.sqrt(n_crops)))
+cols = int(np.ceil(n_crops / rows))
+
+for j, crop in enumerate(part_crops, 1):
+    ax = fig.add_subplot(rows, cols, j)
+    ax.imshow(crop)
+    ax.axis("off")
+
+plt.show()
+```
+
+
+### Random Crops
+In some cases randomly selected crops are desired. Here you can use the [`utils.random_select`](nabirds/dataset/utils.py#L68) function. As optional argument you can also pass a `rnd` argument, that can be an integer (indicating a random seed) or a `numpy.random.RandomState` instance. Additionally, you can also determine the number of crops that will be selected (default is to select random number of crops).
+
+```python
+from nabirds import utils
+
+rnd_idxs, rnd_xy, rnd_part_crops = utils.random_select(idxs, xy, part_crops)
+
+fig = plt.figure(figsize=(16,9))
+
+n_crops = part_crops.shape[0]
+rows = int(np.ceil(np.sqrt(n_crops)))
+cols = int(np.ceil(n_crops / rows))
+
+for j, crop in zip(rnd_idxs, rnd_part_crops):
+    ax = fig.add_subplot(rows, cols, j + 1)
+    ax.imshow(crop)
+    ax.axis("off")
+
+plt.show()
+```
+
+
+### Revealing of the Parts
+In order to create a single image, that consist of the given parts on their correct location use [`utils.reveal_parts`](nabirds/dataset/utils.py#L57) function. It requires again besides the original image and the locations the ratio with which the parts around the locations should be revealed:
+
+```python
+
+plt.imshow(reveal_parts(im, xy, ratio=0.2))
+plt.show()
+
+plt.imshow(reveal_parts(im, rnd_xy, ratio=0.2))
+plt.show()
+```