### Navigation

- index
- modules |
- dlib documentation »

Dlib is principally a C++ library, however, you can use a number of its tools from python applications. This page documents the python API for working with these dlib tools. If you haven’t done so already, you should probably look at the python example programs first before consulting this reference. These example programs are little mini-tutorials for using dlib from python. They are listed on the left of the main dlib web page.

# Classes

- `dlib.array`
- `dlib.cca_outputs`
- `dlib.matrix`
- `dlib.pair`
- `dlib.range`
- `dlib.ranges`
- `dlib.rangess`
- `dlib.ranking_pair`
- `dlib.ranking_pairs`
- `dlib.segmenter_params`
- `dlib.segmenter_test`
- `dlib.segmenter_type`
- `dlib.sparse_ranking_pair`
- `dlib.sparse_ranking_pairs`
- `dlib.sparse_vector`
- `dlib.sparse_vectors`
- `dlib.sparse_vectorss`
- `dlib.svm_c_trainer_histogram_intersection`
- `dlib.svm_c_trainer_linear`
- `dlib.svm_c_trainer_radial_basis`
- `dlib.svm_c_trainer_sparse_histogram_intersection`
- `dlib.svm_c_trainer_sparse_linear`
- `dlib.svm_c_trainer_sparse_radial_basis`
- `dlib.svm_rank_trainer`
- `dlib.svm_rank_trainer_sparse`
- `dlib.vector`
- `dlib.vectors`
- `dlib.vectorss`

# Functions

- `dlib.apply_cca_transform()`
- `dlib.assignment_cost()`
- `dlib.cca()`
- `dlib.cross_validate_ranking_trainer()`
- `dlib.cross_validate_sequence_segmenter()`
- `dlib.cross_validate_trainer()`
- `dlib.cross_validate_trainer_threaded()`
- `dlib.dot()`
- `dlib.load_libsvm_formatted_data()`
- `dlib.make_sparse_vector()`
- `dlib.max_cost_assignment()`
- `dlib.max_index_plus_one()`
- `dlib.save_libsvm_formatted_data()`
- `dlib.solve_structural_svm_problem()`
- `dlib.test_binary_decision_function()`
- `dlib.test_ranking_function()`
- `dlib.test_regression_function()`
- `dlib.test_sequence_segmenter()`
- `dlib.train_sequence_segmenter()`

# Detailed API Listing

`dlib.``apply_cca_transform`((matrix)m, (sparse_vector)v) → vector :
  requires
    - max_index_plus_one(v) <= m.nr()
  ensures
    - returns trans(m)*v (i.e. multiply m by the vector v and return the result)

class `dlib.``array`

  This object represents a 1D array of floating point numbers. Moreover, it binds directly to the C++ type std::vector<double>.

  `append`((array)arg1, (object)arg2) → None
  `clear`((array)arg1) → None
  `extend`((array)arg1, (object)arg2) → None
  `resize`((array)arg1, (int)arg2) → None

`dlib.``assignment_cost`((matrix)cost, (list)assignment) → float :
  requires

    - cost.nr() == cost.nc() (i.e. the input must be a square matrix)

    - for all valid i:
        - 0 <= assignment[i] < cost.nr()
  ensures

    - Interprets cost as a cost assignment matrix. That is, cost[i][j] represents the cost of assigning i to j.

    - Interprets assignment as a particular set of assignments. That is, i is assigned to assignment[i].

    - returns the cost of the given assignment. That is, returns a number which is:

      > sum over i: cost[i][assignment[i]]

