Class: Proj::Database

Inherits:
Object
  • Object
show all
Defined in:
lib/proj/database.rb

Overview

This class provides access the Proj SQLite database called proj.db. The database stores transformation information that must be accessible for the library to work properly.

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(context) ⇒ Database

Create a new database instance to query the Proj database

Parameters:

  • context (Context) —

    A proj Context



16
17
18
 
# File 'lib/proj/database.rb', line 16

def initialize(context)
  @context = context
end

Instance Attribute Details

#context ⇒ Object (readonly)

Returns the value of attribute context.



9
10
11
 
# File 'lib/proj/database.rb', line 9

def context
  @context
end

Instance Method Details

#authorities ⇒ Array<Strings>

Return a list of authorities used in the database

Returns:

  • (Array<Strings>) —

    List of authorities

See Also:



101
102
103
104
 
# File 'lib/proj/database.rb', line 101

def authorities
  ptr = Api.proj_get_authorities_from_database(self.context)
  Strings.new(ptr)
end

#celestial_bodies(authority = nil) ⇒ Array<CelestialBody>

Returns a list of celestial bodies from the database

Parameters:

  • authority (String) (defaults to: nil) —

    Authority name, used to restrict the search. Set to nil for all authorities.

Returns:

See Also:



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/proj/database.rb', line 193

def celestial_bodies(authority = nil)
  out_result_count = FFI::MemoryPointer.new(:int)
  ptr = Api.proj_get_celestial_body_list_from_database(self.context, authority, out_result_count)

  body_ptrs = ptr.read_array_of_pointer(out_result_count.read_int)
  result = body_ptrs.map do |body_ptr|
    # First read the pointer to a structure
    struct = Api::ProjCelestialBodyInfo.new(body_ptr)

    # Now map this to a Ruby Struct
    CelestialBody.new(struct[:auth_name], struct[:name])
  end

  Api.proj_celestial_body_list_destroy(ptr)

  result
end

#celestial_body_name(object) ⇒ String

Return the name of the celestial body of the specified object.

Parameters:

  • object (PjObject) —

    Object of type CRS, Datum or Ellipsoid. Must not be nil.

Returns:

  • (String) —

    The name of the celestial body or nil

See Also:



218
219
220
 
# File 'lib/proj/database.rb', line 218

def celestial_body_name(object)
  Api.proj_get_celestial_body_name(self.context, object)
end

#codes(auth_name, pj_type, allow_deprecated = false) ⇒ Strings

Returns the set of authority codes of the given object type.

Parameters:

  • auth_name (String) —

    Authority name. Must not be nil.

  • pj_type (PJ_TYPE) —

    Proj Object type.

  • allow_deprecated (Boolean) (defaults to: false) —

    Specifies if deprecated objects should be returned. Default is false.

Returns:

  • (Strings) —

    Returned authority codes

See Also:



91
92
93
94
 
# File 'lib/proj/database.rb', line 91

def codes(auth_name, pj_type, allow_deprecated = false)
  ptr = Api.proj_get_codes_from_database(self.context, auth_name, pj_type, allow_deprecated ? 1 : 0)
  Strings.new(ptr)
end

#crs_info(auth_name = nil, parameters = nil) ⇒ Array<CrsInfo>

Enumerate CRS infos from the database, taking into account various criteria.

Parameters:

  • auth_name (String) (defaults to: nil) —

    Authority name. Use nil to specify all authorities

  • parameters (Parameters) (defaults to: nil) —

    Parameters to specify search criteria. May be nil

Returns:

  • (Array<CrsInfo>) —

    Returned crs infos

See Also:



114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/proj/database.rb', line 114

def crs_info(auth_name = nil, parameters = nil)
  out_result_count = FFI::MemoryPointer.new(:int)
  ptr = Api.proj_get_crs_info_list_from_database(self.context, auth_name, parameters, out_result_count)

  result = out_result_count.read_int.times.map do |index|
    index_ptr = ptr + (index * FFI::Pointer::SIZE)
    struct = Api::PROJ_CRS_INFO.new(index_ptr.read_pointer)
    CrsInfo.from_proj_crs_info(struct)
  end

  Api.proj_crs_info_list_destroy(ptr)
  result
end

#geoid_models(authority, code) ⇒ Strings

Returns a list of geoid models available

Parameters:

  • authority (String) —

    Authority name into which the object will be inserted. Must not be nil

  • code (Integer) —

    Code with which the object will be inserted.Must not be nil

Returns:

  • (Strings) —

    List of insert statements

See Also:



181
182
183
184
 
# File 'lib/proj/database.rb', line 181

def geoid_models(authority, code)
  ptr = Api.proj_get_geoid_models_from_database(self.context, authority, code, nil)
  Strings.new(ptr)
end

#grid(name) ⇒ Grid

Returns information about a Grid from the database

Parameters:

  • name (String) —

    The name of the grid

Returns:

See Also:



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/proj/database.rb', line 135

def grid(name)
  out_full_name = FFI::MemoryPointer.new(:string)
  out_package_name = FFI::MemoryPointer.new(:string)
  out_url = FFI::MemoryPointer.new(:string)
  out_downloadable = FFI::MemoryPointer.new(:int)
  out_open_license = FFI::MemoryPointer.new(:int)
  out_available = FFI::MemoryPointer.new(:int)

  result = Api.proj_grid_get_info_from_database(self.context, name,
                                                out_full_name, out_package_name, out_url,
                                                out_downloadable, out_open_license, out_available)

  if result == 1
    full_name_ptr = out_full_name.read_pointer
    package_name_ptr = out_package_name.read_pointer
    url_ptr = out_url.read_pointer

    downloadable_ptr = out_downloadable
    open_license_ptr = out_open_license
    available_ptr = out_available

    full_name = full_name_ptr.read_string_to_null
    package_name = package_name_ptr.read_string_to_null
    url = url_ptr.read_string_to_null

    downloadable = downloadable_ptr.read_int == 1 ? true : false
    open_license = open_license_ptr.read_int == 1 ? true : false
    available = available_ptr.read_int == 1 ? true : false

    Grid.new(name, self.context,
             full_name: full_name, package_name: package_name,
             url: url ? URI(url) : nil,
             downloadable: downloadable, open_license: open_license, available: available)
  else
    Error.check_context(self.context)
  end
end

#metadata(key) ⇒ String

Return a metadata from the database.

Parameters:

  • key (String) —

    The name of the metadata item. Must not be nil Available keys:

    DATABASE.LAYOUT.VERSION.MAJOR
DATABASE.LAYOUT.VERSION.MINOR
EPSG.VERSION
EPSG.DATE
ESRI.VERSION
ESRI.DATE
IGNF.SOURCE
IGNF.VERSION
IGNF.DATE
NKG.SOURCE
NKG.VERSION
NKG.DATE
PROJ.VERSION
PROJ_DATA.VERSION

Returns:

  • (String) —

    Returned metadata

See Also:



78
79
80
 
# File 'lib/proj/database.rb', line 78

def metadata(key)
  Api.proj_context_get_database_metadata(self.context, key)
end

#path ⇒ Object

Returns the path the Proj database

return [String]

See Also:



25
26
27
28
29
 
# File 'lib/proj/database.rb', line 25

def path
  if Api.method_defined?(:proj_context_get_database_path)
    Api.proj_context_get_database_path(self.context)
  end
end

#path=(value) ⇒ Database

Sets the path to the Proj database

Parameters:

  • value (String) —

    Path to the proj database

Returns:

  • (Database) —

    Returns reference to the current database instance

See Also:



38
39
40
41
42
43
44
 
# File 'lib/proj/database.rb', line 38

