siamese/README.md

# Siamese Neural Network for Keras

This project provides a lightweight siamese neural network module for use with the Keras 
framework. 

The neural network compares two images and returns their similarity in a 0-1 float value.
The datasets used are the fruit-360 dataset, COCO 2014 and 2017 as well as some ImageNet data.

# Installation

- tensorflow

To install tensorflow:
```
$ pip install tensorflow
```

To install tensorflow with gpu support:
```
$ pip install tensorflow-gpu
```

- If you use tensorflow-gpu, you'll have to install Cuda and CuDNN.

## Usage
For detailed usage examples please refer to the examples and unit test modules. If the instructions are not sufficient 
feel free to make a request for improvements.

- Import the module
```python
from siamese import SiameseNetwork
```

- Load or generate some data.
```python
x_train = np.random.rand(100, 3)
y_train = np.random.randint(num_classes, size=100)

x_test = np.random.rand(30, 3)
y_test = np.random.randint(num_classes, size=30)
```

- Design a base model
```python
def create_base_model(input_shape):
    model_input = Input(shape=input_shape)
    embedding = Flatten()(model_input)
    embedding = Dense(128)(embedding)
    return Model(model_input, embedding)
```

- Design a head model
```python
def create_head_model(embedding_shape):
    embedding_a = Input(shape=embedding_shape)
    embedding_b = Input(shape=embedding_shape)
    
    head = Concatenate()([embedding_a, embedding_b])
    head = Dense(4)(head)
    head = BatchNormalization()(head)
    head = Activation(activation='sigmoid')(head)

    head = Dense(1)(head)
    head = BatchNormalization()(head)
    head = Activation(activation='sigmoid')(head)

    return Model([embedding_a, embedding_b], head)
```
- Create an instance of the SiameseNetwork class
```python
base_model = create_base_model(input_shape)
head_model = create_head_model(base_model.output_shape)
siamese_network = SiameseNetwork(base_model, head_model)
```

- Compile the model
```python
siamese_network.compile(loss='binary_crossentropy', optimizer=keras.optimizers.adam())
```

- Train the model
```python
siamese_network.fit(x_train, y_train,
                    validation_data=(x_test, y_test),
                    batch_size=64,
                    epochs=epochs)
```

## requirements

keras==2.2.4
numpy==1.16.4
pytest==4.6.4  
pep8==1.7.1