001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.referencing.datum;
033
034 import java.util.Map;
035 import java.util.Date;
036 import javax.measure.unit.Unit;
037 import javax.measure.quantity.Angle;
038 import javax.measure.quantity.Length;
039 import org.opengis.referencing.ObjectFactory;
040 import org.opengis.util.FactoryException;
041 import org.opengis.annotation.UML;
042
043 import static org.opengis.annotation.Specification.*;
044
045
046 /**
047 * Builds up complex {@linkplain Datum datums} from simpler objects or values.
048 * {@code DatumFactory} allows applications to make {@linkplain Datum datums}
049 * that cannot be created by a {@link DatumAuthorityFactory}. This factory is very
050 * flexible, whereas the authority factory is easier to use.
051 * So {@link DatumAuthorityFactory} can be used to make "standard" datums, and
052 * {@code DatumFactory} can be used to make "special" datums.
053 *
054 * @author Martin Desruisseaux (IRD)
055 * @version 3.0
056 * @since 1.0
057 *
058 * @see org.opengis.referencing.cs.CSFactory
059 * @see org.opengis.referencing.crs.CRSFactory
060 */
061 @UML(identifier="CS_CoordinateSystemFactory", specification=OGC_01009)
062 public interface DatumFactory extends ObjectFactory {
063 /**
064 * Creates an engineering datum.
065 *
066 * @param properties Name and other properties to give to the new object.
067 * Available properties are {@linkplain ObjectFactory listed there}.
068 * @return The datum for the given properties.
069 * @throws FactoryException if the object creation failed.
070 */
071 @UML(identifier="createLocalDatum", specification=OGC_01009)
072 EngineeringDatum createEngineeringDatum(Map<String, ?> properties)
073 throws FactoryException;
074
075 /**
076 * Creates geodetic datum from ellipsoid and (optionally) Bursa-Wolf parameters.
077 *
078 * @param properties Name and other properties to give to the new object.
079 * Available properties are {@linkplain ObjectFactory listed there}.
080 * @param ellipsoid Ellipsoid to use in new geodetic datum.
081 * @param primeMeridian Prime meridian to use in new geodetic datum.
082 * @return The datum for the given properties.
083 * @throws FactoryException if the object creation failed.
084 */
085 @UML(identifier="createHorizontalDatum", specification=OGC_01009)
086 GeodeticDatum createGeodeticDatum(Map<String, ?> properties,
087 Ellipsoid ellipsoid,
088 PrimeMeridian primeMeridian) throws FactoryException;
089
090 /**
091 * Creates an image datum.
092 *
093 * @param properties Name and other properties to give to the new object.
094 * Available properties are {@linkplain ObjectFactory listed there}.
095 * @param pixelInCell Specification of the way the image grid is associated
096 * with the image data attributes.
097 * @return The datum for the given properties.
098 * @throws FactoryException if the object creation failed.
099 */
100 ImageDatum createImageDatum(Map<String, ?> properties,
101 PixelInCell pixelInCell) throws FactoryException;
102
103 /**
104 * Creates a temporal datum from an enumerated type value.
105 * <p>
106 * <TABLE WIDTH="80%" ALIGN="center" CELLPADDING="18" BORDER="4" BGCOLOR="#FFE0B0">
107 * <TR><TD>
108 * <P align="justify"><B>Warning:</B> The argument type of this method may change
109 * in GeoAPI 3.1 release. It may be replaced by a type matching more closely
110 * either ISO 19108 (<cite>Temporal Schema</cite>) or ISO 19103.</P>
111 * </TD></TR>
112 * </TABLE>
113 *
114 * @param properties Name and other properties to give to the new object.
115 * Available properties are {@linkplain ObjectFactory listed there}.
116 * @param origin The date and time origin of this temporal datum.
117 * @return The datum for the given properties.
118 * @throws FactoryException if the object creation failed.
119 */
120 TemporalDatum createTemporalDatum(Map<String, ?> properties,
121 Date origin) throws FactoryException;
122
123 /**
124 * Creates a vertical datum from an enumerated type value.
125 *
126 * @param properties Name and other properties to give to the new object.
127 * Available properties are {@linkplain ObjectFactory listed there}.
128 * @param type The type of this vertical datum (often "geoidal").
129 * @return The datum for the given properties.
130 * @throws FactoryException if the object creation failed.
131 */
132 @UML(identifier="createVerticalDatum", specification=OGC_01009)
133 VerticalDatum createVerticalDatum(Map<String, ?> properties,
134 VerticalDatumType type) throws FactoryException;
135
136 /**
137 * Creates an ellipsoid from radius values.
138 *
139 * @param properties Name and other properties to give to the new object.
140 * Available properties are {@linkplain ObjectFactory listed there}.
141 * @param semiMajorAxis Equatorial radius in supplied linear units.
142 * @param semiMinorAxis Polar radius in supplied linear units.
143 * @param unit Linear units of ellipsoid axes.
144 * @return The ellipsoid for the given properties.
145 * @throws FactoryException if the object creation failed.
146 */
147 @UML(identifier="createEllipsoid", specification=OGC_01009)
148 Ellipsoid createEllipsoid(Map<String, ?> properties,
149 double semiMajorAxis,
150 double semiMinorAxis,
151 Unit<Length> unit) throws FactoryException;
152
153 /**
154 * Creates an ellipsoid from an major radius, and inverse flattening.
155 *
156 * @param properties Name and other properties to give to the new object.
157 * Available properties are {@linkplain ObjectFactory listed there}.
158 * @param semiMajorAxis Equatorial radius in supplied linear units.
159 * @param inverseFlattening Eccentricity of ellipsoid.
160 * @param unit Linear units of major axis.
161 * @return The ellipsoid for the given properties.
162 * @throws FactoryException if the object creation failed.
163 */
164 @UML(identifier="createFlattenedSphere", specification=OGC_01009)
165 Ellipsoid createFlattenedSphere(Map<String, ?> properties,
166 double semiMajorAxis,
167 double inverseFlattening,
168 Unit<Length> unit) throws FactoryException;
169
170 /**
171 * Creates a prime meridian, relative to Greenwich.
172 *
173 * @param properties Name and other properties to give to the new object.
174 * Available properties are {@linkplain ObjectFactory listed there}.
175 * @param longitude Longitude of prime meridian in supplied angular units East of Greenwich.
176 * @param unit Angular units of longitude.
177 * @return The prime meridian for the given properties.
178 * @throws FactoryException if the object creation failed.
179 */
180 @UML(identifier="createPrimeMeridian", specification=OGC_01009)
181 PrimeMeridian createPrimeMeridian(Map<String, ?> properties,
182 double longitude,
183 Unit<Angle> unit) throws FactoryException;
184 }