better doc

parent 8124400a
......@@ -10,14 +10,26 @@
#define CCLIP(x,a,b) ( (x) > (a) ? ( (x) < (b) ? (x) : (b) ) : (a) )
/**
* ways of extracting patches from an image.
*/
typedef enum {
EXTRACT_EXACT, /// only extract patches which contain true pixels, possibly leaving bordering pixels out
EXTRACT_FULL, /// extract patches so that whole image is covered, extrapolating border pixels as needed
EXTRACT_EXACT, ///< only extract patches which contain true pixels, possibly leaving bordering pixels out
EXTRACT_FULL, ///< extract patches so that whole image is covered, extrapolating border pixels as needed
} extract_t;
size_t compute_grid_size(const size_t size, const size_t width, const size_t stride, extract_t extract_type);
/**
* Extract patches from an image into a patches matrix
* \param I input binary image
* \param width the width (and height) of the patches
* \param stride the distance between adjacent patches
* \param e extraction method
* \param[out] P patches matrix
* \see extract_t
*/
void extract_patches(const binary_matrix& I,
const size_t width,
const size_t stride,
......@@ -25,7 +37,17 @@ void extract_patches(const binary_matrix& I,
binary_matrix& P);
// I must be preallocated
/**
* Stitch patches from a patches matrix into
* a target binary image.
* \param M number of rows in the image
* \param N number of columns in the image
* \param stride distance between adjacent patches
* \param e extraction mode
* \param[out] I output image
* \param[out] auxiliary accumulator (integer matrix)
* \param[out] auxiliary normalization factors (integer matrix)
*/
void stitch_patches(const binary_matrix& P,
const size_t M,
const size_t N,
......
/**
* \file bmf.cpp
* \brief Binary Matrix Factorization and Encoding using Dictionary Learning methods
*/
#include <omp.h>
#include "bmf_util.h"
#include "bmf.h"
......
......@@ -5,42 +5,78 @@
#ifndef BMF_H
#define BMF_H
/**
* Traditional alternate descent dictionary learningh
*/
idx_t learn_model_traditional(binary_matrix& X,
const binary_matrix& H,
binary_matrix& E,
binary_matrix& D,
binary_matrix& A);
/**
* \brief Alternating roles method, variant 1. Performs one iteration of coeficients
* update and dictionary learning for the model X = D*A + E, then switches roles
* then switches roles of A and D, Xt = At*Dt + Et and performs a pair of iterations again
* this is repeated until convergence.
*/
idx_t learn_model_alter1(binary_matrix& X,
const binary_matrix& H,
binary_matrix& E,
binary_matrix& D,
binary_matrix& A);
/**
* \brief Alternating roles method, variant 2.
* Repeats the traditional method until convergence for the model X = D*A + E
* then switches roles of A and D, Xt = At*Dt + Et, and relearns the model.
* This is repeated until convergence
*/
idx_t learn_model_alter2(binary_matrix& X,
const binary_matrix& H,
binary_matrix& E,
binary_matrix& D,
binary_matrix& A);
/**
* \brief Alternating roles method, variant 3.
* Never uses coefficients update methods. Each even iteration assumes D to be the dictionary and A to be the linear coeffs,
* and the odd iterations assume A to be the dictionary and D the coefficients. In each case, D and A are updated using
* the dictionary update routines.
*/
idx_t learn_model_alter3(binary_matrix& X,
const binary_matrix& H,
binary_matrix& E,
binary_matrix& D,
binary_matrix& A);
/**
* First The dictionary is initialized with a presumably small number of atoms K.
* Then, the model is learned using any of the 'inner' methods,
* and new atom is added and initialized using the same initialization function.
* The above process is repeated until adding new atoms does not improve the overall result
*/
idx_t learn_model_mdl_forward_selection(binary_matrix& X,
const binary_matrix& H,
binary_matrix& E,
binary_matrix& D,
binary_matrix& A);
/**
* First The dictionary is initialized with a presumably large number of atoms K.
* Then, the worst atom is removed and the model re-learned
* The above process is repeated until removing atoms does not improve the overall result
*/
idx_t learn_model_mdl_backward_selection(binary_matrix& X,
const binary_matrix& H,
binary_matrix& E,
binary_matrix& D,
binary_matrix& A);
/**
* Given a maximum number of atoms K, the best model is searched exhaustively
* for all K using the golden ratio method.
*/
idx_t learn_model_mdl_full_search(binary_matrix& X,
const binary_matrix& H,
binary_matrix& E,
......
/**
* \file bmf_learn_tool.cpp
* \brief Learns or updates a Binary Matrix Factorization model of the form $X = DA + E$ where $X$ is the input matrix, $D$ is a dictionary, $A$ are linear coefficients, and $E$ is a residual.
* \file bmf_encode_tool.cpp
* \brief Encodes the rows of a binary input matrix (and optional missing data matrix H) and produces an output coefficients matrix
*/
#include <cstdio>
#include <cstdlib>
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment