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.SequenceFeature;
  24 import jalview.datamodel.SequenceI;
  25 import jalview.datamodel.features.FeatureMatcherSetI;
  26
  27 import java.awt.Color;
  28 import java.awt.Graphics;
  29 import java.util.List;
  30 import java.util.Map;
  31
  32 /**
  33  * Abstract feature renderer interface
  34  *
  35  * @author JimP
  36  *
  37  */
  38 public interface FeatureRenderer
  39 {
  40
  41   /**
  42    * Computes the feature colour for a given sequence and column position,
  43    * taking into account sequence feature locations, feature colour schemes,
  44    * render ordering, feature and feature group visibility, and transparency.
  45    * <p>
  46    * Does not take into account global feature visibility (show features on or
  47    * off). Test for this before calling this method if necessary. This allows,
  48    * for example, feature colours to be computed for structures even if not
  49    * shown on the alignment.
  50    * <p>
  51    * The graphics argument should be provided if transparency is applied
  52    * (getTransparency() < 1). With feature transparency, visible features are
  53    * written to the graphics context and the composite colour may be read off
  54    * from it. In this case, the returned feature colour is not the composite
  55    * colour but that of the last feature drawn.
  56    * <p>
  57    * If no transparency applies, then the graphics argument may be null, and the
  58    * returned colour is the one that would be drawn for the feature.
  59    * <p>
  60    * Returns null if there is no visible feature at the position.
  61    * <p>
  62    * This is provided to support rendering of feature colours other than on the
  63    * sequence alignment, including by structure viewers and the overview window.
  64    * Note this method takes no account of whether the sequence or column is
  65    * hidden.
  66    *
  67    * @param sequence
  68    * @param column
  69    *          aligned column position (1..)
  70    * @param g
  71    * @return
  72    */
  73   Color findFeatureColour(SequenceI sequence, int column, Graphics g);
  74
  75   /**
  76    * trigger the feature discovery process for a newly created feature renderer.
  77    */
  78   void featuresAdded();
  79
  80   /**
  81    *
  82    * @param ft
  83    * @return display style for a feature
  84    */
  85   FeatureColourI getFeatureStyle(String ft);
  86
  87   /**
  88    * update the feature style for a particular feature
  89    *
  90    * @param ft
  91    * @param ggc
  92    */
  93   void setColour(String ft, FeatureColourI ggc);
  94
  95   AlignViewportI getViewport();
  96
  97   /**
  98    *
  99    * @return container managing list of feature types and their visibility
 100    */
 101   FeaturesDisplayedI getFeaturesDisplayed();
 102
 103   /**
 104    * get display style for all features types - visible or invisible
 105    *
 106    * @return
 107    */
 108   Map<String, FeatureColourI> getFeatureColours();
 109
 110   /**
 111    * query the alignment view to find all features
 112    *
 113    * @param newMadeVisible
 114    *          - when true, automatically make newly discovered types visible
 115    */
 116   void findAllFeatures(boolean newMadeVisible);
 117
 118   /**
 119    * get display style for all features types currently visible
 120    *
 121    * @return
 122    */
 123   Map<String, FeatureColourI> getDisplayedFeatureCols();
 124
 125   /**
 126    * get all registered groups
 127    *
 128    * @return
 129    */
 130   List<String> getFeatureGroups();
 131
 132   /**
 133    * get groups that are visible/invisible
 134    *
 135    * @param visible
 136    * @return
 137    */
 138   List<String> getGroups(boolean visible);
 139
 140   /**
 141    * Set visibility for a list of groups
 142    *
 143    * @param toset
 144    * @param visible
 145    */
 146   void setGroupVisibility(List<String> toset, boolean visible);
 147
 148   /**
 149    * Set visibility of the given feature group
 150    *
 151    * @param group
 152    * @param visible
 153    */
 154   void setGroupVisibility(String group, boolean visible);
 155
 156   /**
 157    * Returns visible features at the specified aligned column on the given
 158    * sequence. Non-positional features are not included. If the column has a gap,
 159    * then enclosing features are included (but not contact features).
 160    *
 161    * @param sequence
 162    * @param column
 163    *          aligned column position (1..)
 164    * @return
 165    */
 166   List<SequenceFeature> findFeaturesAtColumn(SequenceI sequence, int column);
 167
 168   /**
 169    * Returns features at the specified residue position on the given sequence.
 170    * Non-positional features are not included.
 171    *
 172    * @param sequence
 173    * @param resNo
 174    *          residue position (start..)
 175    * @return
 176    */
 177   List<SequenceFeature> findFeaturesAtResidue(SequenceI sequence, int resNo);
 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 type is not visible, or</li>
 264    * <li>feature group is not visible, or</li>
 265    * <li>feature values lie outside any colour threshold, or</li>
 266    * <li>feature is excluded by filter conditions</li>
 267    * </ul>
 268    *
 269    * @param feature
 270    * @return
 271    */
 272   Color getColour(SequenceFeature feature);
 273 }