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

from siamese import SiameseNetwork

• Load or generate some data.

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

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

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

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

siamese_network.compile(loss='binary_crossentropy', optimizer=keras.optimizers.adam())

• Train the model

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