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.



35
36
37
38
39
40
41
 
# File 'lib/proj/context.rb', line 35

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

  @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

#life_span ⇒ Object (readonly)

Returns the value of attribute life_span.



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

def life_span
  @life_span
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



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

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
17
 
# 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.instance_variable_set(:@life_span, LifeSpan.new)
  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:



144
145
146
 
# File 'lib/proj/context.rb', line 144

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:



151
152
153
 
# File 'lib/proj/context.rb', line 151

def cache
  GridCache.new(self)
end

#destroy ⇒ Object

Explicitly free the underlying PROJ context.



56
57
58
59
60
61
62
 
# File 'lib/proj/context.rb', line 56

def destroy
  @life_span.ended!
  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]



73
74
75
 
# File 'lib/proj/context.rb', line 73

def errno
  Api.proj_context_errno(self)
end

#initialize_copy(original) ⇒ Object 



43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/proj/context.rb', line 43

def initialize_copy(original)
  ObjectSpace.undefine_finalizer(self)

  super

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

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

#log_level ⇒ PJ_LOG_LEVEL

Gets the current log level

Returns:

  • (PJ_LOG_LEVEL) 


97
98
99
 
# File 'lib/proj/context.rb', line 97

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) 


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

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:



170
171
172
 
# File 'lib/proj/context.rb', line 170

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:



160
161
162
163
 
# File 'lib/proj/context.rb', line 160

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:



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/proj/context.rb', line 221

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:



260
261
262
263
264
265
266
267
268
 
# File 'lib/proj/context.rb', line 260

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) 


88
89
90
91
92
 
# File 'lib/proj/context.rb', line 88

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:



273
274
275
276
277
278
279
280
281
 
# File 'lib/proj/context.rb', line 273

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:



211
212
213
 
# File 'lib/proj/context.rb', line 211

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

#to_ptr ⇒ Object 



64
65
66
 
# File 'lib/proj/context.rb', line 64

def to_ptr
  @pointer
end

#url ⇒ String

Returns the URL endpoint to query for remote grids

Returns:

  • (String) —

    Endpoint URL

See Also:



179
180
181
 
# File 'lib/proj/context.rb', line 179

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:



188
189
190
 
# File 'lib/proj/context.rb', line 188

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) 


112
113
114
115
 
# File 'lib/proj/context.rb', line 112

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) 


122
123
124
 
# File 'lib/proj/context.rb', line 122

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:



199
200
201
202
203
 
# File 'lib/proj/context.rb', line 199

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:



133
134
135
 
# File 'lib/proj/context.rb', line 133

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