`dlib.``cca`((sparse_vectors)L, (sparse_vectors)R, (int)num_correlations[, (int)extra_rank=5[, (int)q=2[, (float)regularization=0]]]) → cca_outputs :
  requires
    - num_correlations > 0
    - len(L) > 0
    - len(R) > 0
    - len(L) == len(R)
    - regularization >= 0
    - L and R must be properly sorted sparse vectors. This means they must list their elements in ascending index order and not contain duplicate index values. You can use make_sparse_vector() to ensure this is true.
  ensures

    - This function performs a canonical correlation analysis between the vectors in L and R. That is, it finds two transformation matrices, Ltrans and Rtrans, such that row vectors in the transformed matrices L*Ltrans and R*Rtrans are as correlated as possible (note that in this notation we interpret L as a matrix with the input vectors in its rows). Note also that this function tries to find transformations which produce num_correlations dimensional output vectors.

    - Note that you can easily apply the transformation to a vector using apply_cca_transform(). So for example, like this:

      > - apply_cca_transform(Ltrans, some_sparse_vector)

    - returns a structure containing the Ltrans and Rtrans transformation matrices as well as the estimated correlations between elements of the transformed vectors.

    - This function assumes the data vectors in L and R have already been centered (i.e. we assume the vectors have zero means). However, in many cases it is fine to use uncentered data with cca(). But if it is important for your problem then you should center your data before passing it to cca().

    - This function works with reduced rank approximations of the L and R matrices. This makes it fast when working with large matrices. In particular, we use the dlib::svd_fast() routine to find reduced rank representations of the input matrices by calling it as follows: svd_fast(L, U,D,V, num_correlations+extra_rank, q) and similarly for R. This means that you can use the extra_rank and q arguments to cca() to influence the accuracy of the reduced rank approximation. However, the default values should work fine for most problems.

    - This function performs the ridge regression version of Canonical Correlation Analysis when regularization is set to a value > 0. In particular, larger values indicate the solution should be more heavily regularized. This can be useful when the dimensionality of the data is larger than the number of samples.

    - A good discussion of CCA can be found in the paper “Canonical Correlation Analysis” by David Weenink. In particular, this function is implemented using equations 29 and 30 from his paper. We also use the idea of doing CCA on a reduced rank approximation of L and R as suggested by Paramveer S. Dhillon in his paper “Two Step CCA: A new spectral method for estimating vector models of words”.

class `dlib.``cca_outputs`
  `Ltrans`
  `Rtrans`
  `correlations`

`dlib.``cross_validate_ranking_trainer`((svm_rank_trainer)trainer, (ranking_pairs)samples, (int)folds) → _ranking_test

  cross_validate_ranking_trainer( (svm_rank_trainer_sparse)trainer, (sparse_ranking_pairs)samples, (int)folds) -> _ranking_test

`dlib.``cross_validate_sequence_segmenter`((vectorss)samples, (rangess)segments, (int)folds[, (segmenter_params)params=<BIO, highFeats, signed, win=5, threads=4, eps=0.1, cache=40, non-verbose, C=100>]) → segmenter_test

  cross_validate_sequence_segmenter( (sparse_vectorss)samples, (rangess)segments, (int)folds [, (segmenter_params)params=<BIO,highFeats,signed,win=5,threads=4,eps=0.1,cache=40,non-verbose,C=100>]) -> segmenter_test

`dlib.``cross_validate_trainer`((svm_c_trainer_radial_basis)trainer, (vectors)x, (array)y, (int)folds) → _binary_test

  cross_validate_trainer( (svm_c_trainer_sparse_radial_basis)trainer, (sparse_vectors)x, (array)y, (int)folds) -> _binary_test

  cross_validate_trainer( (svm_c_trainer_histogram_intersection)trainer, (vectors)x, (array)y, (int)folds) -> _binary_test

  cross_validate_trainer( (svm_c_trainer_sparse_histogram_intersection)trainer, (sparse_vectors)x, (array)y, (int)folds) -> _binary_test

  cross_validate_trainer( (svm_c_trainer_linear)trainer, (vectors)x, (array)y, (int)folds) -> _binary_test

  cross_validate_trainer( (svm_c_trainer_sparse_linear)trainer, (sparse_vectors)x, (array)y, (int)folds) -> _binary_test

