caffe的python接口封装原理与解析

Posted 2022-12-09 sloanqin

【说明】：欢迎加入：faster-rcnn 交流群 238138700，caffe提供了灵活的python的接口，那么这些接口是如何实现的，caffe是如何有效的把c++中的方法和类，让我们在python中可以灵活调用的；

【c/c++扩展】：python中调用c/c++称为扩展，扩展的方法有很多；

标准的方法是：通过样板来包装c/c++代码，这种是最原始的方式，具体的实现可以参考《python核心编程》--22章，看这章的好处就是可以理解封装的思路是怎样的，为什么可行；

第二类方法就是借用各种各样的工具来减轻我们的工作量：听得最多的应该是SWIG，应该比较好用；caffe用的不是这个，caffe用的是boost python（能够极大提高c++为python写扩展的效率）

【跟其他工具的比较】：这一段我是借鉴别人的评述：点击打开链接

目前有多个工具可以实现跟 Boost.Python 类似的功能，如 SWIG，SIP等。但是它们有很大的不同。SWIG 和 SIP 都定义了一种接口描述语言。我需要先写一个接口描述文件，用于描述我要导出的 C++ 函数和类。然后通过一个翻译器，将接口描述文件翻译成 C++ 程序。最后编译连接生成的 C++ 程序来生成扩展库。而 Boost.Python 用于导出 C++ 函数和类的时候，我需要添加的也是 C++ 的代码，这是 Boost.Python 的最大特点之一。
SWIG 比较适合用来包装 C 语言程序，最近也开始增强一些对 C++ 的支持，但是到目前还不支持嵌套类等 C++ 特性。SIP 似乎除了用在包装 Qt 库之外，就没几个人用。而 Boost.Python 可能是这三者之间对 C++ 支持最好的一个。不过 Boost.Python 也有缺点，就是它使用了大量模板技巧，因此当要导出的元素比较多时，编译非常慢。不过幸好作为“胶水”，我并不需要经常修改和重编译，而且如果使用预编译头的话可以进一步提高编译速度。
Boost.Python 的另外一个优点是，它的设计目标就是让 C++ 程序库可以透明地导出到 Python 中去。即在完全不修改原来 C++ 程序的情况下，导出给 Python 用。在这种设计理念下设计出来的 Boost.Python 比同类工具支持了给完善的 C++ 特性，能够最大程度地保证不修改原 C++ 程序。要知道贸然修改别人的程序，往往会带来许多难以察觉的错误。
基于以上几点，我推荐大家在需要的时候使用 Boost.Python，而不是其它。这也是我写这篇文章的最大动力 :-)。

【boost python】：

官网的教程是最好的教材，写的也比较简洁：点击打开链接

我决定跟着官网的教程走一遍，把需要记录的写下来，建议大家也可以跟着官网教程走一遍；

【caffe的python接口代码】：caffe的python接口的代码就是在./python/caffe/_caffe.cpp文件中实现的，使用的就是boost python库；

#include <Python.h>  // NOLINT(build/include_alpha)

// Produce deprecation warnings (needs to come before arrayobject.h inclusion).
#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION

#include <boost/make_shared.hpp>
#include <boost/python.hpp>
#include <boost/python/raw_function.hpp>
#include <boost/python/suite/indexing/vector_indexing_suite.hpp>
#include <boost/python/enum.hpp>
#include <numpy/arrayobject.h>

// these need to be included after boost on OS X
#include <string>  // NOLINT(build/include_order)
#include <vector>  // NOLINT(build/include_order)
#include <fstream>  // NOLINT

#include "caffe/caffe.hpp"
#include "caffe/layers/memory_data_layer.hpp"
#include "caffe/layers/python_layer.hpp"
#include "caffe/sgd_solvers.hpp"

// Temporary solution for numpy < 1.7 versions: old macro, no promises.
// You're strongly advised to upgrade to >= 1.7.
#ifndef NPY_ARRAY_C_CONTIGUOUS
#define NPY_ARRAY_C_CONTIGUOUS NPY_C_CONTIGUOUS
#define PyArray_SetBaseObject(arr, x) (PyArray_BASE(arr) = (x))
#endif

