001 /* 002 * Histogram3D 003 * 004 * Copyright (c) 2001, 2002 Marco Schmidt <marcoschmidt@users.sourceforge.net> 005 * All rights reserved. 006 */ 007 008 package net.sourceforge.jiu.color.data; 009 010 /** 011 * An interface for classes that store three-dimensional histograms. 012 * Histograms count the occurrence of values, so a three-dimensional 013 * histogram has counters for three-dimensional values. 014 * The 3D histograms are used (as an example) to count the occurrence of 015 * each color in an RGB image. 016 * 017 * @author Marco Schmidt 018 * @see Histogram1D 019 */ 020 public interface Histogram3D 021 { 022 /** 023 * Sets all counters to zero. 024 */ 025 void clear(); 026 027 /** 028 * Returns the counter value of (index1, index2, index3). 029 * @param index1 first of the three values forming the threedimensional index 030 * @param index2 second of the three values forming the threedimensional index 031 * @param index3 three of the three values forming the threedimensional index 032 * @return the counter value of the desired index 033 * @throws IllegalArgumentException if the index formed by the arguments is invalid 034 */ 035 int getEntry(int index1, int index2, int index3); 036 037 /** 038 * Returns the maximum index value for one of the three indexes. 039 * @throws IllegalArgumentException if the index formed by the arguments is invalid 040 */ 041 int getMaxValue(int index); 042 043 /** 044 * Returns the number of used entries (those entries with 045 * a counter value larger than zero). 046 * @return number of non-zero counter values 047 */ 048 int getNumUsedEntries(); 049 050 /** 051 * Increases the counter value of (index1, index2, index3) by one. 052 * This method can easily be implemented by the one-liner 053 * <code>setEntry(index1, index2, index3, getEntry(index1, index2, index3) + 1);</code> 054 * However, this method is expected to be faster in some contexts. 055 * 056 * @param index1 first of the three values forming the threedimensional index 057 * @param index2 second of the three values forming the threedimensional index 058 * @param index3 three of the three values forming the threedimensional index 059 * @return the counter value of the desired index 060 * @throws IllegalArgumentException if the index formed by the arguments is invalid 061 */ 062 void increaseEntry(int index1, int index2, int index3); 063 064 /** 065 * Sets the counter value of (index1, index2, index3) to newValue. 066 * 067 * @param index1 first of the three values forming the threedimensional index 068 * @param index2 second of the three values forming the threedimensional index 069 * @param index3 three of the three values forming the threedimensional index 070 * @param newValue the counter value that is assigned to the argument index 071 * @throws IllegalArgumentException if the index formed by the first three arguments is invalid 072 */ 073 void setEntry(int index1, int index2, int index3, int newValue); 074 }