Class: Proj::Context

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

Overview

Proj 4.8 introduced the concept of a thread context object to support multi-threaded programs. The bindings automatically create one context per thread (its stored in local thread storage).

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Context

Returns a new instance of Context.



33
34
35
36
37
38
 
# File 'lib/proj/context.rb', line 33

def initialize
  @pointer = Api.proj_context_create
  ObjectSpace.define_finalizer(self, self.class.finalize(@pointer))

  @database = Database.new(self)
end

Instance Attribute Details

#database ⇒ Object (readonly)

Returns the value of attribute database.



5
6
7
 
# File 'lib/proj/context.rb', line 5

def database
  @database
end

Class Method Details

.current ⇒ Context

The context for the current thread. If a context does not exist a new one is created

Returns:

  • (Context) —

    The context for the current thread



22
23
24
 
# File 'lib/proj/context.rb', line 22

def self.current
  Thread.current[:proj_context] ||= Context.new
end

.default ⇒ Context

Returns the default Proj context. This context must only be used in the main thread In general it is better to create new contexts

Returns:

  • (Context) —

    The default context



11
12
13
14
15
16
 
# File 'lib/proj/context.rb', line 11

def self.default
  result = Context.allocate
  # The default Proj Context is represented by a null pointer
  result.instance_variable_set(:@pointer, FFI::Pointer::NULL)
  result
end

Instance Method Details

#ca_bundle_path=(path) ⇒ nil

Sets the CA Bundle path which will be used by PROJ when curl and PROJ_NETWORK are enabled.

Parameters:

  • path (String) —

    Path to CA bundle.

Returns:

  • (nil)

See Also:



139
140
141
 
# File 'lib/proj/context.rb', line 139

def ca_bundle_path=(path)
  Api.proj_context_set_ca_bundle_path(self, path.encode('utf-8'))
end

#cache ⇒ GridCache

Returns the cache used to store grid files locally

Returns:



146
147
148
 
# File 'lib/proj/context.rb', line 146

def cache
  GridCache.new(self)
end

#destroy ⇒ Object

Explicitly free the underlying PROJ context.



52
53
54
55
56
57
 
# File 'lib/proj/context.rb', line 52

def destroy
  Api.proj_context_destroy(@pointer)
  @pointer = FFI::Pointer::NULL
  ObjectSpace.undefine_finalizer(self)
  nil
end

#errno ⇒ Object

Returns the current error-state of the context. An non-zero error codes indicates an error.

See proj.org/development/reference/functions.html#c.proj_context_errno proj_context_errno

return [Integer]



68
69
70
 
# File 'lib/proj/context.rb', line 68

def errno
  Api.proj_context_errno(self)
end

#initialize_copy(original) ⇒ Object 



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/proj/context.rb', line 40

def initialize_copy(original)
  ObjectSpace.undefine_finalizer(self)

  super

  @pointer = Api.proj_context_clone(original)
  @database = Database.new(self)

  ObjectSpace.define_finalizer(self, self.class.finalize(@pointer))
end

#log_level ⇒ PJ_LOG_LEVEL

Gets the current log level

Returns:

  • (PJ_LOG_LEVEL) 


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

def log_level
  Api.proj_log_level(self, :PJ_LOG_TELL)
end

#log_level=(value) ⇒ nil

Sets the current log level

Parameters:

  • value (PJ_LOG_LEVEL)

Returns:

  • (nil) 


100
101
102
 
# File 'lib/proj/context.rb', line 100

def log_level=(value)
  Api.proj_log_level(self, value)
end

#network_enabled=(value) ⇒ Object

Enable or disable network access for downloading grid files

Parameters:

  • value (Boolean) —

    Specifies if network access should be enabled or disabled

See Also:



165
166
167
 
# File 'lib/proj/context.rb', line 165

def network_enabled=(value)
  Api.proj_context_set_enable_network(self, value ? 1 : 0)
end

#network_enabled? ⇒ Boolean

Returns if network access is enabled allowing Grid files to be downloaded

Returns:

  • (Boolean) —

    True if network access is enabled, otherwise false

See Also:



155
156
157
158
 
# File 'lib/proj/context.rb', line 155

def network_enabled?
  result = Api.proj_context_is_network_enabled(self)
  result == 1 ? true : false
end

#search_paths=(paths) ⇒ Object

Sets the paths that Proj will search when opening one of its resource files such as the proj.db database, grids, etc.

If set on the default context, they will be inherited by contexts created later.

See Also:



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/proj/context.rb', line 216

def search_paths=(paths)
  # Convert paths to C chars
  paths_ptr = paths.map do |path|
    FFI::MemoryPointer.from_string(path)
  end

  pointer = FFI::MemoryPointer.new(:pointer, paths.size)
  pointer.write_array_of_pointer(paths_ptr)

  if Api.method_defined?(:proj_context_set_search_paths)
    Api.proj_context_set_search_paths(self, paths.size, pointer)
  elsif Api.method_defined?(:pj_set_searchpath)
    Api.pj_set_searchpath(paths.size, pointer)
  end
end

#set_file_api(file_api_klass) ⇒ Object

Installs a custom file API that PROJ will use for all file operations.

