ObitDisplay.h File Reference

ObitDisplay Image Display class. More...

#include "Obit.h"
#include "ObitErr.h"
#include "ObitRPC.h"
#include "ObitDConCleanWindow.h"

Go to the source code of this file.

Classes
struct	ObitDisplay
	ObitDisplay Class structure. More...
struct	ObitDisplayClassInfo
	ClassInfo Structure. More...
Defines
#define	ObitDisplayUnref(in)   ObitUnref (in)
	Macro to unreference (and possibly destroy) an ObitDisplay returns a ObitDisplay*.
#define	ObitDisplayRef(in)   ObitRef (in)
	Macro to reference (update reference count) an ObitDisplay.
#define	ObitDisplayIsA(in)   ObitIsA (in, ObitDisplayGetClass())
	Macro to determine if an object is the member of this or a derived class.
Typedefs
typedef ObitDisplay *(*	ObitDisplayCreateFP )(gchar *name, gchar *ServerURL, ObitErr *err)
	Typedef for definition of class pointer structure.
typedef gboolean(*	ObitDisplayShowFP )(ObitDisplay *display, Obit *image, ObitDConCleanWindow *window, gint field, ObitErr *err)
	Typedef for definition of class pointer structure.
typedef void(*	ObitDisplayTurnOnFP )(ObitDisplay *display)
	Typedef for definition of class pointer structure.
typedef void(*	ObitDisplayTurnOffFP )(ObitDisplay *display)
	Typedef for definition of class pointer structure.
