Added more comments

tools/convert_dlib_nets_to_caffe/main.cpp

@@ -114,6 +114,10 @@ void convert_dlib_xml_to_cafffe_python_code(
     fout.precision(9);
     const auto layers = parse_dlib_xml(xml_filename);
 
+    fout << "#\n";
+    fout << "# !!! This file was automatically generated by dlib's tools/convert_dlib_nets_to_caffe utility.     !!!\n";
+    fout << "# !!! It contains all the information from a dlib DNN network and lets you save it as a cafe model. !!!\n";
+    fout << "#\n";
     fout << "import caffe " << endl;
     fout << "from caffe import layers as L, params as P" << endl;
     fout << "import numpy as np" << endl;
@@ -123,8 +127,8 @@ void convert_dlib_xml_to_cafffe_python_code(
     fout << "batch_size = 1;" << endl;
     if (layers.back().detail_name == "input_rgb_image")
     {
-        fout << "input_nr = 28; #WARNING, the source dlib network didn't commit to a specific input size, so we put 28 here as a default." << endl;
-        fout << "input_nc = 28; #WARNING, the source dlib network didn't commit to a specific input size, so we put 28 here as a default." << endl;
+        fout << "input_nr = 28; #WARNING, the source dlib network didn't commit to a specific input size, so we put 28 here as a default.  It might not be the right value." << endl;
+        fout << "input_nc = 28; #WARNING, the source dlib network didn't commit to a specific input size, so we put 28 here as a default.  It might not be the right value." << endl;
         fout << "input_k = 3;" << endl;
     }
     else if (layers.back().detail_name == "input_rgb_image_sized")
@@ -135,8 +139,8 @@ void convert_dlib_xml_to_cafffe_python_code(
     }
     else if (layers.back().detail_name == "input")
     {
-        fout << "input_nr = 28; #WARNING, the source dlib network didn't commit to a specific input size, so we put 28 here as a default." << endl;
-        fout << "input_nc = 28; #WARNING, the source dlib network didn't commit to a specific input size, so we put 28 here as a default." << endl;
+        fout << "input_nr = 28; #WARNING, the source dlib network didn't commit to a specific input size, so we put 28 here as a default.  It might not be the right value." << endl;
+        fout << "input_nc = 28; #WARNING, the source dlib network didn't commit to a specific input size, so we put 28 here as a default.  It might not be the right value." << endl;
         fout << "input_k = 1;" << endl;
     }
     else
@@ -144,6 +148,24 @@ void convert_dlib_xml_to_cafffe_python_code(
         throw dlib::error("No known transformation from dlib's " + layers.back().detail_name + " layer to caffe.");
     }
     fout << endl;
+    fout << "# Call this function to write the dlib DNN model out to file as a pair of caffe\n";
+    fout << "# definition and weight files.  You can then use the network by loading it with\n";
+    fout << "# this statement: \n";
+    fout << "#    net = caffe.Net(def_file, weights_file, caffe.TEST);\n";
+    fout << "#\n";
+    fout << "def save_as_caffe_model(def_file, weights_file):\n";
+    fout << "    with open(def_file, 'w') as f: f.write(str(make_netspec()));\n";
+    fout << "    net = caffe.Net(def_file, caffe.TEST);\n";
+    fout << "    set_network_weights(net);\n";
+    fout << "    net.save(weights_file);\n\n";
+    fout << "###############################################################################\n";
+    fout << "#         EVERYTHING BELOW HERE DEFINES THE DLIB MODEL PARAMETERS             #\n";
+    fout << "###############################################################################\n\n\n";
+
+
+    // -----------------------------------------------------------------------------------
+    //  The next block of code outputs python code that defines the network architecture. 
+    // -----------------------------------------------------------------------------------
 
     fout << "def make_netspec():" << endl;
     fout << "    # For reference, the only \"documentation\" about caffe layer parameters seems to be this page:\n";
@@ -283,18 +305,6 @@ void convert_dlib_xml_to_cafffe_python_code(
     fout << "    return n.to_proto();\n\n" << endl;
 
 
-    // -------------------------
-    // -------------------------
-
-
-    fout << "def save_as_caffe_model(def_file, weights_file):\n";
-    fout << "    with open(def_file, 'w') as f: f.write(str(make_netspec()));\n";
-    fout << "    net = caffe.Net(def_file, caffe.TEST);\n";
-    fout << "    set_network_weights(net);\n";
-    fout << "    net.save(weights_file);\n\n";
-
-
-
     // -----------------------------------------------------------------------------------
     //  The next block of code outputs python code that populates all the filter weights.
     // -----------------------------------------------------------------------------------