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



18
19
20
21
 
# File 'lib/proj/database.rb', line 18

def initialize(context)
  Error.validate_context!(context)
  @context = context
end

Instance Attribute Details

#context ⇒ Object (readonly)

Returns the value of attribute context.



11
12
13
 
# File 'lib/proj/database.rb', line 11

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:



104
105
106
107
 
# File 'lib/proj/database.rb', line 104

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:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/proj/database.rb', line 197

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].read_string_to_null, struct[:name].read_string_to_null)
  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:



222
223
224
 
# File 'lib/proj/database.rb', line 222

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 (PjType) —

    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:



94
95
96
97
 
# File 'lib/proj/database.rb', line 94

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:



117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/proj/database.rb', line 117

def crs_info(auth_name = nil, parameters = nil)
  out_result_count = FFI::MemoryPointer.new(:int)
  params = parameters.is_a?(Parameters) ? parameters.instance_variable_get(:@params) : parameters
  ptr = Api.proj_get_crs_info_list_from_database(self.context, auth_name, params, out_result_count)

  result = out_result_count.read_int.times.map do |index|
    index_ptr = ptr + (index * FFI::Pointer::SIZE)
    struct = Api::ProjCrsInfo.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:



185
186
187
188
 
# File 'lib/proj/database.rb', line 185

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:



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
172
173
174
175
 
# File 'lib/proj/database.rb', line 139

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:



81
82
83
 
# File 'lib/proj/database.rb', line 81

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:



28
29
30
31
32
 
# File 'lib/proj/database.rb', line 28

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:



41
42
43
44
45
46
47
 
# File 'lib/proj/database.rb', line 41

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:



54
55
56
57
 
# File 'lib/proj/database.rb', line 54

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:



235
236
237
238
239
240
241
 
# File 'lib/proj/database.rb', line 235

def suggest_code_for(object, authority, numeric_code)
  ptr = Api.proj_suggests_code_for(self.context, object, authority, numeric_code ? 1 : 0, nil)
  return nil if ptr.null?
  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:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/proj/database.rb', line 287

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:



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/proj/database.rb', line 252

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(self.context, 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::ProjUnitInfo.new(array_p_units[i])

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

  Api.proj_unit_list_destroy(pp_units)

  result
end