Enumerations
enum	obitDisplayRequest {   OBIT_Request_Continue = 0, OBIT_Request_Abort, OBIT_Request_Quit, OBIT_Request_NoTV,   OBIT_Request_View, OBIT_Request_Edit }
	enum Display request coads (MUST be synchronized with server usage which is defined in ObitRPC.h #ObitRPCRequestType) This specifies the request More...
Functions
void	ObitDisplayClassInit (void)
	Public: Class initializer.
ObitDisplay *	newObitDisplay (gchar *name)
	Public: Default Constructor.
ObitDisplay *	ObitDisplayCreate (gchar *name, gchar *ServerURL, ObitErr *err)
	Public: Create/initialize ObitDisplay structures.
gconstpointer	ObitDisplayGetClass (void)
	Public: ClassInfo pointer.
gboolean	ObitDisplayShow (ObitDisplay *display, Obit *image, ObitDConCleanWindow *window, gint field, ObitErr *err)
	Public: Send Display and Window edit request.
void	ObitDisplayTurnOn (ObitDisplay *display)
	Public: Turn display on.
void	ObitDisplayTurnOff (ObitDisplay *display)
	Public: Turn display off.

---

Detailed Description

ObitDisplay Image Display class.

This class is derived from the Obit class.

This class communicates with the Image Display server The implementation is based on ObitView, only one allowed and return

Display Interface

The ObitDisplay class is the client interface between applications software and the image display server which runs asynchronously, perhaps on another computer. The server is specified by a URL in the ObitDisplayCreate call and an example of a local server running on port 8765 is "http://localhost:8765/RPC2" The actual communications uses the ObitRPC class which communicates using internet (http) protocols and xml to package the information communicated. The actual communication is through ObitRPCCall. In Obit, xml is encapsulated in the ObitXML class. In ObitView the server is managed in XMLRPCserver.

The communication model is the client/server model where the client makes a call with a single (xml) argument and the server performs its service and returns a single (xml) reply. (Since xml is very flexible the requirement of a single argument and reply is not a limitation). In this model, the interaction between client and server is stateless, i.e., makes no assumption about any previous or future interactions, although both the client and do have state. In this implementation, the response from the server may include a request for a further action by the client. Examples of this are to display and/or edit the CLEAN window for another field of a mosaic or to abort the program.

The returned xml from the server contains up to three components:

• Result This will be the ObitXML returned by the ObitRPCCall and depends on the Call type. There is an ObitXML function to translate this to the call-specific useful form.
• Status This is returned as an ObitInfoList by ObitRPCCall and gives the status (success or failure) of the call. See below for details.
• Request [optional] The request section, if present, is returned as an ObitInfoList by ObitRPCCall . This describes a request by the server (generally user input) for an action by the client and is described further below.

Returned

The status argument returned by ObitRPCCall is an ObitInfoList translation of Status portion of the server response. There will be two entries:

• code (gint) which is a return code, 0=OK everything else indicates an error
• reason (gchar*) which is a reason for the code. "OK" is given for success, "Busy" if the server is still processing another request (code=1). Other values may also appear.

Returned

The request argument returned by ObitRPCCall is an ObitInfoList translation of Request portion of the server response. This is a copy of an ObitInfoList generated by the server and the details depend on the exact request. The Request code is the "Request" entry (gint) in the ObitInfoList(#ObitDisplayRequest enum defined for convienence) and the following values are defined:

• 0 (OBIT_Request_Continue) Continue program (no request for action) ,
• 1 (OBIT_Request_Abort) Abort program, current results are assumed of no value
• 2 (OBIT_Request_Quit) Quit, graceful shutdown with current results saved
• 3 (OBIT_Request_Edit) Edit, send window for editing, must match current image
• 4 (OBIT_Request_View) View, send another field in the same ObitImageMosaic and possibly corresponding window to edit. This request will also include member "Field" (gint) which is the 1-rel field number requested.

Functions

The display server currently supported is ObitView which has the following callable functions:

• ping Simple function to test communications.
• loadFITS (not used here) Sends the name of a FITS image to display. Name should be the full path as seen from the server and may be an internet URL.
• loadImage Load any image type accessable by Obit in the server
• editWindow Passed an ObitDConCleanWindow for a single image, the server overlays it on the image and allows interactive editing, returning the edited window structure.

call arguments and return

The argument passed to the ping call is generated by ObitXMLPing2XML although no actual information is passed to the server (a random integer is used). The return value is a string containing the name of the server (e.g. "ObitView"). The Status return value from ObitRPCCall gives the availability of the server (may be "busy"). If there was a communications failure (e.g. no server or network connection or bad xml) then an error will be entered on err.

call arguments and return

This call is not used by Obit. The argument is a single string giving the full path or URL of a FITS image to load.

call arguments and return

This call is used to display an image accessable by Obit running in the server. The argument is generated by ObitXMLFileInfo2XML which takes a description of the file as seen by the server. Note: the FITS path may be an internet URL but only local AIPS images are accessable. The return value is a string of either "Loaded File" or "Load failed" but the succes of the function is better determined from the Status return.

call arguments and return

This call sends the ObitDConCleanWindow (one field only) corresponding to the previous loadImage call and allows the user to interactively edit the window. The call argument to ObitRPCCall is generated by ObitXMLWindow2XML and the return value converted into a (single field) ObitDConCleanWindow by ObitXMLXML2Window. The return from this call may include a Request for a further action.

Creators and Destructors

An ObitDisplay will usually be created using ObitDisplayCreate which allows specifying a name for the object as well as other information.

A copy of a pointer to an ObitDisplay should always be made using the ObitDisplayRef function which updates the reference count in the object. Then whenever freeing an ObitDisplay or changing a pointer, the function ObitDisplayUnref will decrement the reference count and destroy the object when the reference count hits 0. There is no explicit destructor.

---

Define Documentation

#define ObitDisplayIsA (  in   )     ObitIsA (in, ObitDisplayGetClass())

Macro to determine if an object is the member of this or a derived class. Returns TRUE if a member, else FALSE in = object to reference

#define ObitDisplayRef (  in   )     ObitRef (in)

Macro to reference (update reference count) an ObitDisplay. returns a ObitDisplay*. in = object to reference

#define ObitDisplayUnref (  in   )     ObitUnref (in)

Macro to unreference (and possibly destroy) an ObitDisplay returns a ObitDisplay*. in = object to unreference

---

Typedef Documentation

typedef ObitDisplay*(* ObitDisplayCreateFP)(gchar *name, gchar *ServerURL, ObitErr *err)

Typedef for definition of class pointer structure.

typedef gboolean(* ObitDisplayShowFP)(ObitDisplay *display, Obit *image, ObitDConCleanWindow *window, gint field, ObitErr *err)

Typedef for definition of class pointer structure.

typedef void(* ObitDisplayTurnOffFP)(ObitDisplay *display)

Typedef for definition of class pointer structure.

typedef void(* ObitDisplayTurnOnFP)(ObitDisplay *display)

Typedef for definition of class pointer structure.

---

Enumeration Type Documentation

enum obitDisplayRequest

enum Display request coads (MUST be synchronized with server usage which is defined in ObitRPC.h #ObitRPCRequestType) This specifies the request Enumeration values: OBIT_Request_Continue  Continue program (no request for action). OBIT_Request_Abort  Abort program current results are assumed of no value. OBIT_Request_Quit  Quit, graceful shutdown with current results saved. OBIT_Request_NoTV  No more TV display. OBIT_Request_View  View, send another field in the same ObitImageMosaic. OBIT_Request_Edit  Edit, send window for editing.

---

Function Documentation

ObitDisplay* newObitDisplay (  gchar *  name  )

Public: Default Constructor. Initializes class if needed on first call. Parameters: name  An optional name for the object. Returns: the new object.

void ObitDisplayClassInit (  void   )

Public: Class initializer.

ObitDisplay* ObitDisplayCreate (  gchar *  name, gchar *  ServerURL, ObitErr *  err )

Public: Create/initialize ObitDisplay structures. Parameters: name  An optional name for the object. ServerURL  URL of display server, NULL defaults to "http://localhost:8765/RPC2" err  Obit Error message Returns: the new object.

gconstpointer ObitDisplayGetClass (  void   )

Public: ClassInfo pointer. Returns: pointer to the class structure.

gboolean ObitDisplayShow (  ObitDisplay *  display, Obit *  image, ObitDConCleanWindow *  window, gint  field, ObitErr *  err )

Public: Send Display and Window edit request. For a mosaic, the user can request other images from the mosaic. If the display is remote, the image is copied as a gzipped FITS file. Parameters: display  ObitDisplay object image  ObitImage or Image Mosaic window  if nonNULL window corresponding to image possibly edited by user. This MUST correspond to image. field  If image= an ImageMosaic then this is the 1-rel field number err  Obit Error message Returns: TRUE if user wants to quit

void ObitDisplayTurnOff (  ObitDisplay *  display  )

Public: Turn display off. Parameters: display  ObitDisplay object

void ObitDisplayTurnOn (  ObitDisplay *  display  )

Public: Turn display on. Parameters: display  ObitDisplay object

---