= Visual Property Discussion =

    * There are currently two serious issues with the visual property system:
        * Serializing a visual property to a format other than what the core supports.
        * Programmatic manipulation of visual properties that are not declared as API (e.g. NodeShape).
    * These issues impact the following use cases:
        * '''UC1''': CyNetworkViewReader constructs CyNetworkView with visual properties from a non-XGMML source.
        * '''UC2''': CyNetworkViewWriter writes a non-XGMML CyNetworkView with visual properties to disk.
        * '''UC3''': Non-core plugin creates a visual style.
        * '''UC4''': Non-core plugin creates a discrete visual mapping.

== Background ==

=== How Looking Up Visual Properties Currently Works ===

VisualProperties can vary from one RenderingEngine implementation to another.  In order to access a particular property you need to look it up in a VisualLexicon.  The lookup key is a file format-specific name.  For example, in GML, the "type" graphics attribute is mapped to the NODE_SHAPE visual property:

{{attachment:lookup-1.png}}

=== Specific issues ===

    * RenderingEngines are currently responsible for maintaining mappings between format-specific keys (e.g. XGMML attribute keys or GML keys) and VisualProperty instances.

=== Potential solution ===

Since each visual property already has an id, it would make sense to expose these ids as API through some kind of controlled vocabulary.  That way, different RenderingEngines can support conceptually-identical VisualProperties in a uniform way.  It would then be the responsibility of CyNetworkViewReader/Writers to map their format-specific visual property ids to the controlled vocabulary.

{{attachment:lookup-2.png}}

=== How Parsing/Serializing Visual Property Values Currently Works ===

Instances of VisualProperties are used to serialize and parse property values to and from strings.  The implementation of these parsers is the responsibility of RenderingEngine providers.

{{attachment:visualprops-1.png}}

==== Legend ====
    * Green arrows: Serialization relationships
    * Blue arrows: Parsing relationships

=== Specific Issues ===
    1. ['''UC1''','''UC2'''] Very awkward to serialize visual properties for formats other than XGMML.
        * Currently, we need to map between XGMML attribute strings and the target format's strings (e.g. GML).
    1. ['''UC3'''] Visual properties of inaccessible types (e.g. org.cytoscape.ding.NodeShape) are awkward to set programmatically.
        * Currently, you need to use a VisualProperty instance to construct a NodeShape instance by parsing the serialized form of the desired shape.
    1. ['''UC4'''] Visual properties of inaccessible types (e.g. org.cytoscape.ding.NodeShape) are awkward to use with discrete mappers programmatically.

=== Assumptions ===
    * RenderingEngine implementations and I/O implementations cannot know about one another.

=== Options ===
    * '''O1''': No change.  Let RenderingEngines handle visual property serialization.
        * RenderingEngine implementation can only serialize to and from one format.
        * Inhibited: '''UC1''', '''UC2'''
        * Awkward: '''UC3''', '''UC4'''.
----
{{attachment:visualprops-2.png}}
    
    * '''O2''': Same as '''O1''' but serialization format is not specific to any particular format.
        * Converting between generic format and a particular file type's format is just a string mapping.
        * Flexible, but potentially difficult to validate.
        * List of allowable string values would need to be documented somewhere.
        * Awkward: '''UC3''', '''UC4'''.
----
{{attachment:visualprops-3.png}}
    * '''O3''': Let CyNetworkViewReader/WriterFactories handle visual property serialization.
        * All visual property types would need to be exposed as API.
        * RenderingEngines can still introduce arbitrary visual property types.
            * However, these would not be accessible programmatically unless the vendor also supplies an API bundle for the new types.