JAL-3676 Documentation in Help for Java Console, Logging and Reporting Bugs
[jalview.git] / src / jalview / schemes / UserColourScheme.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.schemes;
22
23 import jalview.api.AlignViewportI;
24 import jalview.datamodel.AnnotatedCollectionI;
25 import jalview.util.ColorUtils;
26 import jalview.util.StringUtils;
27
28 import java.awt.Color;
29 import java.util.ArrayList;
30 import java.util.Collections;
31 import java.util.HashMap;
32 import java.util.List;
33 import java.util.Map;
34 import java.util.Map.Entry;
35 import java.util.StringTokenizer;
36
37 public class UserColourScheme extends ResidueColourScheme
38 {
39   /*
40    * lookup (by symbol index) of lower case colours (if configured)
41    */
42   Color[] lowerCaseColours;
43
44   protected String schemeName;
45
46   public UserColourScheme()
47   {
48     super(ResidueProperties.aaIndex);
49   }
50
51   public UserColourScheme(Color[] newColors)
52   {
53     super(ResidueProperties.aaIndex);
54     colors = newColors;
55   }
56
57   @Override
58   public ColourSchemeI getInstance(AlignViewportI view,
59           AnnotatedCollectionI sg)
60   {
61     return new UserColourScheme(this);
62   }
63
64   /**
65    * Copy constructor
66    * 
67    * @return
68    */
69   protected UserColourScheme(UserColourScheme from)
70   {
71     this(from.colors);
72     schemeName = from.schemeName;
73     if (from.lowerCaseColours != null)
74     {
75       lowerCaseColours = new Color[from.lowerCaseColours.length];
76       System.arraycopy(from.lowerCaseColours, 0, lowerCaseColours, 0,
77               from.lowerCaseColours.length);
78     }
79   }
80
81   /**
82    * Constructor for an animino acid colour scheme. The colour specification may
83    * be one of
84    * <ul>
85    * <li>an AWT colour name e.g. red</li>
86    * <li>an AWT hex rgb colour e.g. ff2288</li>
87    * <li>residue colours list e.g. D,E=red;K,R,H=0022FF;c=yellow</li>
88    * </ul>
89    * 
90    * @param colour
91    */
92   public UserColourScheme(String colour)
93   {
94     super(ResidueProperties.aaIndex);
95
96     if (colour.contains("="))
97     {
98       /*
99        * a list of colours per residue(s)
100        */
101       parseAppletParameter(colour);
102       return;
103     }
104
105     Color col = ColorUtils.parseColourString(colour);
106
107     if (col == null)
108     {
109       System.out.println("Making colour from name: " + colour);
110       col = ColorUtils.createColourFromName(colour);
111     }
112
113     setAll(col);
114     schemeName = colour;
115   }
116
117   /**
118    * Sets all symbols to the specified colour
119    * 
120    * @param col
121    */
122   protected void setAll(Color col)
123   {
124     if (symbolIndex == null)
125     {
126       return;
127     }
128     int max = 0;
129     for (int index : symbolIndex)
130     {
131       max = Math.max(max, index);
132     }
133     colors = new Color[max + 1];
134     for (int i = 0; i <= max; i++)
135     {
136       colors[i] = col;
137     }
138   }
139
140   public Color[] getColours()
141   {
142     return colors;
143   }
144
145   public Color[] getLowerCaseColours()
146   {
147     return lowerCaseColours;
148   }
149
150   public void setName(String name)
151   {
152     schemeName = name;
153   }
154
155   public String getName()
156   {
157     return schemeName;
158   }
159
160   /**
161    * Parse and save residue colours specified as (for example)
162    * 
163    * <pre>
164    *     D,E=red; K,R,H=0022FF; c=100,50,75
165    * </pre>
166    * 
167    * This should be a semi-colon separated list of colours, which may be defined
168    * by colour name, hex value or comma-separated RGB triple. Each colour is
169    * defined for a comma-separated list of amino acid single letter codes. (Note
170    * that this also allows a colour scheme to be defined for ACGT, but not for
171    * U.)
172    * 
173    * @param paramValue
174    */
175   void parseAppletParameter(String paramValue)
176   {
177     setAll(Color.white);
178
179     StringTokenizer st = new StringTokenizer(paramValue, ";");
180     StringTokenizer st2;
181     String token = null, colour, residues;
182     try
183     {
184       while (st.hasMoreElements())
185       {
186         token = st.nextToken().trim();
187         residues = token.substring(0, token.indexOf("="));
188         colour = token.substring(token.indexOf("=") + 1);
189
190         st2 = new StringTokenizer(residues, " ,");
191         while (st2.hasMoreTokens())
192         {
193           String residue = st2.nextToken();
194
195           int colIndex = ResidueProperties.aaIndex[residue.charAt(0)];
196           if (colIndex == -1)
197           {
198             continue;
199           }
200
201           if (residue.equalsIgnoreCase("lowerCase"))
202           {
203             if (lowerCaseColours == null)
204             {
205               lowerCaseColours = new Color[colors.length];
206             }
207             for (int i = 0; i < lowerCaseColours.length; i++)
208             {
209               if (lowerCaseColours[i] == null)
210               {
211                 lowerCaseColours[i] = ColorUtils.parseColourString(colour);
212               }
213             }
214
215             continue;
216           }
217
218           if (residue.equals(residue.toLowerCase()))
219           {
220             if (lowerCaseColours == null)
221             {
222               lowerCaseColours = new Color[colors.length];
223             }
224             lowerCaseColours[colIndex] = ColorUtils
225                     .parseColourString(colour);
226           }
227           else
228           {
229             colors[colIndex] = ColorUtils.parseColourString(colour);
230           }
231         }
232       }
233     } catch (Exception ex)
234     {
235       System.out.println(
236               "Error parsing userDefinedColours:\n" + token + "\n" + ex);
237     }
238
239   }
240
241   public void setLowerCaseColours(Color[] lcolours)
242   {
243     lowerCaseColours = lcolours;
244   }
245
246   /**
247    * Returns the colour for the given residue character. If the residue is
248    * lower-case, and there is a specific colour defined for lower case, that
249    * colour is returned, else the colour for the upper case residue.
250    */
251   @Override
252   public Color findColour(char c)
253   {
254     if ('a' <= c && c <= 'z' && lowerCaseColours != null)
255     {
256       Color colour = lowerCaseColours[symbolIndex[c]];
257       if (colour != null)
258       {
259         return colour;
260       }
261     }
262     return super.findColour(c);
263   }
264
265   /**
266    * Answers the customised name of the colour scheme, if it has one, else "User
267    * Defined"
268    */
269   @Override
270   public String getSchemeName()
271   {
272     if (schemeName != null && schemeName.length() > 0)
273     {
274       return schemeName;
275     }
276     return ResidueColourScheme.USER_DEFINED;
277   }
278
279   /**
280    * Generate an applet colour parameter like A,C,D=12ffe9;Q,W=2393fd;w=9178dd
281    * 
282    * @return
283    */
284   public String toAppletParameter()
285   {
286     /*
287      * step 1: build a map from colours to the symbol(s) that have the colour
288      */
289     Map<Color, List<String>> colours = new HashMap<>();
290
291     for (char symbol = 'A'; symbol <= 'Z'; symbol++)
292     {
293       String residue = String.valueOf(symbol);
294       int index = symbolIndex[symbol];
295       Color c = colors[index];
296       if (c != null && !c.equals(Color.white))
297       {
298         if (colours.get(c) == null)
299         {
300           colours.put(c, new ArrayList<String>());
301         }
302         colours.get(c).add(residue);
303       }
304       if (lowerCaseColours != null)
305       {
306         c = lowerCaseColours[index];
307         if (c != null && !c.equals(Color.white))
308         {
309           residue = residue.toLowerCase();
310           if (colours.get(c) == null)
311           {
312             colours.put(c, new ArrayList<String>());
313           }
314           colours.get(c).add(residue);
315         }
316       }
317     }
318
319     /*
320      * step 2: make a list of { A,G,R=12f9d6 } residues/colour specs
321      */
322     List<String> residueColours = new ArrayList<>();
323     for (Entry<Color, List<String>> cols : colours.entrySet())
324     {
325       boolean first = true;
326       StringBuilder sb = new StringBuilder();
327       for (String residue : cols.getValue())
328       {
329         if (!first)
330         {
331           sb.append(",");
332         }
333         sb.append(residue);
334         first = false;
335       }
336       sb.append("=");
337       /*
338        * get color as hex value, dropping the alpha (ff) part
339        */
340       String hexString = Integer.toHexString(cols.getKey().getRGB())
341               .substring(2);
342       sb.append(hexString);
343       residueColours.add(sb.toString());
344     }
345
346     /*
347      * sort and output
348      */
349     Collections.sort(residueColours);
350     return StringUtils.listToDelimitedString(residueColours, ";");
351   }
352
353   @Override
354   public boolean hasGapColour()
355   {
356     return (findColour(' ') != null);
357   }
358 }