def path=(value)
  result = Api.proj_context_set_database_path(self.context, value, nil, nil)
  unless result == 1
    Error.check_context(self.context)
  end
  self
end

#structure ⇒ Array<Strings>

Returns SQL statements to run to initiate a new valid auxiliary empty database.

Returns:

  • (Array<Strings>) —

    List of sql statements

See Also:



51
52
53
54
 
# File 'lib/proj/database.rb', line 51

def structure
  ptr = Api.proj_context_get_database_structure(self.context, nil)
  Strings.new(ptr)
end

#suggest_code_for(object, authority, numeric_code) ⇒ String

Suggests a database code for the specified object.

Parameters:

  • object (PjObject) —

    Object for which to suggest a code.

  • authority (String) —

    Authority name into which the object will be inserted.

  • numeric_code (Boolean) —

    Whether the code should be numeric, or derived from the object name.

Returns:

  • (String) —

    The suggested code

See Also:



231
232
233
234
235
236
 
# File 'lib/proj/database.rb', line 231

def suggest_code_for(object, authority, numeric_code)
  ptr = Api.proj_suggests_code_for(self.context, object, authority, numeric_code ? 1 : 0, nil)
  result = ptr.read_string_to_null
  Api.proj_string_destroy(ptr)
  result
end

#unit(auth_name, code) ⇒ Unit

Returns information for a unit of measure from a database lookup

Parameters:

  • auth_name (String) —

    Authority name

  • code (String) —

    Unit of measure code

Returns:

See Also:



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/proj/database.rb', line 282

def unit(auth_name, code)
  out_name = FFI::MemoryPointer.new(:string)
  out_conv_factor = FFI::MemoryPointer.new(:double)
  out_category = FFI::MemoryPointer.new(:string)

  result = Api.proj_uom_get_info_from_database(self.context, auth_name, code,
                                                out_name, out_conv_factor , out_category)

  if result == 1
    name_ptr = out_name.read_pointer
    conv_factor_ptr = out_conv_factor
    category_ptr = out_category.read_pointer

    name = name_ptr.read_string_to_null
    conv_factor = conv_factor_ptr.read_double
    category = category_ptr.read_string_to_null

    Unit.new(auth_name, code, name, category, conv_factor, nil, false)
  else
    Error.check_context(self.context)
  end
end

#units(auth_name: nil, category: nil, allow_deprecated: false) ⇒ Array<Unit>

Returns a list of units from the database

Parameters:

  • auth_name (String) (defaults to: nil) —

    Authority name, used to restrict the search. Or nil for all authorities.

  • category (String) (defaults to: nil) —

    Filter by category, if this parameter is not nil. Category is one of “linear”, “linear_per_time”, “angular”, “angular_per_time”, “scale”, “scale_per_time” or “time

  • allow_deprecated (Boolean) (defaults to: false) —

    Whether deprecated units should also be returned. Default false.

Returns:

  • (Array<Unit>) —

    Array of units

See Also:



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/proj/database.rb', line 247

def units(auth_name: nil, category: nil, allow_deprecated: false)
  # Create pointer to read the count output parameter
  out_result_count = FFI::MemoryPointer.new(:int)

  # Result is an array of pointers to structures
  pp_units = Api.proj_get_units_from_database(Context.current, auth_name, category, allow_deprecated ? 1 : 0, out_result_count)
  count = out_result_count.read(:int)
  array_p_units = pp_units.read_array_of_pointer(count)

  result = Array.new(count)
  count.times do |i|
    unit_info = Api::PROJ_UNIT_INFO.new(array_p_units[i])

    result[i] = Unit.new(unit_info[:auth_name],
                         unit_info[:code],
                         unit_info[:name],
                         unit_info[:category],
                         unit_info[:conv_factor],
                         unit_info[:proj_short_name],
                         unit_info[:deprecated])
  end

  Api.proj_unit_list_destroy(pp_units)

  result
end