HACKING

   1 EXTENDING OSCOPY:
   2 -----------------
   3 Oscopy is designed to be easily extendable. Support of new data file formats is done by adding new Readers/Writers, new types of Graph and Figures by deriving Graph and Figure...
   4
   5 New data file format can be added by deriving Reader and
   6 redefining the function readsigs(), which fills the list
   7 of signals self.sigs and return a dict of signals.
   8 During execution, Reader.read() check the validity
   9 of the provided path, and then call readsigs().
  10
  11 New graph mode can be added by deriving Graph and redefining
  12 the function set_axes() which if called by plot(), or eventually
  13 redefining plot(). See FFTGraph.py for example.
  14 NOTE : Figure.set_mode() has to be updated when new mode are added !
  15
  16 Vocabular:
  17 A figure is CREATEd or DESTROYed, a graph is ADDed to a figure or DELETEd and a signal is INSERTed or REMOVEd from a graph.
  18
  19 Template for new import format:
  20 ---
  21 import Signal
  22 import Readers
  23
  24 class xxxReader(Readers.Reader.Reader):
  25       def readsigs(self):
  26           #[...] read the signals data from file and for each signal:
  27               #create signal:
  28               # Reference signal, or X axis
  29               sref = Signal("name_ref", self, "unit_ref")
  30               sref.set_pts([with X data from file as a list or numpy.array])
  31               # Signal, or Y axis
  32               s = Signal("name_sig", self, "unit_sig")
  33               s.set_pts([with data from file as a list or numpy.array])
  34               # Assign reference to signal
  35               s.set_ref(sref)
  36           #fill self.slist
  37               self.slist.append(s)
  38               sigs["name_ref"] = s
  39           #and return a dict of sigs where key is signal name
  40           return sigs
  41
  42       def detect(self, fn):
  43           # return True if file fn can be read using this Reader
  44 ---
  45 When a importing a signal, first detect is called.
  46 If format is supported, read() and subsequent update() will call readsigs()
  47
  48 Template for new export format:
  49 ---
  50 import Signal
  51 import Writers
  52
  53 class xxxWriter(Writers.Writer.Writer):
  54       def getfmtname(self):
  55       ... return a string containing the name of the format
  56
  57       def fmtcheck(self, sigs):
  58       ... return True if format can be use to write dict of signals sigs
  59
  60       def writesigs(self, sigs)
  61       ... write signals to file
  62 ---
  63 When an export command is issued, the format name is compared to the
  64 one provided by the class, and then the signals are passed to the class
  65 to check whether it can write them properly, e.g. if they have the same
  66 abscisse. If eveyrthing is fine, writesigs() is called.
  67 Options passed by user can be found in self.opts.
  68
  69 Template for new graphs:
  70 ---
  71 import Graphs
  72 import Signal
  73
  74 class xxxGraph(Graphs.Graph.Graph):
  75       def plot():
  76       ... define the plot function, using signals in self.sigs
  77 ---
  78
  79 A SCHEME:
  80 ---------
  81
  82    READER -- SIGNAL+           + FIGURE +-- GRAPH +-- SIGNAL
  83           \- SIGNAL+           |        |         +-- SIGNAL
  84    READER -- SIGNAL+           |        |
  85                    |           |        +-- GRAPH +-- SIGNAL
  86                    |           |                  +-- SIGNAL
  87                    |           + FIGURE ...
  88                    |           ...
  89                    |           |
  90                    +- CONTEXT -+
  91