The class must include FileApiCallbacks and implement the following methods that receive a file handle as their first argument:

  • open(path, access_mode) - Open a file. Return a file object or nil on error.

  • read(file, size_bytes) - Read size_bytes from file, return data string.

  • write(file, data) - Write data to file, return bytes written.

  • seek(file, offset, whence) - Seek within file.

  • tell(file) - Return current file position.

  • close(file) - Close the file.

  • exists(path) - Return true if file exists.

  • mkdir(path) - Create directory, return true on success.

  • unlink(path) - Remove file, return true on success.

  • rename(original_path, new_path) - Rename file, return true on success.

Examples:

context.set_file_api(MyCustomFileApi)

Parameters:

  • file_api_klass (Class) —

    A class whose initializer accepts a single Context argument

See Also:



255
256
257
258
259
260
261
262
263
 
# File 'lib/proj/context.rb', line 255

def set_file_api(file_api_klass)
  unless file_api_klass.kind_of?(Class)
    raise("#{file_api_klass} must be a class whose initializer has single argument which is a context")
  end

  # There is no API to "uninstall" a FileApi. Thus it needs to stay alive
  # until the context is GCed
  @file_api = file_api_klass.new(self)
end

#set_log_function(pointer = nil, &proc) ⇒ nil

Sets a custom log function

Examples:

context.set_log_function(data) do |pointer, int, message|
  ... do stuff...
end

Parameters:

  • pointer (FFI::MemoryPointer) (defaults to: nil) —

    Optional pointer to custom data

  • proc (Proc) —

    Custom logging procedure

Returns:

  • (nil) 


83
84
85
86
87
 
# File 'lib/proj/context.rb', line 83

def set_log_function(pointer = nil, &proc)
  @log_data_pointer = pointer
  @log_function = proc
  Api.proj_log_func(self, pointer, proc)
end

#set_network_api(network_api_klass) ⇒ Object

Installs a new NetworkApi

See Also:



268
269
270
271
272
273
274
275
276
 
# File 'lib/proj/context.rb', line 268

def set_network_api(network_api_klass)
  unless network_api_klass.kind_of?(Class)
    raise("#{network_api_klass} must be a class whose initializer has single argument which is a context")
  end

  # There is no API to "uninstall" a NetworkApi. Thus it needs to stay alive
  # until the context is GCed
  @network_api = network_api_klass.new(self)
end

#set_user_writable_directory(path, create: true) ⇒ Object

Sets the user directory used to save grid files.

Parameters:

  • path (String) —

    Directory path

  • create (Boolean) (defaults to: true) —

    If true, create the directory if needed. Defaults to true.

See Also:



206
207
208
 
# File 'lib/proj/context.rb', line 206

def set_user_writable_directory(path, create: true)
  Api.proj_context_set_user_writable_directory(self, path, create ? 1 : 0)
end

#to_ptr ⇒ Object 



59
60
61
 
# File 'lib/proj/context.rb', line 59

def to_ptr
  @pointer
end

#url ⇒ String

Returns the URL endpoint to query for remote grids

Returns:

  • (String) —

    Endpoint URL

See Also:



174
175
176
 
# File 'lib/proj/context.rb', line 174

def url
  Api.proj_context_get_url_endpoint(self)
end

#url=(value) ⇒ Object

Sets the URL endpoint to query for remote grids. This overrides the default endpoint in the PROJ configuration file or with the PROJ_NETWORK_ENDPOINT environment variable.

Parameters:

  • value (String) —

    Endpoint URL

See Also:



183
184
185
 
# File 'lib/proj/context.rb', line 183

def url=(value)
  Api.proj_context_set_url_endpoint(self, value)
end

#use_proj4_init_rules ⇒ Boolean

Gets if proj4 init rules are being used (i.e., support +init parameters)

Returns:

  • (Boolean) 


107
108
109
110
 
# File 'lib/proj/context.rb', line 107

def use_proj4_init_rules
  result = Api.proj_context_get_use_proj4_init_rules(self, 0)
  result == 1 ? true : false
end

#use_proj4_init_rules=(value) ⇒ nil

Sets if proj4 init rules should be used

Parameters:

  • value (Boolean)

Returns:

  • (nil) 


117
118
119
 
# File 'lib/proj/context.rb', line 117

def use_proj4_init_rules=(value)
  Api.proj_context_use_proj4_init_rules(self, value ? 1 : 0)
end

#user_directory(create = false) ⇒ String

Returns the user directory used to save grid files.

Parameters:

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

    If true create the directory if it does not exist already. Defaults to false.

Returns:

  • (String) —

    Directory

See Also:



194
195
196
197
198
 
# File 'lib/proj/context.rb', line 194

def user_directory(create = false)
  path = Api.proj_context_get_user_writable_directory(self, create ? 1 : 0)
  # Normalizes path names
  File.expand_path(path)
end

#wkt_dialect(wkt) ⇒ PJ_GUESSED_WKT_DIALECT

Guess the “dialect” of the specified WKT string

Parameters:

  • wkt (String) —

    A WKT string

Returns:

  • (PJ_GUESSED_WKT_DIALECT)

See Also:



128
129
130
 
# File 'lib/proj/context.rb', line 128

def wkt_dialect(wkt)
  Api.proj_context_guess_wkt_dialect(self, wkt)
end