degate  0.1.2
Annotation.h
Go to the documentation of this file.
00001 /* -*-c++-*-
00002 
00003  This file is part of the IC reverse engineering tool degate.
00004 
00005  Copyright 2008, 2009, 2010 by Martin Schobert
00006  Copyright 2012 Robert Nitsch
00007 
00008  Degate is free software: you can redistribute it and/or modify
00009  it under the terms of the GNU General Public License as published by
00010  the Free Software Foundation, either version 3 of the License, or
00011  any later version.
00012 
00013  Degate is distributed in the hope that it will be useful,
00014  but WITHOUT ANY WARRANTY; without even the implied warranty of
00015  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00016  GNU General Public License for more details.
00017 
00018  You should have received a copy of the GNU General Public License
00019  along with degate. If not, see <http://www.gnu.org/licenses/>.
00020 
00021 */
00022 
00023 #ifndef __ANNOTATION_H__
00024 #define __ANNOTATION_H__
00025 
00026 #include "globals.h"
00027 #include "LogicModelObjectBase.h"
00028 #include "Layer.h"
00029 #include "PlacedLogicModelObject.h"
00030 
00031 #include "Rectangle.h"
00032 
00033 #include <set>
00034 #include <boost/lexical_cast.hpp>
00035 #include <boost/filesystem.hpp>
00036 
00037 namespace degate {
00038 
00039   /**
00040    * An annotation is a descriptive meta object that can be
00041    * placed on a logic model's layer to mark a region of interest.
00042    *
00043    * The semantics of an annotation is user defined. The libdegate
00044    * does not establish a relationship from an annotaion to another
00045    * logic model object or to an background image region.
00046    *
00047    * Each annotation should have a class ID. This might be used
00048    * to classify the kind of annotation. For example you can place
00049    * an annotation 'above' a distored part of the background image to
00050    * remember yourself, that this image part should be rephotographed.
00051    * An image recognition algorithm may auto-annotate, that it is unsure
00052    * e.g. if there is a via or not due to fuzzy thresholds.
00053    *
00054    * You can set a name and a description for the annotation as well.
00055    *
00056    * This class is designed to be derived for concrete annotations.
00057    *
00058    * @see set_name()
00059    * @see set_description()
00060    */
00061 
00062   class Annotation : public Rectangle, public PlacedLogicModelObject {
00063 
00064   public:
00065 
00066     typedef unsigned int class_id_t;
00067 
00068     /**
00069      * Enums to declare the type of annotation.
00070      */
00071 
00072     enum ANNOTATION_TYPE {
00073       UNDEFINED = 0,
00074       SUBPROJECT = 1
00075     };
00076 
00077     typedef std::map<std::string, /* param name */
00078                      std::string  /* param value */ > parameter_set_type;
00079 
00080   private:
00081 
00082     class_id_t class_id;
00083     parameter_set_type parameters;
00084 
00085   protected:
00086 
00087 
00088     /**
00089      * Set a parameter.
00090      */
00091 
00092     void set_parameter(std::string const& parameter_name,
00093                        std::string const& parameter_value) {
00094       parameters[parameter_name] = parameter_value;
00095     }
00096 
00097   public:
00098 
00099     explicit Annotation() {};
00100 
00101     /**
00102      * Create a new annotation.
00103      */
00104 
00105     Annotation(int _min_x, int _max_x, int _min_y, int _max_y,
00106                class_id_t _class_id = UNDEFINED);
00107 
00108     /**
00109      * Create a new annotation.
00110      */
00111 
00112     Annotation(BoundingBox const& bbox,
00113                class_id_t _class_id = UNDEFINED);
00114 
00115 
00116     /**
00117      * The destructor for an annotaion.
00118      */
00119 
00120     virtual ~Annotation();
00121 
00122     //@{
00123     DeepCopyable_shptr cloneShallow() const;
00124     void cloneDeepInto(DeepCopyable_shptr destination, oldnew_t *oldnew) const;
00125     //@}
00126     
00127     /**
00128      * Get the class ID for an annotation.
00129      */
00130 
00131     virtual class_id_t get_class_id() const;
00132 
00133     /**
00134      * Set the class ID for an annotation.
00135      */
00136 
00137     virtual void set_class_id(class_id_t _class_id);
00138 
00139     /**
00140      * Get a human readable string that describes the whole
00141      * logic model object. The string should be unique in order
00142      * to let the user identify the concrete object. But that
00143      * is not a must.
00144      */
00145 
00146     virtual const std::string get_descriptive_identifier() const;
00147 
00148     /**
00149      * Get a human readable string that names the object type.
00150      * Here it is "Annotation".
00151      */
00152 
00153     virtual const std::string get_object_type_name() const;
00154 
00155     /**
00156      * Print annotation.
00157      */
00158     void print(std::ostream & os = std::cout, int n_tabs = 0) const;
00159 
00160 
00161 
00162     void shift_x(int delta_x) {
00163       Rectangle::shift_x(delta_x);
00164       notify_shape_change();
00165     }
00166 
00167     void shift_y(int delta_y) {
00168       Rectangle::shift_y(delta_y);
00169       notify_shape_change();
00170     }
00171 
00172     virtual bool in_bounding_box(BoundingBox const& bbox) const {
00173       return in_bounding_box(bbox);
00174     }
00175 
00176     virtual BoundingBox const& get_bounding_box() const {
00177       return Rectangle::get_bounding_box();
00178     }
00179 
00180     virtual bool in_shape(int x, int y, int max_distance = 0) const {
00181       return Rectangle::in_shape(x, y, max_distance);
00182     }
00183 
00184 
00185     /**
00186      * Get a parameter value.
00187      *
00188      * @exception boost::bad_lexical_cast This exception is thrown if the parameter value
00189      *   cannot be converted to the desired type.
00190      * @exception CollectionLookupException This exception is thrown if the parameter is
00191      *   not stored in the lookup table.
00192      */
00193 
00194     template<typename NewType>
00195     NewType get_parameter(std::string parameter_name) const {
00196 
00197       parameter_set_type::const_iterator iter = parameters.find(parameter_name);
00198       if(iter == parameters.end()) {
00199         boost::format f("Failed to lookup parameter %1%.");
00200         f % parameter_name;
00201         throw CollectionLookupException(f.str());
00202       }
00203 
00204       if(typeid(NewType) == typeid(std::string) ||
00205          typeid(NewType) == typeid(boost::filesystem::path)) {
00206 
00207         return NewType(iter->second);
00208       }
00209 
00210       try {
00211         return boost::lexical_cast<NewType>(iter->second);
00212       }
00213       catch(boost::bad_lexical_cast &) {
00214         debug(TM, "Failed to convert value string '%s'.", iter->second.c_str());
00215         throw;
00216       }
00217     }
00218 
00219     /**
00220      * Get an iterator to iterate over parameters.
00221      */
00222     parameter_set_type::const_iterator parameters_begin() const;
00223 
00224     /**
00225      * Get an end marker for the parameter iteration.
00226      */
00227     parameter_set_type::const_iterator parameters_end() const;
00228   };
00229 
00230 }
00231 #endif