`dlib.``cross_validate_trainer_threaded`((svm_c_trainer_radial_basis)trainer, (vectors)x, (array)y, (int)folds, (int)num_threads) → _binary_test

  cross_validate_trainer_threaded( (svm_c_trainer_sparse_radial_basis)trainer, (sparse_vectors)x, (array)y, (int)folds, (int)num_threads) -> _binary_test

  cross_validate_trainer_threaded( (svm_c_trainer_histogram_intersection)trainer, (vectors)x, (array)y, (int)folds, (int)num_threads) -> _binary_test

  cross_validate_trainer_threaded( (svm_c_trainer_sparse_histogram_intersection)trainer, (sparse_vectors)x, (array)y, (int)folds, (int)num_threads) -> _binary_test

  cross_validate_trainer_threaded( (svm_c_trainer_linear)trainer, (vectors)x, (array)y, (int)folds, (int)num_threads) -> _binary_test

  cross_validate_trainer_threaded( (svm_c_trainer_sparse_linear)trainer, (sparse_vectors)x, (array)y, (int)folds, (int)num_threads) -> _binary_test

`dlib.``dot`((vector)arg1, (vector)arg2) → float :

  Compute the dot product between two dense column vectors.

`dlib.``load_libsvm_formatted_data`((str)file_name) → tuple :
  ensures
    - Attempts to read a file of the given name that should contain libsvm formatted data. The data is returned as a tuple where the first tuple element is an array of sparse vectors and the second element is an array of labels.

`dlib.``make_sparse_vector`((sparse_vector)arg1) → None :

  > This function modifies its argument so that it is a properly sorted sparse vector. This means that the elements of the sparse vector will be ordered so that pairs with smaller indices come first. Additionally, there won’t be any pairs with identical indices. If such pairs were present in the input sparse vector then their values will be added together and only one pair with their index will be present in the output.

  make_sparse_vector( (sparse_vectors)arg1) -> None :
    This function modifies a sparse_vectors object so that all elements it contains are properly sorted sparse vectors.

class `dlib.``matrix`

  This object represents a dense 2D matrix of floating point numbers.Moreover, it binds directly to the C++ type dlib::matrix<double>.

  `nc`((matrix)arg1) → int :

    Return the number of columns in the matrix.

  `nr`((matrix)arg1) → int :

    Return the number of rows in the matrix.

  `set_size`((matrix)arg1, (int)rows, (int)cols) → None :

    Set the size of the matrix to the given number of rows and columns.

  `shape`

`dlib.``max_cost_assignment`((matrix)cost) → list :
  requires
    - cost.nr() == cost.nc() (i.e. the input must be a square matrix)
  ensures

    - Finds and returns the solution to the following optimization problem:

      > Maximize: f(A) == assignment_cost(cost, A) Subject to the following constraints:

      > > - The elements of A are unique. That is, there aren’t any elements of A which are equal.
      > > - len(A) == cost.nr()

    - Note that this function converts the input cost matrix into a 64bit fixed point representation. Therefore, you should make sure that the values in your cost matrix can be accurately represented by 64bit fixed point values. If this is not the case then the solution my become inaccurate due to rounding error. In general, this function will work properly when the ratio of the largest to the smallest value in cost is no more than about 1e16.

`dlib.``max_index_plus_one`((sparse_vector)v) → int :
  ensures
    - returns the dimensionality of the given sparse vector. That is, returns a number one larger than the maximum index value in the vector. If the vector is empty then returns 0.

class `dlib.``pair`

  This object is used to represent the elements of a sparse_vector.

  `first`

    This field represents the index/dimension number.

  `second`

    This field contains the value in a vector at dimension specified by the first field.

class `dlib.``range`

  This object is used to represent a range of elements in an array.

  `begin`

    The index of the first element in the range.

  `end`

    One past the index of the last element in the range.

class `dlib.``ranges`

  This object is an array of range objects.

  `append`((ranges)arg1, (object)arg2) → None
  `clear`((ranges)arg1) → None
  `extend`((ranges)arg1, (object)arg2) → None
  `resize`((ranges)arg1, (int)arg2) → None

class `dlib.``rangess`

  This object is an array of arrays of range objects.

  `append`((rangess)arg1, (object)arg2) → None
  `clear`((rangess)arg1) → None
  `extend`((rangess)arg1, (object)arg2) → None
  `resize`((rangess)arg1, (int)arg2) → None

