[libdc1394-devel] Re: Camwire - generic camera API

[Johann S. <j.s...@ir...>]

Hi Brad

Thanks for your insights and comments.  It's good to have someone look 
at it from a fresh perspective.

Camwire started out as a modest little wrapper around libdc1394 for 
some of my colleagues who did not want to spend any time learning 
aobut IEEE 1394 things.  So from the outset it was meant to be simple 
rather than comprehensive.

I appreciate that your proposed changes need not add much complexity 
to the interface and may even simplify it in places.  It will however 
require a major rewrite of much of the code.  I don't have much time 
myself to extend and improve Camwire.  It now does more or less what 
we originally wanted it to do.  I suspect that it will also be 
sufficient for many others and that is why I made it publically available.

I would be happy to implement submitted patches.  I would also be 
happy if anyone wanted to take the code further into a bigger project. 
    Perhaps we may decide to split the project into a keep-it-simple 
original-but-limited version and a more ambitious and flexible version 
which hides the implementation details behind DSOs.

What do you think?

Regards,
Johann


Brad wrote:
> I like the idea behind Camwire, but I was thinking that if you are 
> wanting a significant base of imaging devices to interface with I could 
> suggest a few changes that could be made.  Almost all of these are based 
> on my opinion and past experiences in working with scientifc and other 
> types of imaging.
> 
> I would like to apologise in advance if you are not wanting to get a 
> list of what people would think an optimal API would look like in which 
> case you may stop reading.
> 
> The basis of this email is based solely on my opinion and experiences of 
> what I would consider to be my API of choice.  I'm looking at the API 
> from the perspective that it is an API should control a Camera (Digital 
> SLR, Scientific, Machine Vision, Microscopy, etc ...) regardless of 
> type, feature set or interface (Firewire (IIDC, proprietary), USB, 
> FrameGrabber, ...) with a computer.  Additionally, it is my opinion that 
> it should also be possible to extend such an API to other Operating 
> Systems should that be a desire (Mac, Windows, VxWorks, whatever.)
> 
> GENERIC CAMERA INTERFACE MODULES
> It would probably be a good and easy to implement style if we wrote the 
> generic Camera API to use DSO's to call the appropriate interface 
> types.  For example, there could be an IIDC dso that knew how to talk to 
> IIDC cameras, one for USB and so on.  The Generiic Camera API could then 
> look in a specific location (say /opt/camwire/dso) for modules that 
> represent camera interfaces.  It would make other people / parties job 
> easier to interface their API / Camera system with the Generic Camera 
> API without having to actually modify the API itself.
> 
> SETTING AND GETTING CAMERA FEATURES / SETTINGS
> I believe that having seperate functions to set the different settings 
> that the camera may be set to is a little overkill.  When camera's 
> support features like Roi's (Some Multiple Roi's), Readout Speeds, 
> Binning Modes, Trigger Types, Shutter Modes, Image Formats (etc...) 
> having a seperate function for each possible setting becomes a lot of 
> work to maintain and implement, especially when you try to find what 
> values (range or sparse) are actually supported by the camera.
> 
> Myself I would structure that part of the code as a function that is 
> able to set a structure that contains the actual settings that will be 
> stored (should be opaque.)   The actual function that sets the structure 
> would accept an enumeration that describes which parameter or setting is 
> being set by the function.  Operating in this manner we have an API that 
> does not have to change much as new features are supported in terms of 
> the actual API (just add new enumerations.)
> 
> Additionally, we could add a function to report the largest supported 
> enumeration along with its textual name for user applications so that 
> some applications (using those functions) wouldn't have to be recompiled 
> to use new camera features as they come out and the lower layers are 
> updated.
> 
> Additionally, for settings such as Triggering I would enumerate them to 
> allow to set the following types: Edge High, Edge Low, Pulse High, Pulse 
> Low, Software and (None or Internal or Freerun...) intead of seperate 
> functions to set edge state, and enable external or internal trigger 
> (cause there are other types than just external and multiple external 
> types.)
> 
> -- Here is an example of how I would interface to settings changes
> // These of course will have other typed functions such as u64 and s32.
> set_parameter_u32 (tcamera_settings*, tcamera_parameter, uint32 parameter)
> get_parameter_u32 (tcamera_settings*, tcamera_parameter, uint32* parameter)
> is_parameter_supported_u32 (tcamera_settings*, tcamera_parameter)
> is_parameter_sparse_table_u32 (tcamera_settings*, tcamera_parameter)
> is_parameter_range_table_u32 (tcamera_settings*, tcamera_parameter)
> get_parameter_sparse_table_u32 (tcamera_settings*, tcamera_parameter, 
> uint32* ptable, uint32 usize)
> get_parameter_range_table_u32 (tcamera_settings*, tcamera_parameter, 
> uint32* ptable, uint32 usize)
> 
> // Send the settings to the camera to be used.
> send_settings_to_camera (tcamera_handle, tcamera_settings*);
> get_default_settings (tcamera_handle, tcamera_settings*)
> -- End example settings interface
> 
> Some cameras have things like intensity and scale of the image change 
> from normal change as certain settings are enabled.  We may want to have 
> a function to handle that.  Maybe something like 
> get_x_scale_from_normal, get_x_intensity_from_normal or something 
> similar would be appropriate.  Settings such as Binning modify the 
> intensity and features such as faster viewing modes (A faster view mode 
> at a lower quality.) affects both intensity and scaleing.  I have not 
> seen any API's that have functions to support this, but have dealt with 
> ones that state with Camera X and setting Y use scale of 1.4, but Camera 
> Z and Setting Y use scale of 1.6.
> 
> OPENING AND CLOSING CAMERAS
> What we could do here is have an list_cameras function that lists all 
> cameras found on the system. (1394, USB, Framegrabber Cameras would all 
> appear on the same list.) and the user application could select which 
> camera to use when calling open_camera(cameraid)
> 
> RETRIEVING FRAMES
>  From your interface it looks as if Camwire owns the buffers that the 
> frames are copied into (the number set by the calling application.)  I 
> think that it would be better if the frames were in fact owned by the 
> calling application and that the calling application could queue frames 
> up as it wanted.
> 
> For ease of use there could be a synchronous version of the frame 
> retrieval that could be called grab_frame or grab_frame_sync.
> 
> We could then to an asynchronous version of frame retrieval that would 
> be faster and could just use queues internally to hold onto the frame.  
> Upon completion of the frame being filled, a callback is called.  Of 
> course we would need a function like abort_frames or cancel_frames 
> incase the user wanted to cease operation.
> 
> These are my opinions.  Please let me know what you think.  If you like 
> my ideas, have questions or would like more detailed descriptions feel 
> free to mail me on or off list.
> 
> Regards,
> Brad (br...@je...)
> 

-- 
^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^
Johann Schoonees                         Imaging & Sensing Team
Industrial Research Limited, PO Box 2225, Auckland, New Zealand
Phone +64 9 9203679 Fax +64 9 3028106 http://www.is.irl.cri.nz/