src/jalview/api/FeatureRenderer.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.api;
  22
  23 import jalview.datamodel.MappedFeatures;
  24 import jalview.datamodel.SequenceFeature;
  25 import jalview.datamodel.SequenceI;
  26 import jalview.datamodel.features.FeatureMatcherSetI;
  27
  28 import java.awt.Color;
  29 import java.awt.Graphics;
  30 import java.util.List;
  31 import java.util.Map;
  32
  33 /**
  34  * Abstract feature renderer interface
  35  *
  36  * @author JimP
  37  *
  38  */
  39 public interface FeatureRenderer
  40 {
  41
  42   /**
  43    * Computes the feature colour for a given sequence and column position,
  44    * taking into account sequence feature locations, feature colour schemes,
  45    * render ordering, feature and feature group visibility, and transparency.
  46    * <p>
  47    * The graphics argument should be provided if transparency is applied
  48    * (getTransparency() < 1). With feature transparency, visible features are
  49    * written to the graphics context and the composite colour may be read off
  50    * from it. In this case, the returned feature colour is not the composite
  51    * colour but that of the last feature drawn.
  52    * <p>
  53    * If no transparency applies, then the graphics argument may be null, and the
  54    * returned colour is the one that would be drawn for the feature.
  55    * <p>
  56    * Returns null if there is no visible feature at the position.
  57    * <p>
  58    * This is provided to support rendering of feature colours other than on the
  59    * sequence alignment, including by structure viewers and the overview window.
  60    * Note this method takes no account of whether the sequence or column is
  61    * hidden.
  62    *
  63    * @param sequence
  64    * @param column
  65    *          aligned column position (1..)
  66    * @param g
  67    * @return
  68    */
  69   Color findFeatureColour(SequenceI sequence, int column, Graphics g);
  70
  71   /**
  72    * trigger the feature discovery process for a newly created feature renderer.
  73    */
  74   void featuresAdded();
  75
  76   /**
  77    *
  78    * @param ft
  79    * @return display style for a feature
  80    */
  81   FeatureColourI getFeatureStyle(String ft);
  82
  83   /**
  84    * update the feature style for a particular feature
  85    *
  86    * @param ft
  87    * @param ggc
  88    */
  89   void setColour(String ft, FeatureColourI ggc);
  90
  91   AlignViewportI getViewport();
  92
  93   /**
  94    *
  95    * @return container managing list of feature types and their visibility
  96    */
  97   FeaturesDisplayedI getFeaturesDisplayed();
  98
  99   /**
 100    * get display style for all features types - visible or invisible
 101    *
 102    * @return
 103    */
 104   Map<String, FeatureColourI> getFeatureColours();
 105
 106   /**
 107    * query the alignment view to find all features
 108    *
 109    * @param newMadeVisible
 110    *          - when true, automatically make newly discovered types visible
 111    */
 112   void findAllFeatures(boolean newMadeVisible);
 113
 114   /**
 115    * get display style for all features types currently visible
 116    *
 117    * @return
 118    */
 119   Map<String, FeatureColourI> getDisplayedFeatureCols();
 120
 121   /**
 122    * get all registered groups
 123    *
 124    * @return
 125    */
 126   List<String> getFeatureGroups();
 127
 128   /**
 129    * get groups that are visible/invisible
 130    *
 131    * @param visible
 132    * @return
 133    */
 134   List<String> getGroups(boolean visible);
 135
 136   /**
 137    * Set visibility for a list of groups
 138    *
 139    * @param toset
 140    * @param visible
 141    */
 142   void setGroupVisibility(List<String> toset, boolean visible);
 143
 144   /**
 145    * Set visibility of the given feature group
 146    *
 147    * @param group
 148    * @param visible
 149    */
 150   void setGroupVisibility(String group, boolean visible);
 151
 152   /**
 153    * Returns visible features at the specified aligned column on the given
 154    * sequence. Non-positional features are not included. If the column has a gap,
 155    * then enclosing features are included (but not contact features).
 156    *
 157    * @param sequence
 158    * @param column
 159    *          aligned column position (1..)
 160    * @return
 161    */
 162   List<SequenceFeature> findFeaturesAtColumn(SequenceI sequence, int column);
 163
 164   /**
 165    * Returns features at the specified residue positions on the given sequence.
 166    * Non-positional features are not included. Features are returned in render
 167    * order of their feature type (last is on top). Within feature type, ordering
 168    * is undefined.
 169    *
 170    * @param sequence
 171    * @param fromResNo
 172    * @param toResNo
 173    * @return
 174    */
 175   List<SequenceFeature> findFeaturesAtResidue(SequenceI sequence,
 176           int fromResNo, int toResNo);
 177
 178   /**
 179    * get current displayed types, in ordering of rendering (on top last)
 180    *
 181    * @return a (possibly empty) list of feature types
 182    */
 183
 184   List<String> getDisplayedFeatureTypes();
 185
 186   /**
 187    * Returns a (possibly empty) list of currently visible feature groups
 188    *
 189    * @return
 190    */
 191   List<String> getDisplayedFeatureGroups();
 192
 193   /**
 194    * display all features of these types
 195    *
 196    * @param featureTypes
 197    */
 198   void setAllVisible(List<String> featureTypes);
 199
 200   /**
 201    * display featureType
 202    *
 203    * @param featureType
 204    */
 205   void setVisible(String featureType);
 206
 207   /**
 208    * Sets the transparency value, between 0 (full transparency) and 1 (no
 209    * transparency)
 210    *
 211    * @param value
 212    */
 213   void setTransparency(float value);
 214
 215   /**
 216    * Returns the transparency value, between 0 (full transparency) and 1 (no
 217    * transparency)
 218    *
 219    * @return
 220    */
 221   float getTransparency();
 222
 223   /**
 224    * Answers the filters applied to the given feature type, or null if none is
 225    * set
 226    *
 227    * @param featureType
 228    * @return
 229    */
 230   FeatureMatcherSetI getFeatureFilter(String featureType);
 231
 232   /**
 233    * Answers the feature filters map
 234    *
 235    * @return
 236    */
 237   public Map<String, FeatureMatcherSetI> getFeatureFilters();
 238
 239   /**
 240    * Sets the filters for the feature type, or removes them if a null or empty
 241    * filter is passed
 242    *
 243    * @param featureType
 244    * @param filter
 245    */
 246   void setFeatureFilter(String featureType, FeatureMatcherSetI filter);
 247
 248   /**
 249    * Replaces all feature filters with the given map
 250    *
 251    * @param filters
 252    */
 253   void setFeatureFilters(Map<String, FeatureMatcherSetI> filters);
 254
 255   /**
 256    * Returns the colour for a particular feature instance. This includes
 257    * calculation of 'colour by label', or of a graduated score colour, if
 258    * applicable.
 259    * <p>
 260    * Returns null if
 261    * <ul>
 262    * <li>feature group is not visible, or</li>
 263    * <li>feature values lie outside any colour threshold, or</li>
 264    * <li>feature is excluded by filter conditions</li>
 265    * </ul>
 266    * This method does not check feature type visibility.
 267    *
 268    * @param feature
 269    * @return
 270    */
 271   Color getColour(SequenceFeature feature);
 272
 273   /**
 274    * Answers true if feature would be shown, else false. A feature is shown if
 275    * <ul>
 276    * <li>its feature type is set to visible</li>
 277    * <li>its feature group is either null, or set to visible</li>
 278    * <li>it is not excluded by a colour threshold on score or other numeric
 279    * attribute</li>
 280    * <li>it is not excluded by a filter condition</li>
 281    * </ul>
 282    *
 283    * @param feature
 284    * @return
 285    */
 286   boolean isVisible(SequenceFeature feature);
 287
 288   /**
 289    * Answers a bean containing a mapping, and a list of visible features in this
 290    * alignment at a position (or range) which is mappable from the given sequence
 291    * residue position in a mapped alignment. Features are returned in render order
 292    * of feature type (on top last), with order within feature type undefined. If
 293    * no features or mapping are found, answers null.
 294    *
 295    * @param sequence
 296    * @param pos
 297    * @return
 298    */
 299   MappedFeatures findComplementFeaturesAtResidue(SequenceI sequence, int pos);
 300
 301   /**
 302    * Sends a message to let any registered parties know that something about
 303    * feature rendering has changed
 304    */
 305   void notifyFeaturesChanged();
 306
 307 }