class `dlib.``ranking_pair`
  `nonrelevant`
  `relevant`

class `dlib.``ranking_pairs`
  `append`((ranking_pairs)arg1, (object)arg2) → None
  `clear`((ranking_pairs)arg1) → None
  `extend`((ranking_pairs)arg1, (object)arg2) → None
  `resize`((ranking_pairs)arg1, (int)arg2) → None

`dlib.``save_libsvm_formatted_data`((str)file_name, (sparse_vectors)samples, (array)labels) → None :
  requires
    - len(samples) == len(labels)
  ensures
    - saves the data to the given file in libsvm format

class `dlib.``segmenter_params`

  This class is used to define all the optional parameters to the train_sequence_segmenter() and cross_validate_sequence_segmenter() routines.

  `C`

    SVM C parameter

  `allow_negative_weights`
  `be_verbose`
  `epsilon`
  `max_cache_size`
  `num_threads`
  `use_BIO_model`
  `use_high_order_features`
  `window_size`

class `dlib.``segmenter_test`

  This object is the output of the dlib.test_sequence_segmenter() and dlib.cross_validate_sequence_segmenter() routines.

  `f1`
  `precision`
  `recall`

class `dlib.``segmenter_type`

  This object represents a sequence segmenter and is the type of object returned by the dlib.train_sequence_segmenter() routine.

  `weights`

`dlib.``solve_structural_svm_problem`((object)problem) → vector :

  This function solves a structural SVM problem and returns the weight vector that defines the solution. See the example program python_examples/svm_struct.py for documentation about how to create a proper problem object.

class `dlib.``sparse_ranking_pair`
  `nonrelevant`
  `relevant`

class `dlib.``sparse_ranking_pairs`
  `append`((sparse_ranking_pairs)arg1, (object)arg2) → None
  `clear`((sparse_ranking_pairs)arg1) → None
  `extend`((sparse_ranking_pairs)arg1, (object)arg2) → None
  `resize`((sparse_ranking_pairs)arg1, (int)arg2) → None

class `dlib.``sparse_vector`

  This object represents the mathematical idea of a sparse column vector. It is simply an array of dlib.pair objects, each representing an index/value pair in the vector. Any elements of the vector which are missing are implicitly set to zero.

  Unless otherwise noted, any routines taking a sparse_vector assume the sparse vector is sorted and has unique elements. That is, the index values of the pairs in a sparse_vector should be listed in increasing order and there should not be duplicates. However, some functions work with “unsorted” sparse vectors. These are dlib.sparse_vector objects that have either duplicate entries or non-sorted index values. Note further that you can convert an “unsorted” sparse_vector into a properly sorted sparse vector by calling dlib.make_sparse_vector() on it.

  `append`((sparse_vector)arg1, (object)arg2) → None
  `clear`((sparse_vector)arg1) → None
  `extend`((sparse_vector)arg1, (object)arg2) → None
  `resize`((sparse_vector)arg1, (int)arg2) → None

class `dlib.``sparse_vectors`

  This object is an array of sparse_vector objects.

  `append`((sparse_vectors)arg1, (object)arg2) → None
  `clear`((sparse_vectors)arg1) → None
  `extend`((sparse_vectors)arg1, (object)arg2) → None
  `resize`((sparse_vectors)arg1, (int)arg2) → None

class `dlib.``sparse_vectorss`

  This object is an array of arrays of sparse_vector objects.

  `append`((sparse_vectorss)arg1, (object)arg2) → None
  `clear`((sparse_vectorss)arg1) → None
  `extend`((sparse_vectorss)arg1, (object)arg2) → None
  `resize`((sparse_vectorss)arg1, (int)arg2) → None

class `dlib.``svm_c_trainer_histogram_intersection`
  `c_class1`
  `c_class2`
  `cache_size`
  `epsilon`
  `set_c`((svm_c_trainer_histogram_intersection)arg1, (float)arg2) → None
  `train`((svm_c_trainer_histogram_intersection)arg1, (vectors)arg2, (array)arg3) → _decision_function_histogram_intersection

