001/*
002 * Copyright 2006 - 2013
003 *     Stefan Balev     <stefan.balev@graphstream-project.org>
004 *     Julien Baudry    <julien.baudry@graphstream-project.org>
005 *     Antoine Dutot    <antoine.dutot@graphstream-project.org>
006 *     Yoann Pigné      <yoann.pigne@graphstream-project.org>
007 *     Guilhelm Savin   <guilhelm.savin@graphstream-project.org>
008 * 
009 * This file is part of GraphStream <http://graphstream-project.org>.
010 * 
011 * GraphStream is a library whose purpose is to handle static or dynamic
012 * graph, create them from scratch, file or any source and display them.
013 * 
014 * This program is free software distributed under the terms of two licenses, the
015 * CeCILL-C license that fits European law, and the GNU Lesser General Public
016 * License. You can  use, modify and/ or redistribute the software under the terms
017 * of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following
018 * URL <http://www.cecill.info> or under the terms of the GNU LGPL as published by
019 * the Free Software Foundation, either version 3 of the License, or (at your
020 * option) any later version.
021 * 
022 * This program is distributed in the hope that it will be useful, but WITHOUT ANY
023 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
024 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
025 * 
026 * You should have received a copy of the GNU Lesser General Public License
027 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
028 * 
029 * The fact that you are presently reading this means that you have had
030 * knowledge of the CeCILL-C and LGPL licenses and that you accept their terms.
031 */
032package org.graphstream.ui.swingViewer.util;
033
034import org.graphstream.ui.geom.Point3;
035import org.graphstream.ui.graphicGraph.GraphicElement;
036
037public interface Camera {
038        /**
039         * The view centre (a point in graph units).
040         * 
041         * @return The view centre.
042         */
043        Point3 getViewCenter();
044
045        /**
046         * Change the view centre.
047         * 
048         * @param x
049         *            The new abscissa.
050         * @param y
051         *            The new ordinate.
052         * @param z
053         *            The new depth.
054         */
055        void setViewCenter(double x, double y, double z);
056
057        /**
058         * The portion of the graph visible.
059         * 
060         * @return A real for which value 1 means the graph is fully visible and
061         *         uses the whole view port.
062         */
063        double getViewPercent();
064
065        /**
066         * Zoom the view.
067         * 
068         * @param percent
069         *            Percent of the graph visible.
070         */
071        void setViewPercent(double percent);
072
073        /**
074         * The current rotation angle.
075         * 
076         * @return The rotation angle in degrees.
077         */
078        double getViewRotation();
079
080        /**
081         * Rotate the view around its centre point by a given theta angles (in
082         * degrees).
083         * 
084         * @param theta
085         *            The rotation angle in degrees.
086         */
087        void setViewRotation(double theta);
088
089        /**
090         * A number in GU that gives the approximate graph size (often the diagonal
091         * of the graph). This allows to compute displacements in the graph as
092         * percent of its overall size. For example this can be used to move the
093         * view centre.
094         * 
095         * @return The graph estimated size in graph units.
096         */
097        double getGraphDimension();
098
099        /**
100         * Remove the specified graph view port.
101         * 
102         * @see #setGraphViewport(double, double, double, double)
103         */
104        void removeGraphViewport();
105
106        /**
107         * Specify exactly the minimum and maximum points in GU that are visible
108         * (more points may be visible due to aspect-ratio constraints).
109         * 
110         * @param minx
111         *            The minimum abscissa visible.
112         * @param miny
113         *            The minimum ordinate visible.
114         * @param maxx
115         *            The maximum abscissa visible.
116         * @param maxy
117         *            The maximum abscissa visible.
118         * @see #removeGraphViewport()
119         */
120        void setGraphViewport(double minx, double miny, double maxx, double maxy);
121
122        /**
123         * Reset the view to the automatic mode.
124         */
125        void resetView();
126
127        /**
128         * Set the bounds of the graphic graph in GU. Called by the Viewer.
129         * 
130         * @param minx
131         *            Lowest abscissa.
132         * @param miny
133         *            Lowest ordinate.
134         * @param minz
135         *            Lowest depth.
136         * @param maxx
137         *            Highest abscissa.
138         * @param maxy
139         *            Highest ordinate.
140         * @param maxz
141         *            Highest depth.
142         */
143        void setBounds(double minx, double miny, double minz, double maxx,
144                        double maxy, double maxz);
145
146        /**
147         * Get the {@link GraphMetrics} object linked to this Camera. It can be used
148         * to convert pixels to graphic units and vice versa.
149         * 
150         * @return a GraphMetrics instance
151         */
152        GraphMetrics getMetrics();
153        
154        /**
155         * Enable or disable automatic adjustment of the view to see the entire
156         * graph.
157         * 
158         * @param on
159         *            If true, automatic adjustment is enabled.
160         */
161        void setAutoFitView(boolean on);
162
163        /**
164         * Transform a point in graph units into pixels.
165         * 
166         * @return The transformed point.
167         */
168        Point3 transformGuToPx(double x, double y, double z);
169        
170        /**
171         * Return the given point in pixels converted in graph units (GU) using the
172         * inverse transformation of the current projection matrix. The inverse
173         * matrix is computed only once each time a new projection matrix is
174         * created.
175         * 
176         * @param x
177         *            The source point abscissa in pixels.
178         * @param y
179         *            The source point ordinate in pixels.
180         * @return The resulting points in graph units.
181         */
182        Point3 transformPxToGu(double x, double y);
183        
184        /**
185         * True if the element would be visible on screen. The method used is to
186         * transform the center of the element (which is always in graph units)
187         * using the camera actual transformation to put it in pixel units. Then to
188         * look in the style sheet the size of the element and to test if its
189         * enclosing rectangle intersects the view port. For edges, its two nodes
190         * are used.
191         * 
192         * @param element
193         *            The element to test.
194         * @return True if the element is visible and therefore must be rendered.
195         */
196        boolean isVisible(GraphicElement element);
197}