Python API¶
This section includes information for using the pure Python API of bob.core
.
Logging¶
bob.core.log.setup ((logger_name, ...) 
This function returns a logger object that is set up to perform logging using Bob loggers. 
bob.core.log.add_command_line_option (parser) 
Adds the verbosity command line option to the given parser. 
bob.core.log.set_verbosity_level (logger, level) 
Sets the log level for the given logger. 
bob.core.log.reset 

Random Numbers¶
bob.core.random.mt19937 
A MersenneTwister Random Number Generator (RNG) 
bob.core.random.uniform 
Models a random uniform distribution 
bob.core.random.normal 
Models a random normal distribution 
bob.core.random.lognormal 
Models a random lognormal distribution 
bob.core.random.gamma 
Models a random gamma distribution 
bob.core.random.binomial 
Models a random binomial distribution 
bob.core.random.discrete 
Models a random discrete distribution 
bob.core.random.variate_generator (engine, ...) 
A purepython version of the boost::variate_generator<> class 
Functions¶
bob.core.convert ((src, dtype, [dest_range], ...) 
Converts array data type, with optional range squash/expansion 
bob.core.get_config () 
Returns a string containing the configuration information. 
Details¶
Setsup logging, centrally for Bob.

bob.core.log.
setup
(logger_name[, format]) → logger[source]¶ This function returns a logger object that is set up to perform logging using Bob loggers.
Parameters:
logger_name
: str The name of the module to generate logs for
format
: str The format of the logs, see
logging.LogRecord
for more details. By default, the log contains the logger name, the log time, the log level and the massage.
Returns:
logger
:  The logger configured for logging.
The same logger can be retrieved using the
logging.getLogger()
function.
logging.Logger

bob.core.log.
add_command_line_option
(parser, short_option='v')[source]¶ Adds the verbosity command line option to the given parser.
The verbosity can by set to 0 (error), 1 (warning), 2 (info) or 3 (debug) by including the according number of –verbose command line arguments (e.g.,
vv
for info level).Parameters:
parser
:  A command line parser that you want to add a verbose option to
short_option
: str The short command line option that should be used for increasing the verbosity.
By default,
'v'
is considered as the shortcut
argparse.ArgumentParser
or one of its derivatives

bob.core.log.
set_verbosity_level
(logger, level)[source]¶ Sets the log level for the given logger.
Parameters:
logger
:  The logger to generate logs for, or the name of the module to generate logs for.
level
: int Possible log levels are: 0: Error; 1: Warning; 2: Info; 3: Debug.
logging.Logger
or str

bob.core.log.
reset
()¶  reset() > None
 reset(callable, [stream]) > None
Resets the standard C++ logging devices, or sets it to the given callable
This function allows you to manipulate the sinks for messages emitted in C++, using Python callables. The first variant (without parameters) will reset all logging output to
sys.stderr
. The second variant will reset the given logger to the given callable. Ifstream
is not specified, it resets all loggers.This function raises a
ValueError
in case of problems setting or resetting any of the streams.Parameters:
callable
: callableA python callable that receives anstr
and dumps messages to the desired output channelstream
: one of (‘debug’, ‘info’, warn’, ‘error’)[optional] If specified, only the given logger is send to the given callable. Otherwise all loggers are reset to that callable.
boost::random classes and methods

class
bob.core.random.
variate_generator
(engine, distribution)[source]¶ A purepython version of the boost::variate_generator<> class
Constructor Parameters:
engine
:  An instance of the already initialized RNG you would like to use.
distribution
: one of the distributions defined in  The distribution to respect when generating scalars using the engine. The distribution object should be previously initialized.
mt19937
bob.core.random

class
bob.core.random.
binomial
¶ Bases:
object
Models a random binomial distribution
This distribution produces random numbers distributed with the probability density function
where
t
andp
are parameters of the distribution.Warning
This distribution requires that and that .
Constructor Documentation:
bob.core.random.binomial (dtype, [t], [p])
Creates a new binomial distribution object
Parameters:
dtype
:numpy.dtype
The data type for the drawn random numbers; only integral types are supportedt
: float[Default:1.
] The parameter of the binomial distributionp
: float[Default:0.5
] The parameter of the binomial distributionClass Members:

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to useReturns:
value
: dtypeA random value that follows the binomial distribution

dtype
¶ numpy.dtype
<– The type of scalars produced by this binomial distribution

p
¶ float <– The parameter
p
of the distribution

reset
() → None¶ Resets this distribution
After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

t
¶ float <– The parameter
t
of the distribution


class
bob.core.random.
discrete
¶ Bases:
object
Models a random discrete distribution
A discrete distribution can only assume certain values, which for this class is defined as a number
i
in the range[0, len(probabilities)[
. Note that the condition , withP = probabilities
, is enforced by normalizing the input values so that the sum over all probabilities always equals 1.Constructor Documentation:
bob.core.random.discrete (dtype, probabilities)
Constructs a new discrete distribution object
Parameters:
dtype
:numpy.dtype
or anything that converts to a dtypeThe data type to get the distribution for; only integral types are supportedprobabilities
: [float] or iterable of floatsThe probabilities for drawing indexi
; this also defines the number of values that are drawnClass Members:

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to useReturns:
value
: dtypeA random value that follows the discrete distribution

dtype
¶ numpy.dtype
<– The type of scalars produced by this discrete distribution

probabilities
¶ [float] <– The values have been set for the discrete probabilities of every entry in this distribution

reset
() → None¶ Resets this distribution
After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset


class
bob.core.random.
gamma
¶ Bases:
object
Models a random gamma distribution
This distribution produces random numbers distributed with the probability density function
where
alpha
() is a parameter of this distribution class.Constructor Documentation:
bob.core.random.gamma (dtype, [alpha])
Constructs a new gamma distribution object
Parameters:
dtype
:numpy.dtype
or anything that converts to a dtypeThe data type to get the distribution for; only realvalued types are supportedalpha
: dtype[Default: 1.] The mean of the gamma distibutionClass Members:

alpha
¶ dtype <– The alpha parameter that the distribution currently has

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to useReturns:
value
: dtypeA random value that follows the gamma distribution

dtype
¶ numpy.dtype
<– The type of scalars produced by this normal distribution

reset
() → None¶ Resets this distribution
After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset


class
bob.core.random.
lognormal
¶ Bases:
object
Models a random lognormal distribution
This distribution produces random numbers distributed with the probability density function
for and , where the
mean
() andsigma
(, the standard deviation) are the parameters of this distribution class.Constructor Documentation:
bob.core.random.lognormal (dtype, [mean], [sigma])
Constructs a new lognormal distribution object
Parameters:
dtype
:numpy.dtype
or anything that converts to a dtypeThe data type to get the distribution for; only realvalued types are supportedmean
: dtype[Default: 0.] The mean of the lognormal distibutionsigma
: dtype[Default: 1.] The standard deviation of the lognormal distributiuonClass Members:

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to useReturns:
value
: dtypeA random value that follows the lognormal distribution

dtype
¶ numpy.dtype
<– The type of scalars produced by this normal distribution

mean
¶ dtype <– The mean value the distribution will produce.

reset
() → None¶ Resets this distribution
After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

sigma
¶ dtype <– The standard deviation the distribution will have


class
bob.core.random.
mt19937
¶ Bases:
object
A MersenneTwister Random Number Generator (RNG)
A Random Number Generator (RNG) based on the work Mersenne Twister: A 623dimensionally equidistributed uniform pseudorandom number generator, Makoto Matsumoto and Takuji Nishimura, ACM Transactions on Modeling and Computer Simulation: Special Issue on Uniform Random Number Generation, Vol. 8, No. 1, January 1998, pp. 330
Objects of this class support comparison operators such as
==
or!=
and setting the seed with the methodseed()
. Two random number generators are equal if they are at the same state – i.e. they have been initialized with the same seed and have been called the same number of times for number generation.Constructor Documentation:
bob.core.random.mt19937 ([seed])
Constructs and initializes a random number generator
If no
seed
is specified, the default seed (http://www.boost.org/doc/libs/1_59_0/doc/html/boost/random/mersenne_twister_engine.html) is used.Parameters:
seed
: int[optional] An integral value determining the initial seedClass Members:

seed
(seed) → None¶ Sets the seed for this random number generator
Parameters:
seed
: intA new seed value for this RNG


class
bob.core.random.
normal
¶ Bases:
object
Models a random normal distribution
This distribution produces random numbers distributed with the probability density function
where the
mean
() andsigma
(, the standard deviation) are the parameters of this distribution class.Constructor Documentation:
bob.core.random.normal (dtype, [mean], [sigma])
Constructs a new normal distribution object
Parameters:
dtype
:numpy.dtype
or anything that converts to a dtypeThe data type to get the distribution for; only realvalued types are supportedmean
: dtype[Default: 0.] The mean of the normal distibutionsigma
: dtype[Default: 1.] The standard deviation of the normal distributiuonClass Members:

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to useReturns:
value
: dtypeA random value that follows the normal distribution

dtype
¶ numpy.dtype
<– The type of scalars produced by this normal distribution

mean
¶ dtype <– The mean value the distribution will produce.

reset
() → None¶ Resets this distribution
After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset

sigma
¶ dtype <– The standard deviation the distribution will have


class
bob.core.random.
uniform
¶ Bases:
object
Models a random uniform distribution
On each invocation, it returns a random value uniformly distributed in the set of numbers [min, max] (integer) and [min, max[ (realvalued)
Constructor Documentation:
bob.core.random.uniform (dtype, [min], [max])
Constructs a new uniform distribution object
If the values
min
andmax
are not given, they are assumed to bemin=0
andmax=9
, for integral distributions andmin=0.0
andmax=1.0
for realvalued distributions.Parameters:
dtype
:numpy.dtype
or anything that converts to a dtypeThe data type to get the distribution formin
: dtype[Default: 0] The minimum value to drawmax
: dtype[Default: 1. (for realvalueddtype
) or 9 (for integraldtype
)] The maximum value to be drawnClass Members:

draw
(rng) → value¶ Draws one random number from this distribution using the given
rng
Note
The
__call__()
function is a synonym for thisdraw
.Parameters:
rng
:mt19937
The random number generator to useReturns:
value
: dtypeA random value that follows the uniform distribution

dtype
¶ numpy.dtype
<– The type of scalars produced by this uniform distribution

max
¶ dtype <– The largest value that the distributioncan produce
Integer uniform distributions are bound at [min, max], while realvalued distributions are bound at [min, max[.

min
¶ dtype <– The smallest value that the distribution can produce

reset
() → None¶ Resets this distribution
After calling this method, subsequent uses of the distribution do not depend on values produced by any random number generator prior to invoking reset


bob.core.
get_macros
() → macros[source]¶ Returns a list of preprocessor macros, such as
[(HAVE_BOOST, 1), (BOOST_VERSION,xx)]
. This function is automatically used bybob.extension.get_bob_libraries()
to retrieve the prerpocessor definitions that are required to use the C bindings of this library in dependent classes. You shouldn’t normally need to call this function by hand.Returns:
macros
: [str] The list of preprocessor macros required to use the C bindings of this class.

bob.core.
convert
(src, dtype[, dest_range][, source_range]) → converted¶ Converts array data type, with optional range squash/expansion
This function allows to convert/rescale a array of a given type into another array of a possibly different type. Typically, this can be used to rescale a 16 bit precision grayscale image (2D array) into an 8 bit precision grayscale image.
Parameters:
src
: array_likeInput arraydtype
:numpy.dtype
or anything convertibleThe element data type for the returnedconverted
arraydest_range
: (dtype, dtype)[Default: full range ofdtype
] The range[min, max]
to be deployed at theconverted
arraysource_range
: (X, X)[Default: full range ofsrc
data type] Determines the input range[min,max]
that will be used for scalingReturns:
converted
: array_likeA new array with the same shape assrc
, but rescaled and with its element type as given by thedtype