class `dlib.``svm_c_trainer_linear`
  `be_quiet`((svm_c_trainer_linear)arg1) → None
  `be_verbose`((svm_c_trainer_linear)arg1) → None
  `c_class1`
  `c_class2`
  `epsilon`
  `force_last_weight_to_1`
  `learns_nonnegative_weights`
  `max_iterations`
  `set_c`((svm_c_trainer_linear)arg1, (float)arg2) → None
  `train`((svm_c_trainer_linear)arg1, (vectors)arg2, (array)arg3) → _decision_function_linear

class `dlib.``svm_c_trainer_radial_basis`
  `c_class1`
  `c_class2`
  `cache_size`
  `epsilon`
  `gamma`
  `set_c`((svm_c_trainer_radial_basis)arg1, (float)arg2) → None
  `train`((svm_c_trainer_radial_basis)arg1, (vectors)arg2, (array)arg3) → _decision_function_radial_basis

class `dlib.``svm_c_trainer_sparse_histogram_intersection`
  `c_class1`
  `c_class2`
  `cache_size`
  `epsilon`
  `set_c`((svm_c_trainer_sparse_histogram_intersection)arg1, (float)arg2) → None
  `train`((svm_c_trainer_sparse_histogram_intersection)arg1, (sparse_vectors)arg2, (array)arg3) → _decision_function_sparse_histogram_intersection

class `dlib.``svm_c_trainer_sparse_linear`
  `be_quiet`((svm_c_trainer_sparse_linear)arg1) → None
  `be_verbose`((svm_c_trainer_sparse_linear)arg1) → None
  `c_class1`
  `c_class2`
  `epsilon`
  `force_last_weight_to_1`
  `learns_nonnegative_weights`
  `max_iterations`
  `set_c`((svm_c_trainer_sparse_linear)arg1, (float)arg2) → None
  `train`((svm_c_trainer_sparse_linear)arg1, (sparse_vectors)arg2, (array)arg3) → _decision_function_sparse_linear

class `dlib.``svm_c_trainer_sparse_radial_basis`
  `c_class1`
  `c_class2`
  `cache_size`
  `epsilon`
  `gamma`
  `set_c`((svm_c_trainer_sparse_radial_basis)arg1, (float)arg2) → None
  `train`((svm_c_trainer_sparse_radial_basis)arg1, (sparse_vectors)arg2, (array)arg3) → _decision_function_sparse_radial_basis

class `dlib.``svm_rank_trainer`
  `be_quiet`((svm_rank_trainer)arg1) → None
  `be_verbose`((svm_rank_trainer)arg1) → None
  `c`
  `epsilon`
  `force_last_weight_to_1`
  `learns_nonnegative_weights`
  `max_iterations`
  `train`((svm_rank_trainer)arg1, (ranking_pair)arg2) → _decision_function_linear

    train( (svm_rank_trainer)arg1, (ranking_pairs)arg2) -> _decision_function_linear

class `dlib.``svm_rank_trainer_sparse`
  `be_quiet`((svm_rank_trainer_sparse)arg1) → None
  `be_verbose`((svm_rank_trainer_sparse)arg1) → None
  `c`
  `epsilon`
  `force_last_weight_to_1`
  `learns_nonnegative_weights`
  `max_iterations`
  `train`((svm_rank_trainer_sparse)arg1, (sparse_ranking_pair)arg2) → _decision_function_sparse_linear

    train( (svm_rank_trainer_sparse)arg1, (sparse_ranking_pairs)arg2) -> _decision_function_sparse_linear

