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
 155    * gap, 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,
 163           int column);
 164
 165   /**
 166    * Returns features at the specified residue positions on the given sequence.
 167    * Non-positional features are not included. Features are returned in render
 168    * order of their feature type (last is on top). Within feature type, ordering
 169    * is undefined.
 170    *
 171    * @param sequence
 172    * @param fromResNo
 173    * @param toResNo
 174    * @return
 175    */
 176   List<SequenceFeature> findFeaturesAtResidue(SequenceI sequence,
 177           int fromResNo, int toResNo);
 178
 179   /**
 180    * get current displayed types, in ordering of rendering (on top last)
 181    *
 182    * @return a (possibly empty) list of feature types
 183    */
 184
 185   List<String> getDisplayedFeatureTypes();
 186
 187   /**
 188    * Returns a (possibly empty) list of currently visible feature groups
 189    *
 190    * @return
 191    */
 192   List<String> getDisplayedFeatureGroups();
 193
 194   /**
 195    * display all features of these types
 196    *
 197    * @param featureTypes
 198    */
 199   void setAllVisible(List<String> featureTypes);
 200
 201   /**
 202    * display featureType
 203    *
 204    * @param featureType
 205    */
 206   void setVisible(String featureType);
 207
 208   /**
 209    * Sets the transparency value, between 0 (full transparency) and 1 (no
 210    * transparency)
 211    *
 212    * @param value
 213    */
 214   void setTransparency(float value);
 215
 216   /**
 217    * Returns the transparency value, between 0 (full transparency) and 1 (no
 218    * transparency)
 219    *
 220    * @return
 221    */
 222   float getTransparency();
 223
 224   /**
 225    * Answers the filters applied to the given feature type, or null if none is
 226    * set
 227    *
 228    * @param featureType
 229    * @return
 230    */
 231   FeatureMatcherSetI getFeatureFilter(String featureType);
 232
 233   /**
 234    * Answers the feature filters map
 235    *
 236    * @return
 237    */
 238   public Map<String, FeatureMatcherSetI> getFeatureFilters();
 239
 240   /**
 241    * Sets the filters for the feature type, or removes them if a null or empty
 242    * filter is passed
 243    *
 244    * @param featureType
 245    * @param filter
 246    */
 247   void setFeatureFilter(String featureType, FeatureMatcherSetI filter);
 248
 249   /**
 250    * Replaces all feature filters with the given map
 251    *
 252    * @param filters
 253    */
 254   void setFeatureFilters(Map<String, FeatureMatcherSetI> filters);
 255
 256   /**
 257    * Returns the colour for a particular feature instance. This includes
 258    * calculation of 'colour by label', or of a graduated score colour, if
 259    * applicable.
 260    * <p>
 261    * Returns null if
 262    * <ul>
 263    * <li>feature group is not visible, or</li>
 264    * <li>feature values lie outside any colour threshold, or</li>
 265    * <li>feature is excluded by filter conditions</li>
 266    * </ul>
 267    * This method does not check feature type visibility.
 268    *
 269    * @param feature
 270    * @return
 271    */
 272   Color getColour(SequenceFeature feature);
 273
 274   /**
 275    * Answers true if feature would be shown, else false. A feature is shown if
 276    * <ul>
 277    * <li>its feature type is set to visible</li>
 278    * <li>its feature group is either null, or set to visible</li>
 279    * <li>it is not excluded by a colour threshold on score or other numeric
 280    * attribute</li>
 281    * <li>it is not excluded by a filter condition</li>
 282    * </ul>
 283    *
 284    * @param feature
 285    * @return
 286    */
 287   boolean isVisible(SequenceFeature feature);
 288
 289   /**
 290    * Answers a bean containing a mapping, and a list of visible features in this
 291    * alignment at a position (or range) which is mappable from the given
 292    * sequence residue position in a mapped alignment. Features are returned in
 293    * render order of feature type (on top last), with order within feature type
 294    * undefined. If no features or mapping are found, answers null.
 295    *
 296    * @param sequence
 297    * @param pos
 298    * @return
 299    */
 300   MappedFeatures findComplementFeaturesAtResidue(SequenceI sequence,
 301           int pos);
 302
 303   /**
 304    * Sends a message to let any registered parties know that something about
 305    * feature rendering has changed
 306    */
 307   void notifyFeaturesChanged();
 308
 309 }