HACKING

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