From 95c5e95930f20eb77928d15577d744c1d8d27f57 Mon Sep 17 00:00:00 2001
From: Davis King <davis@dlib.net>
Date: Sun, 21 Aug 2016 21:03:16 -0400
Subject: [PATCH] Added annotation() to tensor so that you can associate any
 object you want with a tensor.

---
 dlib/dnn/tensor.h          | 20 +++++++++++++++++---
 dlib/dnn/tensor_abstract.h | 23 +++++++++++++++++++++++
 2 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/dlib/dnn/tensor.h b/dlib/dnn/tensor.h
index 4f37c5582..261613a7c 100644
--- a/dlib/dnn/tensor.h
+++ b/dlib/dnn/tensor.h
@@ -10,6 +10,7 @@
 #include "gpu_data.h"
 #include "../byte_orderer.h"
 #include <memory>
+#include "../any.h"
 
 namespace dlib
 {
@@ -52,6 +53,9 @@ namespace dlib
         virtual float*       device() = 0;
         virtual float*       device_write_only() = 0;
 
+        virtual const any&   annotation() const = 0;
+        virtual any&         annotation() = 0;
+
         int device_id() const { return data().device_id(); }
 
         tensor& operator= (float val)
@@ -283,13 +287,13 @@ namespace dlib
             set_size(n_,k_,nr_,nc_);
         }
 
-        resizable_tensor(const resizable_tensor& item) 
+        resizable_tensor(const resizable_tensor& item) : _annotation(item.annotation()) 
         {
             // TODO, do the copy with cuda?
             copy_size(item);
             std::memcpy(data_instance.host(), item.host(), data_instance.size()*sizeof(float));
         }
-        resizable_tensor(const tensor& item) 
+        resizable_tensor(const tensor& item) : _annotation(item.annotation()) 
         {
             // TODO, do the copy with cuda?
             copy_size(item);
@@ -306,10 +310,14 @@ namespace dlib
         virtual float*       device()       { return data_instance.device(); }
         virtual float*       device_write_only() { return data_instance.device_write_only(); }
 
+        virtual const any&   annotation() const { return _annotation; }
+        virtual any&         annotation() { return _annotation; }
+
         void clear(
         )
         {
             set_size(0,0,0,0);
+            _annotation.clear();
         }
 
         void copy_size (
@@ -377,6 +385,7 @@ namespace dlib
             std::swap(m_nc,   item.m_nc);
             std::swap(m_size, item.m_size);
             std::swap(data_instance, item.data_instance);
+            std::swap(_annotation, item._annotation);
 #ifdef DLIB_USE_CUDA
             std::swap(cudnn_descriptor, item.cudnn_descriptor);
 #endif
@@ -394,6 +403,7 @@ namespace dlib
 #endif 
 
         gpu_data data_instance;
+        any _annotation;
         virtual gpu_data& data() { return data_instance; }
         virtual const gpu_data& data() const { return data_instance; }
     };
@@ -470,7 +480,7 @@ namespace dlib
     class alias_tensor_instance : public tensor
     {
         alias_tensor_instance(
-        ) : data_instance(0), data_offset(0) {}
+        ) : data_instance(0), _annotation(0), data_offset(0) {}
 
     public:
         friend class alias_tensor;
@@ -495,6 +505,8 @@ namespace dlib
         virtual float*       device()       { return data_instance->device()+data_offset; }
         virtual float*       device_write_only()  { return data_instance->device()+data_offset; }
 
+        virtual const any&   annotation() const { return *_annotation; }
+        virtual any&         annotation() { return *_annotation; }
 
 #ifdef DLIB_USE_CUDA
         virtual const cuda::tensor_descriptor& get_cudnn_tensor_descriptor (
@@ -508,6 +520,7 @@ namespace dlib
         std::shared_ptr<cuda::tensor_descriptor> cudnn_descriptor;
 #endif
         gpu_data* data_instance;
+        any* _annotation;
         size_t data_offset;
         virtual gpu_data& data() { return *data_instance; }
         virtual const gpu_data& data() const { return *data_instance; }
@@ -563,6 +576,7 @@ namespace dlib
             }
 #endif
             inst.data_instance = &t.data();
+            inst._annotation   = &t.annotation();
             // Note that t might already be an aliasing tensor so we need to take that into
             // account.
             inst.data_offset = t.get_alias_offset()+offset;
diff --git a/dlib/dnn/tensor_abstract.h b/dlib/dnn/tensor_abstract.h
index 520d6a876..0f9f15a49 100644
--- a/dlib/dnn/tensor_abstract.h
+++ b/dlib/dnn/tensor_abstract.h
@@ -4,6 +4,7 @@
 #ifdef DLIB_DNn_TENSOR_ABSTRACT_H_
 
 #include "../matrix.h"
+#include "../any/any_abstract.h"
 
 namespace dlib
 {
@@ -187,6 +188,26 @@ namespace dlib
                   every memory location in the returned memory block.  
         !*/
 
+        virtual const any& annotation(
+        ) const = 0;
+        /*!
+            ensures
+                - returns a const reference to the any object in this tensor.  The any
+                  object can be used to store any additional annotation you like in a
+                  tensor.  However, it should be noted that the annotation() is ignored by
+                  serialize() and therefore not saved when a tensor is serialized.
+        !*/
+
+        virtual any& annotation(
+        ) = 0;
+        /*!
+            ensures
+                - returns a non-const reference to the any object in this tensor.  The any
+                  object can be used to store any additional annotation you like in a
+                  tensor.  However, it should be noted that the annotation() is ignored by
+                  serialize() and therefore not saved when a tensor is serialized.
+        !*/
+
         int device_id(
         ) const; 
         /*!
@@ -461,6 +482,7 @@ namespace dlib
                 - #k() == 0
                 - #nr() == 0
                 - #nc() == 0
+                - #annotation().is_empty() == true
         !*/
 
         void copy_size (
@@ -617,6 +639,7 @@ namespace dlib
                     - T.nc()     == nc()
                     - T.host()   == t.host()+offset
                     - T.device() == t.device()+offset
+                    - &T.annotation() == &t.annotation()
         !*/
     };