namespace bp = boost::python;

namespace caffe 

// For Python, for now, we'll just always use float as the type.
typedef float Dtype;
const int NPY_DTYPE = NPY_FLOAT32;

// Selecting mode.
void set_mode_cpu()  Caffe::set_mode(Caffe::CPU); 
void set_mode_gpu()  Caffe::set_mode(Caffe::GPU); 

// For convenience, check that input files can be opened, and raise an
// exception that boost will send to Python if not (caffe could still crash
// later if the input files are disturbed before they are actually used, but
// this saves frustration in most cases).
static void CheckFile(const string& filename) 
    std::ifstream f(filename.c_str());
    if (!f.good()) 
      f.close();
      throw std::runtime_error("Could not open file " + filename);
    
    f.close();


void CheckContiguousArray(PyArrayObject* arr, string name,
    int channels, int height, int width) 
  if (!(PyArray_FLAGS(arr) & NPY_ARRAY_C_CONTIGUOUS)) 
    throw std::runtime_error(name + " must be C contiguous");
  
  if (PyArray_NDIM(arr) != 4) 
    throw std::runtime_error(name + " must be 4-d");
  
  if (PyArray_TYPE(arr) != NPY_FLOAT32) 
    throw std::runtime_error(name + " must be float32");
  
  if (PyArray_DIMS(arr)[1] != channels) 
    throw std::runtime_error(name + " has wrong number of channels");
  
  if (PyArray_DIMS(arr)[2] != height) 
    throw std::runtime_error(name + " has wrong height");
  
  if (PyArray_DIMS(arr)[3] != width) 
    throw std::runtime_error(name + " has wrong width");
  


// Net constructor for passing phase as int
shared_ptr<Net<Dtype> > Net_Init(
    string param_file, int phase) 
  CheckFile(param_file);

  shared_ptr<Net<Dtype> > net(new Net<Dtype>(param_file,
      static_cast<Phase>(phase)));
  return net;


// Net construct-and-load convenience constructor
shared_ptr<Net<Dtype> > Net_Init_Load(
    string param_file, string pretrained_param_file, int phase) 
  CheckFile(param_file);
  CheckFile(pretrained_param_file);

  shared_ptr<Net<Dtype> > net(new Net<Dtype>(param_file,
      static_cast<Phase>(phase)));
  net->CopyTrainedLayersFrom(pretrained_param_file);
  return net;


void Net_Save(const Net<Dtype>& net, string filename) 
  NetParameter net_param;
  net.ToProto(&net_param, false);
  WriteProtoToBinaryFile(net_param, filename.c_str());


void Net_SetInputArrays(Net<Dtype>* net, bp::object data_obj,
    bp::object labels_obj) 
  // check that this network has an input MemoryDataLayer
  shared_ptr<MemoryDataLayer<Dtype> > md_layer =
    boost::dynamic_pointer_cast<MemoryDataLayer<Dtype> >(net->layers()[0]);
  if (!md_layer) 
    throw std::runtime_error("set_input_arrays may only be called if the"
        " first layer is a MemoryDataLayer");
  

  // check that we were passed appropriately-sized contiguous memory
  PyArrayObject* data_arr =
      reinterpret_cast<PyArrayObject*>(data_obj.ptr());
  PyArrayObject* labels_arr =
      reinterpret_cast<PyArrayObject*>(labels_obj.ptr());
  CheckContiguousArray(data_arr, "data array", md_layer->channels(),
      md_layer->height(), md_layer->width());
  CheckContiguousArray(labels_arr, "labels array", 1, 1, 1);
  if (PyArray_DIMS(data_arr)[0] != PyArray_DIMS(labels_arr)[0]) 
    throw std::runtime_error("data and labels must have the same first"
        " dimension");
  
  if (PyArray_DIMS(data_arr)[0] % md_layer->batch_size() != 0) 
    throw std::runtime_error("first dimensions of input arrays must be a"
        " multiple of batch size");
  

  md_layer->Reset(static_cast<Dtype*>(PyArray_DATA(data_arr)),
      static_cast<Dtype*>(PyArray_DATA(labels_arr)),
      PyArray_DIMS(data_arr)[0]);


