1 // This is core/vil/vil_new.h
2 #ifndef vil_new_h_
3 #define vil_new_h_
4 //:
5 // \file
6 // \brief Make a new image.
7 //
8 // If it's very big, it might make a disk image, with a temporary name in which
9 // case "prototype" will be consulted about issues such as file format etc. If
10 // you want more control over the exact disk format, use one of the routines
11 // with more than 4 arguments.
12 //
13 // \author awf@robots.ox.ac.uk
14 // \date 26 Feb 00
15 //
16 // \verbatim
17 // Modifications
18 // 16 Feb 2000 AWF - Initial version.
19 // 25 Sep 2002 Ian Scott - convert to vil.
20 // 30 Mar 2007 Peter Vanroose- Removed deprecated vil_new_image_view_j_i_plane
21 // \endverbatim
22
23 #include "vil_fwd.h"
24 #include "vil_image_resource.h"
25 #include "vil_blocked_image_resource.h"
26 #include "vil_pyramid_image_resource.h"
27 #include "vil_image_view.h"
28 #include <vxl_config.h>
29 #include <vcl_compiler_detection.h>
30
31 //: Make a new image of given format.
32 // If the format is not scalar, the number of planes must be 1. When you create
33 // a multi-component image in this way, the vil_image_resource API will treat
34 // it as a scalar pixel image with multiple planes. (This doesn't affect the
35 // underlying data storage.)
36 // \relatesalso vil_image_resource
37 vil_image_resource_sptr vil_new_image_resource(unsigned ni, unsigned nj, unsigned nplanes,
38 vil_pixel_format format);
39
40 //: Make a new image of given format with interleaved planes.
41 // The format must be scalar.
42 // \relatesalso vil_image_resource
43 vil_image_resource_sptr vil_new_image_resource_interleaved(unsigned ni, unsigned nj,
44 unsigned nplanes,
45 vil_pixel_format format);
46
47 //: Make a new image resource that is a wrapper on an existing view's data.
48 // \note The output will be a shallow copy of the input, so changing the pixel values
49 // of one may change the pixel value of the other. Thanks to the magic of smart pointers,
50 // the output will remain valid even if you destroy the input. When you wrap
51 // a multi-component image in this way, the vil_image_resource API will treat
52 // it as a scalar pixel image with multiple planes. (This doesn't affect the
53 // underlying data storage.)
54 // \relatesalso vil_image_resource
55 vil_image_resource_sptr vil_new_image_resource_of_view(vil_image_view_base const& view);
56
57
58 //: Make a new image, similar format to the prototype.
59 // \relatesalso vil_image_resource
60 vil_image_resource_sptr vil_new_image_resource(unsigned ni, unsigned nj,
61 vil_image_resource_sptr const& prototype);
62
63 //: Make a new image.
64 // \relatesalso vil_image_resource
65 vil_image_resource_sptr vil_new_image_resource(vil_stream* os,
66 unsigned ni, unsigned nj,
67 unsigned nplanes,
68 vil_pixel_format format,
69 char const* file_format = nullptr);
70
71 //: Make a new image.
72 // \relatesalso vil_image_resource
73 vil_image_resource_sptr vil_new_image_resource(char const* filename,
74 unsigned ni, unsigned nj,
75 unsigned nplanes,
76 vil_pixel_format format,
77 char const* file_format = nullptr);
78
79 //: Make a new vil_image_resource, writing to file "filename", size ni x nj, copying pixel format etc from "prototype".
80 // \relatesalso vil_image_resource
81 vil_image_resource_sptr vil_new_image_resource(char const* filename,
82 unsigned ni, unsigned nj,
83 unsigned nplanes,
84 vil_image_resource_sptr const &prototype,
85 char const* format = nullptr);
86
87 //: Make a new vil_image_resource, writing to stream "os", size ni x nj, copying pixel format etc from "prototype".
88 // \relatesalso vil_image_resource
89 vil_image_resource_sptr vil_new_image_resource(vil_stream* os,
90 unsigned ni, unsigned nj,
91 unsigned nplanes,
92 vil_image_resource_sptr const& prototype,
93 char const* file_format = nullptr);
94 //: Make a new blocked resource file
95 vil_blocked_image_resource_sptr
96 vil_new_blocked_image_resource(vil_stream* os, unsigned ni, unsigned nj,
97 unsigned nplanes, vil_pixel_format format,
98 unsigned size_block_i, unsigned size_block_j,
99 char const* file_format = nullptr);
100
101 //: Make a new blocked resource file
102 vil_blocked_image_resource_sptr
103 vil_new_blocked_image_resource(char const* filename, unsigned ni, unsigned nj,
104 unsigned nplanes, vil_pixel_format format,
105 unsigned size_block_i, unsigned size_block_j,
106 char const* file_format = nullptr);
107
108 //: create a blocked interface around any image resource
109 // For zero size blocks, appropriate default blocking is created
110 vil_blocked_image_resource_sptr
111 vil_new_blocked_image_facade(const vil_image_resource_sptr& src,
112 const unsigned size_block_i=0,
113 const unsigned size_block_j=0);
114 //: Make a new cached resource
115 vil_blocked_image_resource_sptr
116 vil_new_cached_image_resource(const vil_blocked_image_resource_sptr& bir,
117 const unsigned cache_size = 100);
118
119
120 //: Make a new pyramid image resource for writing.
121 // Any number of pyramid layers can be inserted and with any scale.
122 // Image resources that duplicate existing scales are not inserted.
123 vil_pyramid_image_resource_sptr
124 vil_new_pyramid_image_resource(char const* file_or_directory,
125 char const* file_format);
126
127 //: Construct a pyramid image resource from a base image.
128 // All levels are stored in the same resource file. Each level has the same
129 // scale ratio (0.5) to the preceding level. Level 0 is the original
130 // base image. The resource is returned open for reading.
131 // The temporary directory is for storing intermediate image
132 // resources during the construction of the pyramid. Files are
133 // be removed from the directory after completion. If temp_dir is 0
134 // then the intermediate resources are created in memory.
135 vil_pyramid_image_resource_sptr
136 vil_new_pyramid_image_from_base(char const* filename,
137 vil_image_resource_sptr const& base_image,
138 unsigned nlevels,
139 char const* file_format,
140 char const* temp_dir);
141
142 //: Construct a new pyramid image resource from a base image
143 // The result is a directory containing separate images for each
144 // pyramid level. Each level has the same scale ratio (0.5) to the
145 // preceding level and is created using level_file_format.
146 // Level 0 is the original base image. If copy_base is false, then Level 0
147 // is already present in the directory and is used without modification.
148 // Each pyramid file in the directory is
149 // named filename + "level_index", e.g. R0, R1, ... Rn.
150 vil_pyramid_image_resource_sptr
151 vil_new_pyramid_image_list_from_base(char const* directory,
152 vil_image_resource_sptr const& base_image,
153 unsigned nlevels,
154 bool copy_base,
155 char const* level_file_format,
156 char const* filename);
157
158 #if 0 // deprecated
159 //: Create a new image view whose plane step is 1.
160 // Pixel data type is the type of the last (dummy) argument.
161 // i_step will be nplanes, j_step will be nplanes x ni.
162 // \relatesalso vil_image_view
163 // \deprecated in favour of vil_image_view constructor
164 template <class T>
165 vil_image_view<T> vil_new_image_view_j_i_plane(unsigned ni, unsigned nj, unsigned nplanes, T /*dummy*/)
166 {
167 VXL_DEPRECATED_MACRO("vil_new_image_view_j_i_plane");
168 vil_pixel_format fmt = vil_pixel_format_of(T());
169 vil_memory_chunk_sptr chunk = new vil_memory_chunk(ni*nj*nplanes*sizeof(T),
170 vil_pixel_format_component_format(fmt));
171 return vil_image_view<T>(chunk, reinterpret_cast<T*>(chunk->data()), ni, nj, nplanes, nplanes, nplanes*ni, 1);
172 }
173 #endif // 0
174
175 //: Create a new image view whose j_step is 1.
176 // Pixel data type is the type of the last (dummy) argument.
177 // i_step will be nj, planestep will be ni x nj.
178 // \relatesalso vil_image_view
179 template <class T>
vil_new_image_view_plane_i_j(unsigned ni,unsigned nj,unsigned nplanes,T)180 vil_image_view<T> vil_new_image_view_plane_i_j(unsigned ni, unsigned nj, unsigned nplanes, T /*dummy*/)
181 {
182 vil_pixel_format fmt = vil_pixel_format_of(T());
183 vil_memory_chunk_sptr chunk = new vil_memory_chunk(ni*nj*nplanes*sizeof(T),
184 vil_pixel_format_component_format(fmt));
185 return vil_image_view<T>(chunk, reinterpret_cast<T*>(chunk->data()), ni, nj, nplanes, nj, 1, nj*ni);
186 }
187
188 //: Create a new image view whose plane step is 1 and whose j_step is nplanes.
189 // Pixel data type is the type of the last (dummy) argument.
190 // i_step will be nplanes x nj.
191 // \relatesalso vil_image_view
192 template <class T>
vil_new_image_view_i_j_plane(unsigned ni,unsigned nj,unsigned nplanes,T)193 vil_image_view<T> vil_new_image_view_i_j_plane(unsigned ni, unsigned nj, unsigned nplanes, T /*dummy*/)
194 {
195 vil_pixel_format fmt = vil_pixel_format_of(T());
196 vil_memory_chunk_sptr chunk = new vil_memory_chunk(ni*nj*nplanes*sizeof(T),
197 vil_pixel_format_component_format(fmt));
198 return vil_image_view<T>(chunk, reinterpret_cast<T*>(chunk->data()), ni, nj, nplanes, nplanes*nj, nplanes, 1);
199 }
200
201 //: Create a shallow copy of an image and wrap it in a vil_image_view_base_sptr
202 // \note vil_image_view_base_sptr almost certainly doesn't behave as
203 // you would expect, and this function should really only be used by experts.
204 // \relatesalso vil_image_view
205 vil_image_view_base_sptr vil_new_image_view_base_sptr(const vil_image_view_base&);
206
207
208 #if defined(_WIN32) && VXL_USE_WIN_WCHAR_T
209 //: Make a new image.
210 // \relatesalso vil_image_resource
211 vil_image_resource_sptr vil_new_image_resource(vil_stream* os,
212 unsigned ni, unsigned nj,
213 unsigned nplanes,
214 vil_pixel_format format,
215 wchar_t const* file_format = 0);
216 //: Make a new image.
217 // \relatesalso vil_image_resource
218 vil_image_resource_sptr vil_new_image_resource(wchar_t const* filename,
219 unsigned ni, unsigned nj,
220 unsigned nplanes,
221 vil_pixel_format format,
222 wchar_t const* file_format = 0);
223
224 //: Make a new vil_image_resource, writing to file "filename", size ni x nj, copying pixel format etc from "prototype".
225 // \relatesalso vil_image_resource
226 vil_image_resource_sptr vil_new_image_resource(wchar_t const* filename,
227 unsigned ni, unsigned nj,
228 unsigned nplanes,
229 vil_image_resource_sptr const &prototype,
230 wchar_t const* format = 0);
231
232 #endif //defined(_WIN32) && VXL_USE_WIN_WCHAR_T
233
234
235 #endif // vil_new_h_
236