From a4a1770d1c3d54a024b5daccc7638eab86676687 Mon Sep 17 00:00:00 2001 From: Arnaud Gardelein Date: Sun, 28 Feb 2010 22:58:10 +0100 Subject: [PATCH] Documentation update: readme, hacking And correct help message for read function --- README => HACKING | 59 +++-------- README | 287 ++++++++++++++++++++++++++++++------------------------ oscopy/app.py | 4 +- 3 files changed, 172 insertions(+), 178 deletions(-) copy README => HACKING (63%) rewrite README (78%) diff --git a/README b/HACKING similarity index 63% copy from README copy to HACKING index ea697ec..936e96f 100644 --- a/README +++ b/HACKING @@ -1,44 +1,7 @@ -oscopy -- An interactive program to view electrical results - -This is oscopy, a kind of oscilloscope in python, to view 2D electrical -simulation or measurement results. -It is designed to easily add new input data file formats and new types of plots. - -Features highlight: - * Post-processing: math expressions, fft, diffs - * View, examine: multiple windows, cursors - * Data import: gnucap - * Data export: gnucap, pictures - * Scripting - -Dependencies: - * Python - * Numpy - * Matplotlib - -To run the program, just do ./oscopy. - -To get any info on available commands, type 'help'. - -EXAMPLE: -------- -cd demo -gnetlist -g spice-sdb -s -o demo.net demo.sch -gnucap -b demo.net -cd .. -./oscopy -b demo/demo.oscopy - -MATH WITH SIGNALS: ------------------- -Support for mathematic with signals is implemented. Supported functions: -trig, sqrt, log... -Support for (i)fft: fft(v1) + fft(v2) is possible, but please avoid -things like ifft(fft(v1) + fft(v2)) -First order diff is supported: diff(v1) or diff(v1, 1) -Access to X axis data is provided through Time and Freq, e.g. sin(Time(vsqu)*1e6) - EXTENDING OSCOPY: ----------------- +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... + New data file format can be added by deriving Reader and redefining the function readsigs(), which fills the list of signals self.sigs and return a dict of signals. @@ -116,13 +79,13 @@ class xxxGraph(Graphs.Graph.Graph): A SCHEME: --------- - READER -- SIGNAL+ + FIGURE +-- GRAPH +-- SIGNAL - \- SIGNAL+ | | +-- SIGNAL - READER -- SIGNAL+ | | - | | +-- GRAPH +-- SIGNAL - | | +-- SIGNAL - | + FIGURE ... - | ... - | | - +- CMDS -+ + READER -- SIGNAL+ + FIGURE +-- GRAPH +-- SIGNAL + \- SIGNAL+ | | +-- SIGNAL + READER -- SIGNAL+ | | + | | +-- GRAPH +-- SIGNAL + | | +-- SIGNAL + | + FIGURE ... + | ... + | | + +- CONTEXT -+ diff --git a/README b/README dissimilarity index 78% index ea697ec..17adcfd 100644 --- a/README +++ b/README @@ -1,128 +1,159 @@ -oscopy -- An interactive program to view electrical results - -This is oscopy, a kind of oscilloscope in python, to view 2D electrical -simulation or measurement results. -It is designed to easily add new input data file formats and new types of plots. - -Features highlight: - * Post-processing: math expressions, fft, diffs - * View, examine: multiple windows, cursors - * Data import: gnucap - * Data export: gnucap, pictures - * Scripting - -Dependencies: - * Python - * Numpy - * Matplotlib - -To run the program, just do ./oscopy. - -To get any info on available commands, type 'help'. - -EXAMPLE: -------- -cd demo -gnetlist -g spice-sdb -s -o demo.net demo.sch -gnucap -b demo.net -cd .. -./oscopy -b demo/demo.oscopy - -MATH WITH SIGNALS: ------------------- -Support for mathematic with signals is implemented. Supported functions: -trig, sqrt, log... -Support for (i)fft: fft(v1) + fft(v2) is possible, but please avoid -things like ifft(fft(v1) + fft(v2)) -First order diff is supported: diff(v1) or diff(v1, 1) -Access to X axis data is provided through Time and Freq, e.g. sin(Time(vsqu)*1e6) - -EXTENDING OSCOPY: ------------------ -New data file format can be added by deriving Reader and -redefining the function readsigs(), which fills the list -of signals self.sigs and return a dict of signals. -During execution, Reader.read() check the validity -of the provided path, and then call readsigs(). - -New graph mode can be added by deriving Graph and redefining -the function set_axes() which if called by plot(), or eventually -redefining plot(). See FFTGraph.py for example. -NOTE : Figure.set_mode() has to be updated when new mode are added ! - -Vocabular: -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. - -Template for new import format: ---- -import Signal -import Readers - -class xxxReader(Readers.Reader.Reader): - def readsigs(self): - #[...] read the signals data from file and for each signal: - #create signal: - # Reference signal, or X axis - sref = Signal("name_ref", self, "unit_ref") - sref.set_pts([with X data from file as a list or numpy.array]) - # Signal, or Y axis - s = Signal("name_sig", self, "unit_sig") - s.set_pts([with data from file as a list or numpy.array]) - # Assign reference to signal - s.set_ref(sref) - #fill self.slist - self.slist.append(s) - sigs["name_ref"] = s - #and return a dict of sigs where key is signal name - return sigs - - def detect(self, fn): - # return True if file fn can be read using this Reader ---- -When a importing a signal, first detect is called. -If format is supported, read() and subsequent update() will call readsigs() - -Template for new export format: ---- -import Signal -import Writers - -class xxxWriter(Writers.Writer.Writer): - def getfmtname(self): - ... return a string containing the name of the format - - def fmtcheck(self, sigs): - ... return True if format can be use to write dict of signals sigs - - def writesigs(self, sigs) - ... write signals to file ---- -When an export command is issued, the format name is compared to the -one provided by the class, and then the signals are passed to the class -to check whether it can write them properly, e.g. if they have the same -abscisse. If eveyrthing is fine, writesigs() is called. -Options passed by user can be found in self.opts. - -Template for new graphs: ---- -import Graphs -import Signal - -class xxxGraph(Graphs.Graph.Graph): - def plot(): - ... define the plot function, using signals in self.sigs ---- - -A SCHEME: ---------- - - READER -- SIGNAL+ + FIGURE +-- GRAPH +-- SIGNAL - \- SIGNAL+ | | +-- SIGNAL - READER -- SIGNAL+ | | - | | +-- GRAPH +-- SIGNAL - | | +-- SIGNAL - | + FIGURE ... - | ... - | | - +- CMDS -+ - +oscopy -- An interactive program to view electrical results + +ABOUT OSCOPY +------------ +This is oscopy, a kind of oscilloscope in python, to view 2D electrical +simulation or measurement results. +It is designed to easily add new input data file formats and new types of plots. +Features highlight: + * Post-processing: math expressions, fft, diffs + * View, examine: multiple windows, cursors + * Data import: gnucap + * Data export: gnucap, pictures + * Scripting + * D-Bus support: update recursively signals + * Run netlister and simulator + +There are two applications: + * oscopy_app.py: command-line interface (CLI) + * oscopy_ui.py: graphical user interface (GUI) fully integrating the CLI. +Scripting is supported in both application, although in the GUI some commands are disabled since plots are displayed dynamically. + +Support for mathematic with signals is implemented. Supported functions: +trig, sqrt, log... +Support for (i)fft: fft(v1) + fft(v2) is possible, but please avoid things like ifft(fft(v1) + fft(v2)) +First order diff is supported: diff(v1) or diff(v1, 1) +Access to X axis data is provided through Time and Freq, e.g. sin(Time(vsqu)*1e6) + +GETTING THE SOURCE +------------------ +The source can be downloaded from repo.cz: +http://repo.or.cz/w/oscopy.git + +To download it: +$ git clone git://repo.or.cz/oscopy.git + +BUILDING FROM SOURCE +-------------------- +Oscopy can work out of the box when downloaded, but it supports also installing on the system using autotools. +In the latter case: +$ ./configure && make + +Dependencies: + * python + * python-numpy + * python-matplotlib +If you want to use the dbus capabilities: + * python-dbus + * glib + * dbus-glib + +INSTALLING +---------- +If you want to install oscopy on a system: +# ./configure && make install + +QUICKSTART +---------- +To run the program, just do ./oscopy_app or ./oscopy_ui. + +To get any info on available commands, type 'help'. + +A sample circuit is provided for demonstration purposes. +From oscopy directory, prepare the demo circuit files +$ cd demo +$ gnetlist -g spice-sdb -s -o demo.net demo.sch +$ gnucap -b demo.net +$ cd .. + +Using the CLI: +$ ./oscopy_app.py -b demo/demo.oscopy + +Using the GUI: +$ ./oscopy_ui.py & +then in the terminal window: +oscopy> exec demo/demo.oscopy + +COMMAND REFERENCE +----------------- +add SIG [, SIG [, SIG]...] + Add a graph to the current figure + +create [SIG [, SIG [, SIG]...]] + Create a new figure, set_ it as current, add the signals + +delete GRAPH# + Delete a graph from the current figure + +destroy FIG# + Destroy a figure + +echo [TEXT] + Print text + +exec FILENAME + execute commands from file + +factors X, Y + set the scaling factor of the graph (in power of ten) + use 'auto' for automatic scaling factor + e.g. factor -3, 6 set the scale factor at 1e-3 and 10e6 + +figlist + Print the list of figures + +freeze SIG [, SIG [, SIG]...] + Do not consider signal for subsequent updates + +insert SIG [, SIG [, SIG]...] + Insert a list of signals into the current graph + +layout horiz|vert|quad + Define the layout of the current figure + +math destsig=mathexpr + Define a new signal destsig using mathematical expression + destsig=mathexpr is also valid. + +mode MODE + Set the type of the current graph of the current figure + Available modes : + lin Linear graph + +pause + Wait for the user to press enter + +plot + Draw and show the figures (disabled in the GUI) + +range [x|y min max]|[xmin xmax ymin ymax]|[reset] + Set the axis range of the current graph of the current figure + +read DATAFILE + read signal file + +remove SIG [, SIG [, SIG]...] + Delete a list of signals into from current graph + +scale [lin|logx|logy|loglog] + Set the axis scale + +select FIG#-GRAPH# + Select the current figure and the current graph + +siglist + List loaded signals + +unfreeze SIG [, SIG [, SIG]...] + Consider signal for subsequent updates + +unit [XUNIT,] YUNIT + Set the unit to be displayed on graph axis + +update + Reread data files + +write format [(OPTIONS)] FILE SIG [, SIG [, SIG]...] + Write signals to file + + diff --git a/oscopy/app.py b/oscopy/app.py index be5e3ed..02fc520 100644 --- a/oscopy/app.py +++ b/oscopy/app.py @@ -158,8 +158,8 @@ FITNESS FOR A PARTICULAR PURPOSE." return False def help_read(self): - print "load DATAFILE" - print " Load signal file" + print "read DATAFILE" + print " Read signal file" def do_read(self, args): fn = args if fn in self._ctxt.readers.keys(): -- 2.11.4.GIT