Solver<Dtype>* GetSolverFromFile(const string& filename) 
  SolverParameter param;
  ReadSolverParamsFromTextFileOrDie(filename, ¶m);
  return SolverRegistry<Dtype>::CreateSolver(param);


struct NdarrayConverterGenerator 
  template <typename T> struct apply;
;

template <>
struct NdarrayConverterGenerator::apply<Dtype*> 
  struct type 
    PyObject* operator() (Dtype* data) const 
      // Just store the data pointer, and add the shape information in postcall.
      return PyArray_SimpleNewFromData(0, NULL, NPY_DTYPE, data);
    
    const PyTypeObject* get_pytype() 
      return &PyArray_Type;
    
  ;
;

struct NdarrayCallPolicies : public bp::default_call_policies 
  typedef NdarrayConverterGenerator result_converter;
  PyObject* postcall(PyObject* pyargs, PyObject* result) 
    bp::object pyblob = bp::extract<bp::tuple>(pyargs)()[0];
    shared_ptr<Blob<Dtype> > blob =
      bp::extract<shared_ptr<Blob<Dtype> > >(pyblob);
    // Free the temporary pointer-holding array, and construct a new one with
    // the shape information from the blob.
    void* data = PyArray_DATA(reinterpret_cast<PyArrayObject*>(result));
    Py_DECREF(result);
    const int num_axes = blob->num_axes();
    vector<npy_intp> dims(blob->shape().begin(), blob->shape().end());
    PyObject *arr_obj = PyArray_SimpleNewFromData(num_axes, dims.data(),
                                                  NPY_FLOAT32, data);
    // SetBaseObject steals a ref, so we need to INCREF.
    Py_INCREF(pyblob.ptr());
    PyArray_SetBaseObject(reinterpret_cast<PyArrayObject*>(arr_obj),
        pyblob.ptr());
    return arr_obj;
  
;

bp::object Blob_Reshape(bp::tuple args, bp::dict kwargs) 
  if (bp::len(kwargs) > 0) 
    throw std::runtime_error("Blob.reshape takes no kwargs");
  
  Blob<Dtype>* self = bp::extract<Blob<Dtype>*>(args[0]);
  vector<int> shape(bp::len(args) - 1);
  for (int i = 1; i < bp::len(args); ++i) 
    shape[i - 1] = bp::extract<int>(args[i]);
  
  self->Reshape(shape);
  // We need to explicitly return None to use bp::raw_function.
  return bp::object();


bp::object BlobVec_add_blob(bp::tuple args, bp::dict kwargs) 
  if (bp::len(kwargs) > 0) 
    throw std::runtime_error("BlobVec.add_blob takes no kwargs");
  
  typedef vector<shared_ptr<Blob<Dtype> > > BlobVec;
  BlobVec* self = bp::extract<BlobVec*>(args[0]);
  vector<int> shape(bp::len(args) - 1);
  for (int i = 1; i < bp::len(args); ++i) 
    shape[i - 1] = bp::extract<int>(args[i]);
  
  self->push_back(shared_ptr<Blob<Dtype> >(new Blob<Dtype>(shape)));
  // We need to explicitly return None to use bp::raw_function.
  return bp::object();


BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(SolveOverloads, Solve, 0, 1);

