Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs/style #59

Merged
merged 5 commits into from
Jun 23, 2021
Merged

Docs/style #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6fed4bd
add smiley
aniketmaurya Jun 23, 2021
fe00a8e
update
aniketmaurya Jun 23, 2021
bff5f05
precommit
aniketmaurya Jun 23, 2021
0211c28
update
aniketmaurya Jun 23, 2021
e602e30
precommit
aniketmaurya Jun 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 64 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
# chitra


[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=aniketmaurya_chitra&metric=alert_status)](https://sonarcloud.io/dashboard?id=aniketmaurya_chitra)
[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=aniketmaurya_chitra&metric=ncloc)](https://sonarcloud.io/dashboard?id=aniketmaurya_chitra)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=aniketmaurya_chitra&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=aniketmaurya_chitra)
Expand All @@ -11,27 +10,29 @@
[![Documentation Status](https://readthedocs.org/projects/chitra/badge/?version=latest)](https://chitra.readthedocs.io/en/latest/?badge=latest)
[![Discord](https://img.shields.io/discord/848469007443165184?style=flat)](https://discord.gg/TdnAfDw3kB)


## What is chitra?

**chitra** (**चित्र**) is a Deep Learning Computer Vision library for easy data loading, model building and model visualization with GradCAM/GradCAM++ and Framework agnostic Model Serving.
**chitra** (**चित्र**) is a Deep Learning Computer Vision library for easy data loading, data visualization, model building and model
analysis with GradCAM/GradCAM++ and Framework agnostic Model Serving.

Highlights:
- Faster data loading without any boilerplate.
- Framework Agnostic Model Serving.
- Progressive resizing of images.
- Rapid experiments with different models using `chitra.trainer` module.
- Train models with cyclic learning rate.
- Model interpretation using GradCAM/GradCAM++ with no extra code.
### Highlights:

> If you have more use case please [**raise an issue/PR**](https://github.com/aniketmaurya/chitra/issues/new/choose) with the feature you want.
- [New] Data Visualization, Bounding Box Visualization 🐶
- [New] Framework Agnostic Model Serving ✨🌟
- Faster data loading without any boilerplate 🤺
- Progressive resizing of images
- Rapid experiments with different models using `chitra.trainer` module 🚀
- Model interpretation using GradCAM/GradCAM++ with no extra code 🔥

> If you have more use case please [**raise an issue/PR**](https://github.com/aniketmaurya/chitra/issues/new/choose) with the feature you want.
> If you want to contribute, feel free to raise a PR. It doesn't need to be perfect.
> We will help you get there.

## Installation

[![Downloads](https://pepy.tech/badge/chitra)](https://pepy.tech/project/chitra)
[![Downloads](https://pepy.tech/badge/chitra/month)](https://pepy.tech/project/chitra)
![GitHub](https://img.shields.io/github/license/aniketmaurya/chitra?style=flat)
![GitHub License](https://img.shields.io/github/license/aniketmaurya/chitra?style=flat)

### Using pip (recommended)

Expand All @@ -46,6 +47,7 @@ pip install -e .
```

### From GitHub

```
pip install git+https://github.com/aniketmaurya/chitra@master
```
Expand All @@ -54,7 +56,9 @@ pip install git+https://github.com/aniketmaurya/chitra@master

### Loading data for image classification

Chitra `dataloader` and `datagenerator` modules for loading data. `dataloader` is a minimal dataloader that returns `tf.data.Dataset` object. `datagenerator` provides flexibility to users on how they want to load and manipulate the data.
Chitra `dataloader` and `datagenerator` modules for loading data. `dataloader` is a minimal dataloader that
returns `tf.data.Dataset` object. `datagenerator` provides flexibility to users on how they want to load and manipulate
the data.

```python
import numpy as np
Expand All @@ -65,22 +69,24 @@ import matplotlib.pyplot as plt

clf_dl = Clf()
data = clf_dl.from_folder(cat_dog_path, target_shape=(224, 224))
clf_dl.show_batch(8, figsize=(8,8))
clf_dl.show_batch(8, figsize=(8, 8))
```

![Show Batch](https://raw.githubusercontent.com/aniketmaurya/chitra/master/docs/assets/images/output_3_1.png)


## Image datagenerator

Dataset class provides the flexibility to load image dataset by updating components of the class.

Components of Dataset class are:

- image file generator
- resizer
- label generator
- image loader

These components can be updated with custom function by the user according to their dataset structure. For example the Tiny Imagenet dataset is organized as-
These components can be updated with custom function by the user according to their dataset structure. For example the
Tiny Imagenet dataset is organized as-

```
train_folder/
Expand All @@ -95,11 +101,11 @@ train_folder/
......imageN.jpg
```

The inbuilt file generator search for images on the `folder1`, now we can just update the `image file generator` and rest of the functionality will remain same.
The inbuilt file generator search for images on the `folder1`, now we can just update the `image file generator` and
rest of the functionality will remain same.

**Dataset also support progressive resizing of images.**


### Updating component

```python
Expand All @@ -109,26 +115,30 @@ ds = Dataset(data_path)
# it will load the folders and NOT images
ds.filenames[:3]
```

<details><summary>Output</summary>

No item present in the image size list

['/Users/aniket/Pictures/data/tiny-imagenet-200/train/n02795169/n02795169_boxes.txt',
'/Users/aniket/Pictures/data/tiny-imagenet-200/train/n02795169/images',
'/Users/aniket/Pictures/data/tiny-imagenet-200/train/n02769748/images']
</details>

</details>

```python
def load_files(path):
return glob(f'{path}/*/images/*')


def get_label(path):
return path.split('/')[-3]


ds.update_component('get_filenames', load_files)
ds.filenames[:3]
```

<details><summary>Output</summary>

get_filenames updated with <function load_files at 0x7fad6916d0e0>
Expand All @@ -140,7 +150,6 @@ ds.filenames[:3]

</details>


### Progressive resizing

> It is the technique to sequentially resize all the images while training the CNNs on smaller to bigger image sizes. Progressive Resizing is described briefly in his terrific fastai course, “Practical Deep Learning for Coders”. A great way to use this technique is to train a model with smaller image size say 64x64, then use the weights of this model to train another model on images of size 128x128 and so on. Each larger-scale model incorporates the previous smaller-scale model layers and weights in its architecture.
Expand Down Expand Up @@ -168,6 +177,7 @@ for img, label in ds.generator():
print('third call to generator:', img.shape)
break
```

<details><summary>Output</summary>

get_filenames updated with <function load_files at 0x7fad6916d0e0>
Expand All @@ -176,11 +186,13 @@ for img, label in ds.generator():
first call to generator: (28, 28, 3)
seconds call to generator: (32, 32, 3)
third call to generator: (64, 64, 3)
</details>

</details>

### tf.data support
Creating a `tf.data` dataloader was never as easy as this one liner. It converts the Python generator into `tf.data.Dataset` for a faster data loading, prefetching, caching and everything provided by tf.data.

Creating a `tf.data` dataloader was never as easy as this one liner. It converts the Python generator
into `tf.data.Dataset` for a faster data loading, prefetching, caching and everything provided by tf.data.

```python
image_sz_list = [(28, 28), (32, 32), (64, 64)]
Expand All @@ -200,43 +212,47 @@ for e in dl.take(1):
for e in dl.take(1):
print(e[0].shape)
```

<details><summary>Output</summary>

get_filenames updated with <function load_files at 0x7fad6916d0e0>
get_label updated with <detn get_label at 0x7fad6916d8c0>
(28, 28, 3)
(32, 32, 3)
(64, 64, 3)

</details>

## Trainer
The Trainer class inherits from `tf.keras.Model`, it contains everything that is required for training.
It exposes trainer.cyclic_fit method which trains the model using Cyclic Learning rate discovered by [Leslie Smith](https://arxiv.org/abs/1506.01186).

The Trainer class inherits from `tf.keras.Model`, it contains everything that is required for training. It exposes
trainer.cyclic_fit method which trains the model using Cyclic Learning rate discovered
by [Leslie Smith](https://arxiv.org/abs/1506.01186).

```python
from chitra.trainer import Trainer, create_cnn
from chitra.datagenerator import Dataset


ds = Dataset(cat_dog_path, image_size=(224,224))
ds = Dataset(cat_dog_path, image_size=(224, 224))
model = create_cnn('mobilenetv2', num_classes=2, name='Cat_Dog_Model')
trainer = Trainer(ds, model)
# trainer.summary()
```

```python
trainer.compile2(batch_size=8,
optimizer=tf.keras.optimizers.SGD(1e-3, momentum=0.9, nesterov=True),
lr_range=(1e-6, 1e-3),
loss='binary_crossentropy',
metrics=['binary_accuracy'])

optimizer=tf.keras.optimizers.SGD(1e-3, momentum=0.9, nesterov=True),
lr_range=(1e-6, 1e-3),
loss='binary_crossentropy',
metrics=['binary_accuracy'])

trainer.cyclic_fit(epochs=5,
batch_size=8,
lr_range=(0.00001, 0.0001),
)
batch_size=8,
lr_range=(0.00001, 0.0001),
)
```

<details><summary>Training Loop...</summary>
cyclic learning rate already set!

Expand All @@ -256,18 +272,21 @@ trainer.cyclic_fit(epochs=5,
1/1 [==============================] - 0s 982us/step - loss: 1.9062 - binary_accuracy: 0.8750

<tensorflow.python.keras.callbacks.History at 0x7f8b1c3f2410>
</details>

</details>

## Model Visualization
It is important to understand what is going inside the model. Techniques like GradCam and Saliency Maps can visualize what the Network is learning. `trainer` module has InterpretModel class which creates GradCam and GradCam++ visualization with almost no additional code.

It is important to understand what is going inside the model. Techniques like GradCam and Saliency Maps can visualize
what the Network is learning. `trainer` module has InterpretModel class which creates GradCam and GradCam++
visualization with almost no additional code.

```python
from chitra.trainer import InterpretModel

trainer = Trainer(ds, create_cnn('mobilenetv2', num_classes=1000, keras_applications=False))
model_interpret = InterpretModel(True, trainer)


image = ds[1][0].numpy().astype('uint8')
image = Image.fromarray(image)
model_interpret(image)
Expand All @@ -280,7 +299,6 @@ print(IMAGENET_LABELS[285])

![png](https://raw.githubusercontent.com/aniketmaurya/chitra/master/docs/assets/images/output_22_1.png)


## Data Visualization

### Image annotation
Expand All @@ -291,7 +309,7 @@ Bounding Box creation is based on top of `imgaug` library.
from chitra.image import Chitra


bbox = [ 70, 25, 190, 210]
bbox = [70, 25, 190, 210]
label = 'Dog'

image = Chitra(image_path, bboxes=bbox, labels=label)
Expand All @@ -300,7 +318,6 @@ plt.imshow(image.draw_boxes())

![png](https://raw.githubusercontent.com/aniketmaurya/chitra/master/docs/assets/images/preview-bounding-box.png)


## Utils

Limit GPU memory or enable dynamic GPU memory growth for Tensorflow.
Expand All @@ -309,24 +326,25 @@ Limit GPU memory or enable dynamic GPU memory growth for Tensorflow.
from chitra.utils import limit_gpu, gpu_dynamic_mem_growth

# limit the amount of GPU required for your training
limit_gpu(gpu_id=0, memory_limit=1024*2)
limit_gpu(gpu_id=0, memory_limit=1024 * 2)
```
No GPU:0 found in your system!

No GPU:0 found in your system!

```python
gpu_dynamic_mem_growth()
```

No GPU found on the machine!


## Contributing

Contributions of any kind are welcome. Please check the [**Contributing Guidelines**](https://github.com/aniketmaurya/chitra/blob/master/CONTRIBUTING.md) before contributing.
Contributions of any kind are welcome. Please check the [**Contributing
Guidelines**](https://github.com/aniketmaurya/chitra/blob/master/CONTRIBUTING.md) before contributing.

## Code Of Conduct
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

Read full [**Contributor Covenant Code of Conduct**](https://github.com/aniketmaurya/chitra/blob/master/CODE_OF_CONDUCT.md)
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Read full [**Contributor Covenant Code of
Conduct**](https://github.com/aniketmaurya/chitra/blob/master/CODE_OF_CONDUCT.md)
Loading