`dlib.``test_binary_decision_function`((_decision_function_linear)function, (vectors)samples, (array)labels) → _binary_test

  test_binary_decision_function( (_decision_function_sparse_linear)function, (sparse_vectors)samples, (array)labels) -> _binary_test

  test_binary_decision_function( (_decision_function_radial_basis)function, (vectors)samples, (array)labels) -> _binary_test

  test_binary_decision_function( (_decision_function_sparse_radial_basis)function, (sparse_vectors)samples, (array)labels) -> _binary_test

  test_binary_decision_function( (_decision_function_polynomial)function, (vectors)samples, (array)labels) -> _binary_test

  test_binary_decision_function( (_decision_function_sparse_polynomial)function, (sparse_vectors)samples, (array)labels) -> _binary_test

  test_binary_decision_function( (_decision_function_histogram_intersection)function, (vectors)samples, (array)labels) -> _binary_test

  test_binary_decision_function( (_decision_function_sparse_histogram_intersection)function, (sparse_vectors)samples, (array)labels) -> _binary_test

  test_binary_decision_function( (_decision_function_sigmoid)function, (vectors)samples, (array)labels) -> _binary_test

  test_binary_decision_function( (_decision_function_sparse_sigmoid)function, (sparse_vectors)samples, (array)labels) -> _binary_test

`dlib.``test_ranking_function`((_decision_function_linear)function, (ranking_pairs)samples) → _ranking_test

  test_ranking_function( (_decision_function_sparse_linear)function, (sparse_ranking_pairs)samples) -> _ranking_test

  test_ranking_function( (_decision_function_linear)function, (ranking_pair)sample) -> _ranking_test

  test_ranking_function( (_decision_function_sparse_linear)function, (sparse_ranking_pair)sample) -> _ranking_test

`dlib.``test_regression_function`((_decision_function_linear)function, (vectors)samples, (array)targets) → _regression_test

  test_regression_function( (_decision_function_sparse_linear)function, (sparse_vectors)samples, (array)targets) -> _regression_test

  test_regression_function( (_decision_function_radial_basis)function, (vectors)samples, (array)targets) -> _regression_test

  test_regression_function( (_decision_function_sparse_radial_basis)function, (sparse_vectors)samples, (array)targets) -> _regression_test

  test_regression_function( (_decision_function_histogram_intersection)function, (vectors)samples, (array)targets) -> _regression_test

  test_regression_function( (_decision_function_sparse_histogram_intersection)function, (sparse_vectors)samples, (array)targets) -> _regression_test

  test_regression_function( (_decision_function_sigmoid)function, (vectors)samples, (array)targets) -> _regression_test

  test_regression_function( (_decision_function_sparse_sigmoid)function, (sparse_vectors)samples, (array)targets) -> _regression_test

  test_regression_function( (_decision_function_polynomial)function, (vectors)samples, (array)targets) -> _regression_test

  test_regression_function( (_decision_function_sparse_polynomial)function, (sparse_vectors)samples, (array)targets) -> _regression_test

`dlib.``test_sequence_segmenter`((segmenter_type)arg1, (vectorss)arg2, (rangess)arg3) → segmenter_test

  test_sequence_segmenter( (segmenter_type)arg1, (sparse_vectorss)arg2, (rangess)arg3) -> segmenter_test

`dlib.``train_sequence_segmenter`((vectorss)samples, (rangess)segments[, (segmenter_params)params=<BIO, highFeats, signed, win=5, threads=4, eps=0.1, cache=40, non-verbose, C=100>]) → segmenter_type

  train_sequence_segmenter( (sparse_vectorss)samples, (rangess)segments [, (segmenter_params)params=<BIO,highFeats,signed,win=5,threads=4,eps=0.1,cache=40,non-verbose,C=100>]) -> segmenter_type

class `dlib.``vector`

  This object represents the mathematical idea of a column vector.

  `resize`((vector)arg1, (int)arg2) → None
  `set_size`((vector)arg1, (int)arg2) → None
  `shape`

class `dlib.``vectors`

  This object is an array of vector objects.

  `append`((vectors)arg1, (object)arg2) → None
  `clear`((vectors)arg1) → None
  `extend`((vectors)arg1, (object)arg2) → None
  `resize`((vectors)arg1, (int)arg2) → None

class `dlib.``vectorss`

  This object is an array of arrays of vector objects.

  `append`((vectorss)arg1, (object)arg2) → None
  `clear`((vectorss)arg1) → None
  `extend`((vectorss)arg1, (object)arg2) → None
  `resize`((vectorss)arg1, (int)arg2) → None

### Navigation

- index
- modules |
- dlib documentation »