BOOST_PYTHON_MODULE(_caffe)  //给封装的C++模块命名，名称就是_caffe，所以后面编译生成的共享库就是_caffe.so
  // below, we prepend an underscore to methods that will be replaced
  // in Python

  bp::scope().attr("__version__") = AS_STRING(CAFFE_VERSION);

  // Caffe utility functions //这里使用def封装python中可以调用的C++函数
  bp::def("set_mode_cpu", &set_mode_cpu);
  bp::def("set_mode_gpu", &set_mode_gpu);
  bp::def("set_device", &Caffe::SetDevice);
  bp::def("set_random_seed", &Caffe::set_random_seed);

  bp::def("layer_type_list", &LayerRegistry<Dtype>::LayerTypeList);

  bp::enum_<Phase>("Phase") //这里封装枚举类型Phase
    .value("TRAIN", caffe::TRAIN)
    .value("TEST", caffe::TEST)
    .export_values();

  //封装类Net，添加了构造函数、成员函数、成员变量
  bp::class_<Net<Dtype>, shared_ptr<Net<Dtype> >, boost::noncopyable >("Net",
    bp::no_init)
    .def("__init__", bp::make_constructor(&Net_Init))
    .def("__init__", bp::make_constructor(&Net_Init_Load))
    .def("_forward", &Net<Dtype>::ForwardFromTo)
    .def("_backward", &Net<Dtype>::BackwardFromTo)
    .def("reshape", &Net<Dtype>::Reshape)
    // The cast is to select a particular overload.
    .def("copy_from", static_cast<void (Net<Dtype>::*)(const string)>(
        &Net<Dtype>::CopyTrainedLayersFrom))
    .def("share_with", &Net<Dtype>::ShareTrainedLayersWith)
    .add_property("_blob_loss_weights", bp::make_function(
        &Net<Dtype>::blob_loss_weights, bp::return_internal_reference<>()))
    .def("_bottom_ids", bp::make_function(&Net<Dtype>::bottom_ids,
        bp::return_value_policy<bp::copy_const_reference>()))
    .def("_top_ids", bp::make_function(&Net<Dtype>::top_ids,
        bp::return_value_policy<bp::copy_const_reference>()))
    .add_property("_blobs", bp::make_function(&Net<Dtype>::blobs,
        bp::return_internal_reference<>()))
    .add_property("layers", bp::make_function(&Net<Dtype>::layers,
        bp::return_internal_reference<>()))
    .add_property("_blob_names", bp::make_function(&Net<Dtype>::blob_names,
        bp::return_value_policy<bp::copy_const_reference>()))
    .add_property("_layer_names", bp::make_function(&Net<Dtype>::layer_names,
        bp::return_value_policy<bp::copy_const_reference>()))
    .add_property("_inputs", bp::make_function(&Net<Dtype>::input_blob_indices,
        bp::return_value_policy<bp::copy_const_reference>()))
    .add_property("_outputs",
        bp::make_function(&Net<Dtype>::output_blob_indices,
        bp::return_value_policy<bp::copy_const_reference>()))
    .def("_set_input_arrays", &Net_SetInputArrays,
        bp::with_custodian_and_ward<1, 2, bp::with_custodian_and_ward<1, 3> >())
    .def("save", &Net_Save);

  //封装类Blob
  bp::class_<Blob<Dtype>, shared_ptr<Blob<Dtype> >, boost::noncopyable>(
    "Blob", bp::no_init)
    .add_property("shape",
        bp::make_function(
            static_cast<const vector<int>& (Blob<Dtype>::*)() const>(
                &Blob<Dtype>::shape),
            bp::return_value_policy<bp::copy_const_reference>()))
    .add_property("num",      &Blob<Dtype>::num)
    .add_property("channels", &Blob<Dtype>::channels)
    .add_property("height",   &Blob<Dtype>::height)
    .add_property("width",    &Blob<Dtype>::width)
    .add_property("count",    static_cast<int (Blob<Dtype>::*)() const>(
        &Blob<Dtype>::count))
    .def("reshape",           bp::raw_function(&Blob_Reshape))
    .add_property("data",     bp::make_function(&Blob<Dtype>::mutable_cpu_data,
          NdarrayCallPolicies()))
    .add_property("diff",     bp::make_function(&Blob<Dtype>::mutable_cpu_diff,
          NdarrayCallPolicies()));

  //封装类：layer
  bp::class_<Layer<Dtype>, shared_ptr<PythonLayer<Dtype> >,
    boost::noncopyable>("Layer", bp::init<const LayerParameter&>())
    .add_property("blobs", bp::make_function(&Layer<Dtype>::blobs,
          bp::return_internal_reference<>()))
    .def("setup", &Layer<Dtype>::LayerSetUp)
    .def("reshape", &Layer<Dtype>::Reshape)
    .add_property("phase", bp::make_function(&Layer<Dtype>::phase))
    .add_property("type", bp::make_function(&Layer<Dtype>::type));
  bp::register_ptr_to_python<shared_ptr<Layer<Dtype> > >();

  bp::class_<LayerParameter>("LayerParameter", bp::no_init);

  //封装类solver
  bp::class_<Solver<Dtype>, shared_ptr<Solver<Dtype> >, boost::noncopyable>(
    "Solver", bp::no_init)
    .add_property("net", &Solver<Dtype>::net)
    .add_property("test_nets", bp::make_function(&Solver<Dtype>::test_nets,
          bp::return_internal_reference<>()))
    .add_property("iter", &Solver<Dtype>::iter)
    .def("solve", static_cast<void (Solver<Dtype>::*)(const char*)>(
          &Solver<Dtype>::Solve), SolveOverloads())
    .def("step", &Solver<Dtype>::Step)
    .def("restore", &Solver<Dtype>::Restore)
    .def("snapshot", &Solver<Dtype>::Snapshot);

  //封装类SGDSolver，并且该类是Solver的派生类,所以上面封装的Solver的函数和property在该类中也可以调用
  bp::class_<SGDSolver<Dtype>, bp::bases<Solver<Dtype> >,
    shared_ptr<SGDSolver<Dtype> >, boost::noncopyable>(
        "SGDSolver", bp::init<string>());
  bp::class_<NesterovSolver<Dtype>, bp::bases<Solver<Dtype> >,
    shared_ptr<NesterovSolver<Dtype> >, boost::noncopyable>(
        "NesterovSolver", bp::init<string>());
  bp::class_<AdaGradSolver<Dtype>, bp::bases<Solver<Dtype> >,
    shared_ptr<AdaGradSolver<Dtype> >, boost::noncopyable>(
        "AdaGradSolver", bp::init<string>());
  bp::class_<RMSPropSolver<Dtype>, bp::bases<Solver<Dtype> >,
    shared_ptr<RMSPropSolver<Dtype> >, boost::noncopyable>(
        "RMSPropSolver", bp::init<string>());
  bp::class_<AdaDeltaSolver<Dtype>, bp::bases<Solver<Dtype> >,
    shared_ptr<AdaDeltaSolver<Dtype> >, boost::noncopyable>(
        "AdaDeltaSolver", bp::init<string>());
  bp::class_<AdamSolver<Dtype>, bp::bases<Solver<Dtype> >,
    shared_ptr<AdamSolver<Dtype> >, boost::noncopyable>(
        "AdamSolver", bp::init<string>());

  bp::def("get_solver", &GetSolverFromFile,
      bp::return_value_policy<bp::manage_new_object>());

  //作者把用到的各种vector类型封装了
  // vector wrappers for all the vector types we use
  bp::class_<vector<shared_ptr<Blob<Dtype> > > >("BlobVec")
    .def(bp::vector_indexing_suite<vector<shared_ptr<Blob<Dtype> > >, true>())
    .def("add_blob", bp::raw_function(&BlobVec_add_blob));
  bp::class_<vector<Blob<Dtype>*> >("RawBlobVec")
    .def(bp::vector_indexing_suite<vector<Blob<Dtype>*>, true>());
  bp::class_<vector<shared_ptr<Layer<Dtype> > > >("LayerVec")
    .def(bp::vector_indexing_suite<vector<shared_ptr<Layer<Dtype> > >, true>());
  bp::class_<vector<string> >("StringVec")
    .def(bp::vector_indexing_suite<vector<string> >());
  bp::class_<vector<int> >("IntVec")
    .def(bp::vector_indexing_suite<vector<int> >());
  bp::class_<vector<Dtype> >("DtypeVec")
    .def(bp::vector_indexing_suite<vector<Dtype> >());
  bp::class_<vector<shared_ptr<Net<Dtype> > > >("NetVec")
    .def(bp::vector_indexing_suite<vector<shared_ptr<Net<Dtype> > >, true>());
  bp::class_<vector<bool> >("BoolVec")
    .def(bp::vector_indexing_suite<vector<bool> >());

  // boost python expects a void (missing) return value, while import_array
  // returns NULL for python3. import_array1() forces a void return value.
  import_array1();


  // namespace caffe