Skip to content

Commit 2020cec

Browse files
committed
Added quick start to README
1 parent 4462557 commit 2020cec

File tree

1 file changed

+71
-6
lines changed

1 file changed

+71
-6
lines changed

README.md

Lines changed: 71 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,18 +20,83 @@ To install the latest release of AgML, run the following command:
2020
pip install agml
2121
```
2222

23-
## Getting Started
23+
## Quick Start
2424

25-
### Using Public Agricultural Data
25+
AgML is designed for easy usage of agricultural data in a variety of formats. You can start off by using the `AgMLDataLoader` to
26+
download and load a dataset into a container:
27+
28+
```python
29+
import agml
30+
31+
loader = agml.data.AgMLDataLoader('apple_flower_segmentation')
32+
```
33+
34+
You can then use the in-built processing methods to get the loader ready for your training and evaluation pipelines. This includes, but
35+
is not limited to, batching data, shuffling data, splitting data into training, validation, and test sets, and applying transforms.
36+
37+
```python
38+
import albumentations as A
39+
40+
# Batch the dataset into collections of 8 pieces of data:
41+
loader.batch(8)
42+
43+
# Shuffle the data:
44+
loader.shuffle()
45+
46+
# Apply transforms to the input images and output annotation masks:
47+
loader.mask_to_channel_basis()
48+
loader.transform(
49+
transform = A.RandomContrast(),
50+
dual_transform = A.Compose([A.RandomRotate90()])
51+
)
52+
53+
# Split the data into train/val/test sets.
54+
loader.split(train = 0.8, val = 0.1, test = 0.1)
55+
```
56+
57+
The split datasets can be accessed using `loader.train_data`, `loader.val_data`, and `loader.test_data`. Any further processing applied to the
58+
main loader will be applied to the split datasets, until the split attributes are accessed, at which point you need to apply processing independently
59+
to each of the loaders. You can also turn toggle processing on and off using the `loader.eval()`, `loader.reset_preprocessing()`, and `loader.disable_preprocessing()`
60+
methods.
61+
62+
You can visualize data using the `agml.viz` module, which supports multiple different types of visualization for different data types:
63+
64+
```python
65+
# Disable processing and batching for the test data:
66+
test_ds = loader.test_data
67+
test_ds.batch(None)
68+
test_ds.reset_prepreprocessing()
69+
70+
# Visualize the image and mask side-by-side:
71+
agml.viz.visualize_image_and_mask(test_ds[0])
72+
73+
# Visualize the mask overlaid onto the image:
74+
agml.viz.visualize_overlaid_masks(test_ds[0])
75+
```
76+
77+
AgML supports both the TensorFlow and PyTorch libraries as backends, and provides functionality to export your loaders to native TensorFlow and PyTorch
78+
formats when you want to use them in a training pipeline. This includes both exporting the `AgMLDataLoader` to a `tf.data.Dataset` or `torch.utils.data.DataLoader`,
79+
but also internally converting data within the `AgMLDataLoader` itself, enabling access to its core functionality.
2680

27-
AgML aims to provide easy access to a range of existing public agricultural datasets The core of AgML's public data pipeline is
28-
[`AgMLDataLoader`](/agml/data/loader.py). Simply running the following line of code:
2981

3082
```python
31-
loader = AgMLDataLoader('<dataset_name_here>')
83+
# Export the loader as a `tf.data.Dataset`:
84+
train_ds = loader.train_data.export_tensorflow()
85+
86+
# Convert to PyTorch tensors without exporting.
87+
train_ds = loader.train_data
88+
train_ds.as_torch_dataset()
3289
```
3390

34-
will download the dataset locally from which point it will be automatically loaded from the disk on future runs.
91+
You're now ready to use AgML for training your own models!
92+
93+
## Usage Information
94+
95+
### Using Public Agricultural Data
96+
97+
AgML aims to provide easy access to a range of existing public agricultural datasets The core of AgML's public data pipeline is
98+
[`AgMLDataLoader`](/agml/data/loader.py). You can use the `AgMLDataLoader` or `agml.data.download_public_dataset()` to download
99+
the dataset locally from which point it will be automatically loaded from the disk on future runs.
35100
From this point, the data within the loader can be split into train/val/test sets, batched, have augmentations and transforms
36101
applied, and be converted into a training-ready dataset (including batching, tensor conversion, and image formatting).
37102

0 commit comments

Comments
 (0)