ObjectGraphics

Object Graphics Properties v 0.5

Current Issues

• Root object
  • It would be much easier if the default properties were listed as Default.Type.Property instead of DefaultTypeProperty?.
  • I've created a Required.Type (e.g. required.line) as a child of the root object that lists the required properties as {'prop1' 'prop1', ...} so that object creation can be one simple function instead of many more complex functions.
  • I've also created a ChildProps?.Type (e.g. childprops.line) that keeps a list of all properties that contain handles to other objects as their children. This allows for tree searching and for easy object deletion.
  • Create an "Orphans" property that will keep a list of all handles that have been created but do not yet have parents. This is to prevent the need for garbage collection in case of an error while an object is being created when its children may have already been created.
• Should we have a repository for UserData? in the plot?
• Where do we put additional information about the plot that is not necessarily part of the standard (i.e. for the mapping toolbox)?
  • Should we add an ExtraData? field to most objects?
• How do we handle uiobjects?
• What about hg* objects (the group objects used by matlab)?
  • Can we address this with the group object?
• Should group objects have a ChildrenInherit? flag that would allow for all immediate children of the object to inherit a change (i.e. if I set(groupobj, "color", [1 0 0]) since the group by itself has few properties, should it be possible to set all immediate children's color red if we have previously done set(groupobj, "ChildrenInherit", 1))?
• Are there any issues with the backend changing object settings (I'm thinking of things like figure.position is the simplest one, but any setting in general should be changable from either end).
• Do we want to include any versioning in the objects so that if a figure is saved today, but opened a year from now we may be able to more intelligently convert?

Resolved Issues

• Text objects: The widthheight property seems as though it would be both backend specific and as if it doesn't really belong. Can we remove it?
  • Removed. It would be good for a backend to provide a mechanism for finding the width and height, but they're not required to.
• How do we determine the layer order of objects?
  • Use the order of the children (first child first, second child second, etc.).
• Do we need patch and surface objects?
  • Patches are general polygons while surfaces are rectangular grids, so both are needed as separate objects.
• How should we store user data entered in one method when our preferred format is a different method (specifically, I'm thinking of rgb values given that we will convert to rgba, but it will proabably apply more generally)?
  • See general rules, generally if we don't change the user's intent then no warning will be given.
• How do we want to handle implementation dependent features?
  • This document specifies the minimum required settings. See General Rules for more info.
• Should we bother with a numbering convention for objects?
  • The object numbering convention should be accepted as whatever is provided. No assumptions should be made about the object number other than that it will be a unique double for every object.
• Should any units other than the figure be in device dependent units (like pixels)?
  • All units possible should be changed from pixels to parent object units. What do we do with LineWidth?, MarkerSize?, and text's WidthHeight? properties?
  • Use points for anything that may make sense as pixels.
• What exactly is the movie object and how is it used?
  • The movie object is a figure-level object that should be used by movie creation backends that will create multiple frames based on its children. If given a non-image object as a frame, it should rasterize that object (possibly with the help of another backend) only at movie creation time and it should keep the non-image object in its original form in the property methods.
• For 3d objects, do we want to implement light and camera features?
  • Camera and light properties are now in the axes object.
• Are we going for full matlab compliance? If not, do we want to create a translator of some type?
  • See the new general and backend functions sections.

General Rules

• If any input is invalid, the user will be warned by Octave that they entered an invalid option and either the pre-existing setting (preferred) or the default will be used. The user should be told in the warning what is used.
• If input is given that over-specifies the system (e.g. a 1x4 vector that should have been 1x2 or 1x3), the user should be notified and an attempt should be made to do what the user meant (i.e. when a 1x4 vector is given and a 1x2 is expected, Octave should use the first two elements). If the user's intent cannot be determined, and error should be raised.
• Default values should be taken from the root (0) object whenever possible. These values can be set in the root (0) object by adding "Default[property name]" i.e. set(0,"DefaultTextColor","r"); will set the default text color to red.
• For any values that are given as text (especially property names), when appropriate they should be matched case insensitively.
• Saving a figure should consist of a script that will add the current figure to the variable workspace and displaying it (with the exception of backends that create files as their display mechanism). The script should run without adding any variables to the global space other than the figure data, and it should allow for the fact that the figure number used previously and the object numbers may be used currently.
• For any parameters that change the user's input into a preferred form, if the transformation does not change the intent of the data (e.g. for rgb to rgba where a = 1) no warning will be given.
  • Related to this is that if a backend does not support an optional parameter, it is the responsibility of the backend to notify the user if the intent is changed. e.g. If the backend does not support an alpha channel, and the alpha channel is 1 for all fields, then no warning is necessary, but if alpha is less than 1 for any field, the user should be warned, but the checking should always be done.
• Whenever a vector is stored, it should be stored as a column vector.
• Implementation dependent features (both object types and properties) are allowed, and this document is intended to only show minimum features of object graphics. The set function will probe an implementation specific __set__ function if a property or type does not exist in the general Object Graphics properties or types. It is highly suggested for any properties that may be useful to other users or implementations to suggest them to the maintainers of the Object Graphics specification for possible inclusion.
• Layer order should be determined by the order of the children of an object (i.e. draw the first child object completely then draw the second object on top of the first object). All parts of an object should be drawn before any children are drawn

General Functions Needed

All these functions should fall through to the backend in any sort of failure case before returning an error to the user. The backends should implement these functions with underscores around them (i.e. __get__) with the same arguements.

• get(object, [property])
  • Return the properties from an object. If property is not specified, all properties for the given object are returned as a structure.
• isproperty(object, property)
  • Does the specified object type have the property.
• propnames(object)
  • Return a cellstr vector of all properties of an object. This is equivalent to fieldnames(get(object)).
• set(object, property, value)
  • Set the property of the object to value.

Backend Functions Needed

• __drawnow__(object)
  • Draw the specified object. If the backend does not support redrawing individual objects, then the entire figure should be redrawn.

Variable Types

• boolean: "yes" or "no", "y" or "n", or non-zero or zero should be accepted for any boolean by Octave and these will be translated to just the 1/0 notation for the graphics backend.
• colorspec can be either one of "r" (red [1 0 0 1]), "g" (green [0 1 0 1]), "b" (blue [0 0 1 1]), "c" (cyan [0 1 1 1]), "m" (magenta [1 0 1 1]), "y" (yellow [1 1 0 1]), "w" (white [1 1 1 1]), "k" (black [0 0 0 1]), "none" ([0 0 0 0]) as a string or an [r, g, b, a] vector. Some backends may ignore the alpha value, and if alpha is omitted, it will be assumed to be full (1.0, 255, etc.). Color values will be assumed to be given on a scale appropriate for the class of variable (i.e. uint8 is in the range [0 255])
• linespec can be any of "-" (solid), "--" (dashed), ":" (dotted), "-." (dash-dot), "none" (no line).
• markerspec can be any one of "none", "+", "o", "*", ".", "x".
• scalars, vectors, and matrixes are assumed to be of type double unless otherwise specified.
• objects are doubles of the form [figure number].[object number].

Object Types

• Axes
• Figure
• Group
• Image
• Legend
• Line
• Movie
• Patch
• Root
• Surface
• Text

Axes

• CameraPosition?
  • Camera position (1x3 vector)
• CameraPositionMode?
  • "auto" or "manual" for definition of CameraPosition?. When "auto", points to the center of the axes. (char vector)
• CameraProjection?
  • "orthographic" (default) or "perspective" (char vector)
• CameraTarget?
  • Location that the camera looks at (1x3 vector)
• CameraTargetMode?
  • "auto" or "manual" for definition of CameraTarget? (char vector)
• CameraUpVector?
  • Unit vector pointing up for the camera's perspective (1x3 vector)
• CameraUpVectorMode?
  • "auto" or "manual" for definition of CameraUpVector? (char vector)
• CameraViewAngle?
  • Amount of zoom that the camera uses (scalar, 0-180 degrees)
• CameraViewAngleMode?
  • "auto" or "manual" for definition of CameraViewAngle? (char vector)
• Children
  • The objects that are within this axes (lines, text, ...) excluding axes labels and tick labels which have properties of their own. (object vector)
• Color
  • Axes background color (colorspec)
• ColorOrder?
  • An mx3 matrix of rgb value. used by plot when plotting multiple lines without explicit color properties (mx3 matrix)
• GridLineStyle?
  • The grid line style. (linespec)
• GridLineWidth?
  • The grid line width. (scalar)
• LightColor?
  • The color of the light in the scene. (1x3 vector) Some backends may allow more than one light; if they do, then colors should be defined as (nx3 matrix).
• LightPosition?
  • The position of the light in [x y z]. (1x3 vector) Some backends may allow more than one light; if they do, then positions should be defined as (nx3 matrix).
• LightStyle?
  • "infinite" or "local" for parallel or divergent lighting. (char vector) Some backends may allow more than one light; if they do, then styles should be defined as a char matrix with n rows and deblanking on each line should return "infinite" or "local". (char matrix)
• LineWidth?
  • The linewidth of the axis (scalar)
• NextPlot?
  • Determines if next line will add or replace current axes lines. Values: "add", "replace"
• Position
  • The axes position in figure units [left, top, width, height] (1x4 vector)
• Parent
  • Axes' parent (object)
• Tag
  • A user defined string for notation of the current object (char matrix)
• TickLength?
  • The tick length in points. The three elements should correspond to x, y, and z tick lengths. If only a scalar is given, it should be assigned to all three. (3x1 vector)
• Type
  • A string that should always be "Axes" (char vector)
• Visible
  • Axes' visibility (boolean)
• XColor, YColor, ZColor
  • The color of the x, y, and z axes (colorspec)
• XLabel, YLabel, ZLabel
  • Object number for the x, y, or z axis label text objects (object)
• Xlim, YLim, Zlim, CLim
  • The x, y, z, and color axes limits respectively (vector)
• XLimMode?, YLimMode?, ZLimMode?, CLimMode?
  • Determines how the x,y,z, and color axis limits are set. Values: "auto", "manual"
• XScale, YScale, ZScale
  • Determines if the x,y,z axes are linear or log. Values: "linear", "log"
• XTick, YTick, ZTick
  • Vector of x, y, and z ticks (vector)
• XTickLabel?, YTickLabel?, ZTickLabel?
  • A cell vector (e.g. {"1";"2";"3"}) which will be used for x, y, and z labels. The label placement is determined by the XTick, YTick, and ZTick vectors. If the list is shorter than the vector length, the list is cycled, and if the list is longer than the vector only the first elements are used. If a char array is used to set this, then it will be deblanked before being converted into cells. (cellstr vector)
• XtickLabelObject?, YTickLabelObject?, ZTickLabelObject?
  • Object numbers for the x, y, and z axis tick labels. (object)
• XTickLabelMode?, YTickLabelMode?, ZTickLabelMode?
  • Determines how x, y, and z labels are set. Values: "auto" or "manual"

Figure

• Children
  • The objects that fall within this figure (e.g. axes ...) (object vector)
• Colormap
  • an m-by-3 matrix of rgb values. (mx3 matrix)
• CurrentAxes?
  • Object for the current axes in this figure (object)
• Filename
  • The complete path and filename to use for saving the figure. If it is blank, "figure[number].m" should be used. If a path is not given, it should be saved in the current directory. (char vector)
• Number
  • The figures number (scalar)
• Parent
  • Figures parent (root)
• Position
  • Position [left, top, width, height] of the figure in pixels relative to the display device (e.g. screen, page, etc.) (vector)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Figure"
• Visible
  • Figure's visibility (boolean)

Group

• Children
  • The objects that are within this group (lines, text, ...). (object vector)
• Clipping
  • Will the Group be clipped to the axes? (boolean)
• Parent
  • Group's parent (object)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Group" (char)
• Visible
  • Group's visibility (boolean)

Image

• Clipping
  • Will the legend be clipped to the axes? (boolean)
• ColorMap?
  • The color values corresponding to an image mapping (nx3 matrix in the range [0 1])
• EdgeColor?
  • The image's edgecolor (colorspec)
• ImageData?
  • The image data. If it is mxnx3 (or mxnx4), it is interpreted as a color intensity with each plane in the third dimensions as rgb (or rgba). If it is mxn and boolean, it is interpreted as monochrome. If it is mxn and double in the range [0 1], it is interpreted as a grayscale image. If it is mxn and an integer type, it is interpreted as a mapping to the colormap. (matrix)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Image".
• Visible
  • Image's visibility (boolean)

Legend

• Clipping
  • Will the legend be clipped to the axes? (boolean)
• EdgeColor?
  • The legend box's edgecolor (colorspec)
• FaceColor?
  • The legend box's face color (colorspec)
• Label
  • Object numbers of the legend text objects (object vector)
• Line
  • Object numbers of the legend lines (object vector)
• Location
  • Specifies the textbox location. Can be one of the 8 major compass directions, abbreviated or not (i.e northwest or nw) or the location in axis coordinates. Default is NE.
• Parent
  • Legend's parent (object)
• Patch
  • Object number of the legend's patch object which is used to draw the legend's box (object)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Legend".
• Visible
  • Legend's visibility (boolean)

Line

• Clipping
  • Will the line be clipped to the axes? (boolean)
• Color
  • Line color (colorspec)
• Label
  • Object number for a text object containing the line's label in the legend (object)
• LineStyle?
  • Line style. (linespec)
• LineWidth?
  • Line width in points (scalar)
• Marker
  • Line marker style. (markerspec)
• MarkerEdgeColor?
  • Line marker edge color (colorspec)
• MarkerFaceColor?
  • Line marker face color (colorspec)
• MarkerSize?
  • Line marker size in points (scalar)
• Parent
  • Line's parent (object)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Line"
• Visible
  • Line's visibility (boolean)
• XData, YData, ZData
  • Line's data. XData can be empty, in which case YData is plotted against it's index. If ZData is empty, this is plotted on the z = 0 plane. If any of the elements (either in Xdata or Ydata) is "NaN", that element is treated as a missing value and not plotted. (vector)

Movie

• Children
  • The objects that are within this movie (lines, text, ...) on every frame. (object vector)
• ChildStartStop?
  • An nx2 matrix of times in the movie (frame numbers) that the child object should be visible. The first column would be the start time and the second column would be the stop time. If either number is NaN, it should indicate that it goes to that end of the movie. (nx2 matrix)
• Frames
  • All frames in order (nx1 object vector)
• FramesPerSecond?
  • The number of frames to play per second (scalar)
• Filename
  • The complete path and filename to use for saving the figure. If it is blank, "movie[number].m" should be used. If a path is not given, it should be saved in the current directory. (char vector)
• FileType?
  • The file type for import or export. Can be either of "mpg", "avi".
• Number
  • The movie's figure number (scalar)
• Parent
  • Figure's parent (root)
• Position
  • Position [left, top, width, height] of the figure in pixels relative to the screen (vector)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Movie".
• Visible
  • Movie's visibility (boolean)

Patch

• Clipping
  • Will the patch be clipped to the axes? (boolean)
• EdgeColor?
  • Edge color. (colorspec)
• FaceColor?
  • Face color. (colorspec)
• Label
  • Object number for a text object containing the patch's label in the legend (object)
• LineStyle?
  • Edge linestyle. (linespec)
• LineWidth?
  • Edge linewidth in points (scalar)
• Marker
  • Edge marker style. (markerspec)
• MarkerEdgeColor?
  • Edge marker edge color (colorspec)
• MarkerFaceColor?
  • Edge marker face color (colorspec)
• MarkerSize?
  • Edge marker size in points (scalar)
• Parent
  • Patch's parent (object)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Patch"
• Visible
  • Line's visibility (boolean)
• XData, YData, ZData
  • Patch's data. XData, YData, and ZData should be the same length

Root

FIXME

• CurrentFigure?
  • Object for the current figure (object)
• Default<type><property>
  • For all other properties, the default property of that type. Properties of this form should exist for all properties on this page with the exception of properties that should have no default and must be defined (e.g. DefaultLineXData? should not exist). If the default does not exist and the value is not given, then an error should be reported on instantiation of the object.
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Root".

Surface

• Clipping
  • Surface clipping. (boolean)
• EdgeColor?
  • Edge color. (colorspec)
• FaceColor?
  • Face color. (colorspec)
• Label
  • Object number for a text object containing the surface's label in the legend (object)
• LineStyle?
  • Edge linestyle. (linespec)
• LineWidth?
  • Edge linewidth in points (scalar)
• Parent
  • Surface's parent (object)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Surface"
• Visible
  • Surface visibility (boolean)
• XData, YData, ZData
  • x, y, or z coordiantes. The surface is defined by (x(i,j), y(i,j), z(i,j)). They must be of the same size (matrix)

Text

• Clipping
  • Will the text be clipped to the axes? (boolean)
• Color
  • Text color. (colorspec)
• FontName?
  • Font name. (char vector)
• FontSize?
  • Font size in points (scalar)
• HorizontalAlignment?
  • Horizontal alignments of the text. One of "left", "center", "right"
• Parent
  • Text's parent object (object number)
• Position
  • Position (x, y, z) of the text (1x2 or 1x3 vector)
• Rotation
  • Font rotation in degrees up from east (scalar in the range [0 360))
• String
  • The text of the text object. (char vector)
• Tag
  • A user defined string for notation of the current object (char matrix)
• Type
  • A string that should always be "Text".
• VerticalAlignment?
  • Vertical alignment of the text. Can be one of "top", "middle", "bottom" (string- default: bottom)
• Visible
  • Text's visibility (boolean)