DICOM standard

Posted on by

Last update : May 31, 2016

DICOM (Digital Imaging and Communications in Medicine) is a software integration standard that is used in Medical Imaging. It’s success relies on the ability of modern imaging equipment, manufactured by many different vendors, to seamlessly collaborate and integrate together. Medical imaging equipments are called Imaging Modalities and include X-Rays, Ultrasound (US), Computed Radiography (CR), Computed Tomography (CT), Magnetic Resonance Imaging (MRI), Endoscopie (ES),  and others.

DICOM standard

The Digital Imaging and Communications in Medicine (DICOM) standard (now ISO 12052) was first conceived by the American College of Radiology (ACR) and the National Electrical Manufacturers Association (NEMA) in 1983. DICOM changed the face of clinical medicin. The release 3 of the standard was published in 1993 and since then an updated version is edited every year.  The current version is PS3-2016b. The DICOM standard is often considered to be be very complicated or tricky, the publication is now more than 3.000 pages long. A list of the 18 parts (parts 9 and 13 were retired) of the DICOM standard is shown below :

  • Part 3.1 : Introduction and Overview
  • Part 3.2: Conformance
  • Part 3.3: Information Object Definitions
  • Part 3.4: Service Class Specifications
  • Part 3.5: Data Structures and Encoding
  • Part 3.6: Data Dictionary
  • Part 3.7: Message Exchange
  • Part 3.8: Network Communication Support for Message Exchange
  • Part 3.10: Media Storage and File Format for Media Interchange
  • Part 3.11: Media Storage Application Profiles
  • Part 3.12: Media Formats and Physical Media for Media Interchange
  • Part 3.14: Grayscale Standard Display Function
  • Part 3.15: Security and System Management Profiles
  • Part 3.16: Content Mapping Resource
  • Part 3.17: Explanatory Information
  • Part 3.18: Web Access to DICOM Persistent Objects (WADO)
  • Part 3.19: Application Hosting
  • Part 3.20 : Transformation of DICOM to and from HL7 Standards

The DICOM standard is promoted by IHE (Integrating the Healthcare Enterprise), an initiative by healthcare professionals and industry to improve the way computer systems in healthcare share information.

DICOM core

The DICOM core is a file format and a networking protocol.

All medical images are saved in DICOM format, but DICOM files contain more than just images. Every DICOM file holds informations about the patient, the context of the study, the type of equipment used etc.

All medical imaging equipments that are connected to a health network (hospital, …) use the DICOM network protocol to exchange informations, mainly images and binary data. This protocol allows to search for medical images in an archive and to download them to a doctor’s workstation in order to display them.

DICOM Objects

Developers knowing object oriented programming should be familiar with DICOM objects. Patients, medical devices, clinical studies etc are entities in the real world. DICOM has abstract definitions for these entities, called DICOM Information Entities (IEs). DICOM uses a data model with SOP (Service Object Pair) classes and  Information Object Definitions (IODs)  to handle these entities in the DICOM world. For example, a patient IOD has attributes for patient’s name, ID, date of birth, weight, sex and all other clinically relevant patient related informations.

The DICOM data model defines four object levels :

  1. Patient
  2. Study
  3. Series & Equipment
  4. Instance (image)

The name instance, instead of image, was introduced some years ago, because there are now DICOM objects at the fourth level which are not images. These objects are sometimes called DICOM P10 instances with reference to the PS3.10 DICOM standard.

Each of the levels can contain several sub-levels. The following figure shows the DICOM information hierarchy :

dicom_b

DICOM Information Hierarchy

One patient may have multiple studies at different times, each study may include several series with one or more instances.

DICOM differentiates between normalized and composite IODs. A normalized IOD represent a single real-world entity with inherent attributes. Composite IODs are mixtures of several real-world entities.

The DICOM Information Modules are used to group attributes into logical and structured units. Modules can be mandatory, conditional, optional or user-defined. DICOM specifies for each IE the modules it should include. For example, the patient IE should include the patient module, the specimen identification module and the clinical trial subject module. All DICOM objects must include the SOP common module and the four modules of the data model. All DICOM instances that are images must include the Image module.

The attributes of an IOD are encoded as Data Elements.

Let’s summarize the chapter about DICOM objects in a few other words :

  • The DICOM data model is made of Information Entities (IEs)
  • The classes of the DICOM data model are called SOP classes
  • SOP is a pair of a DICOM object and a DICOM service
  • SOP classes are defined by IODs
  • IODs are collections of modules
  • Modules are collections of data elements
  • Data elements collections refer to an Information Entity (IE)

DICOM Data Elements

DICOM objects are encoded in binary form as sequential lists of attributes, called Data Elements.  Every data element has :

  • a tag to uniquely define the element and its proprieties. A tag is comprised of a 16-bit Group number and a 16-bit Element number. Data elements that are related to another have the same Group number.
  • an optional Value Representation (VR), represented as two character code, to define the data type (examples : UI = Unique identifier, CS = coded string, US = unsigned short, …). The VR is called explicit when available. The data type is also specified by the tag and VR is omitted (implicit VR) if determined by the negotiated Transfer Syntax.
  • a length to specify the size of the value field. DICOM values length are always even. Values with a single data are padded by a space in the case of strings and by a null (0x0) in the case of binary types. DICOM lengths are specified with 16 bit if VR is explicit and with 32 bit if VR is implicit. The value filed length can be undefined (FFFFFFFFH).
  • a value field with the corresponding informations. If the length of the value field is undefined, a sequence delimitation item marks its end.
DICOM File displayed in Hexeditor

DICOM File displayed in Hexeditor

There are thousands of different DICOM data elements with a well specified meaning. The names of the data elements are referenced in a DICOM dictionary. Here are some examples :

Tag Group Number Tag Element Number Element or Attribute Name
0010 0010 Patient’s Name
0010 0030 Patient’s Birthday
0020 0011 Series Number
0028 0010 Image Rows
0028 0011 Image Columns

The data elements are sorted sequentially by ascending tag number. It’s possible to define additional elements, called private elements, to add specific informations, but it is recommended to use existing elements whenever possible. Standard DICOM data elements have an even group number and private data elements have an odd group number.

Secondary Capture Image Object

The simplest DICOM object is the Secondary Capture (SC) Image. It has a minimal set of data elements that a DICOM application needs in order to display and archive a medical image. It’s not related to a particular medical image device. The following table shows the mandatory modules for the Secondary Capture Image Object :

Information Entity (IE) Module Reference
Patient Patient C.7.1.1
Study General Study C.7.2.1
Series General Series C.7.3.1
Equipment SC Equipment C.8.6.1
Instance (Image) General Image C.7.6.1
Image Image Pixel C.7.6.3
Image SC Image C.8.6.2
Image SOP Common C.12.1

There are only two modules that are specific to SC (Secondary Capture), the other modules are common and shared by many IODs. Every module is rather large and includes lots of data elements, but luckily most of these data elements are optional. In the DICOM standard the modules are marked with a type column :

  • value 1 : data element is mandatory and must be set
  • value 2 : data element is mandatory, but can be null
  • value 3. data element is optional

Values 1 and 2 can also been marked as c for conditional.

The following table shows the mandatory data elements for the Secondary Capture Image Object :

Attribute Name Tag Type
Patient’s Name (0010, 0010) 2
Patient ID (0010, 0020) 2
Patient’s Birth Date (0010,0030) 2
Patient’s Sex (0010, 0040) 2
Study Instance UID (0020, 000D) 1
Study Date (0008, 0020) 2
Study Time (0008, 0030) 2
Referring Physician’s Name (0008, 0090) 2
Study ID (0020, 0010) 2
Accession Number (0008, 0050) 2
Modality (0008, 0060) 1
Series Instance UID (0020, 000E) 1
Series Number (0020, 0011) 2
Laterality (0020, 0060) 2C
Conversion Type (0008, 0064) 1
Instance Number (0020, 0013) 2
Patient Orientation (0020, 0020) 2C
Samples per Pixel (0028, 0002) 1
Photometric Interpretation (0028, 0004) 1
Rows (0028, 0010) 1
Columns (0028, 0011) 1
Bits Allocated (0028, 0100) 1
Bits Stored (0028, 0101) 1
High Bit (0028, 0102) 1
Pixel Representation 0028, 0103) 1
Pixel Data (7FE0, 0010) 1C
Planar Configuration (0028, 0006) 1C
SOP Class UID (0008, 0016) 1
SOP Instance UID (0008, 0018) 1
Specific Character Set (0008, 0005) 1C

Unique Identifiers

DICOM makes extensive use of Unique Identifiers (UIDs). Almost every entity has a UID, with the exception of the patient (patients are identified with their name and their ID). DICOM defines a mechanism in order to make sure UIDs are globally unique. Every DICOM application should acquire a root UID that is used as a prefix for the UIDs it creates.

Usually the Study Instance UID is provided through a DICOM service called Modality Worklist. The Series UID and the SOP Instance UID are always generated by the application.

DICOM Networking Protocol

The following figure shows the typical medical imaging workflow.

Workflow

Medical Imaging Workflow

The workflow begins when the patient gets registered in the Hospital Information System (HIS). An Electronic Medical Record (EMR) is generated for the new patient. A medical procedure, for example an X-Ray of the thorax, is ordered and placed into the Radiology Information System (RIS). The RIS generates a study scheduled and sends an HL7-event to a HL7-DICOM gateway. The gateway sends the study scheduled event to the Picture Archiving and Communication System (PACS) to prefetch previous exams of the patient. When the patient arrives at the modality (X-Ray in this example), the technologist requests the Modality Worklist (MWL : a sort of task manager) and updates the RIS. The acquired images are forwarded to the PACS where they are checked, stored and forwarded to the review workstation of the radiologist. The radiologist views the study images and reports possible pathologies.

The Modality Worklist is combined with a Modality Performed Procedure Step (MPPS) that allows the Modality to report the task status and to take ownership over the task. Associated to MPPS are the Requested Procedure (RP), the Requested Procedure Description, the Requested Procedure Code Sequence and the Scheduled Procedure Step (SPS). MPPS is the checkmark for MWL.

The main DICOM nodes in this workflow are the Modality, the PACS and the Workstation. DICOM’s network communication is based on the ISO/OSI model. The entities (nodes) in the network are specified with the following parameters :

  • Application Entity (AE) Title : max 16 characters, case sensitive;
    it’s a sort of alias for the combination of IP address and port number
  • IP address
  • Port number

With the parameters of the source and the target AE, we can start a per-to-peer session called Association. This is the first step of a DICOM network communication. The second step is exchanging DICOM commands. Most problems in DICOM communications are related to failing association negotiations. Errors are reported in the DICOM log.

The calling AE sends an Association Request to the target (called) AE. It’s a description of the application, its capabilities and its intentions in this session (presentation context). The called AE checks the request and sends back an Association Response, confirming what can and can’t be done. If its doesn’t match, the calling AE can reject the association. An important parameter is the Max PDU Size, an application level packet that says how big is the buffer consumed for the request. Some calling application entities uses buffer sizes too large for the called application entity; the result can be a crash due to a buffer overflow. In case of none-response by the called AE, the request will timeout.

A DICOM service related to the exchange step is Storage Commitment (SCM) that lets you verify if files sent to a PACS where indeed stored correctly. The result is sent using the N-EVENT-REPORT command.

DICOM services are used for communication within an entity and between entities. A service is built on top of a set of DICOM Message Service Elements (DIM-SEs) adapted to normalized and composite objects. DIM-SEs are paired : when a device issues a command, the receiver responds accordingly.

DICOM services are referred to as Service Classes. A Service Class Provider (SCP) provides a service, a Service Class User (SCU) uses a service. A device can be an SCP, an SCU or both. The following table shows the main DIM-SE’s : commands with a C-prefix are composite and those with a N-prefix are normalized.

C-ECHO sort of application level ping to verify a connection;
this service is mandatory for all AEs
C-FIND inquiries about information object instances
C-STORE allows one AE to send a DICOM object to another AE
C-GET transmission of an information object instance
C-MOVE similar to C-GET, but receiver is usually not the command initiator
C-CANCEL interrupt a command
N-CREATE creation of an information object
N-GET retrieval of information object attribute value
N-SET specification of an information object
N-DELETE Deletion of an information object
N-EVENT-REPORT result from SCM

A fundamental service implemented by every workstation is the Query / Retrieve (Q / R) task. The query is done with C-FIND. The keys to search are Patient Name, Patient ID, Accession Number, Study Description, Study Date, Modality, … The Retrieve is done with C-MOVE and C-STORE commands.

DICOM Serialization = Transfer Syntax

To transmit DICOM objects through a network or to save them into a file, they must be serialized. The DICOM Transfer Syntax defines how this is be done. There are 3 basic transfer syntaxes presented in the next table :

UID Transfer Syntax Notes
1.2.840.10008.1.2.1 Little Endian Explicit (LEE) stores data little-end first, explicit VR
1.2.840.10008.1.2.2 Big Endian Explicit (BEE) stores data big-end first, explicit VR
1.2.840.10008.1.2 Little Endian Implicit (LEI) stores data little-end first, implicit VR

A complete list is shown in my post DICOM TransferSyntaxUID.

The transfer syntax specifies 3 points :

  • if VRs are explicit
  • if the low byte of muti-byte data is the first serialized or the last serialized
  • if pixel data is compressed and when yes, what compression algorithm is used

LEI is the default Transfer Syntax which shall be supported by every conformant DICOM Implementation. Compressed pixel data transfer syntax are always explicit VR little Endian. The following compression methods can be used :

  • jpeg
  • jpeg lossless
  • jpeg 2000
  • RLE
  • JPIP
  • MPEG2
  • MPEG4

If DICOM objects are serialized into files, there are additional informations to provide :

  • a  preamble of 132 bytes, where the first 128 bytes are null and the last 4 bytes are the DICOM magic number DICM.
  • a file meta header consisting of data elements of group 0002, written in Little Endian Explicit
  • an element (0002, 0010) with the Transfer Syntax UID that is used for all the data elements other than group 0002.

Group 0002 data elements are strictly used for files and must be removed before sending DICOM objects over the network.

If DICOM files are saved on a standard CD / DVD, they should have a file named DICOMDIR in its root directory. DICOMDIR is a DICOM object listing the paths to the files stored on the media. The file names of these files should be capital alphanumeric up to 8 characters with no suffix. An example of naming conventions is shown hereafter :

  • directory PAxxx for every patient  (xxx = 001, 002, …)
  • inside PAxxx a directory STyyy for every (yyy = 001, 002, …)
  • inside STyyy a directory SEzzz for every series (zzz = 001, 002, …)
  • inside SEzzz a DICOM file MODwwwww for every instance
    (MOD = CT, CR, …; wwwww = 00001, 00002, …)

DICOM files stored in the cloud or on a non-DICOM media have the suffix .dcm.

Pixel Data

Because imaging is the heart of DICOM, we will deal with the bits of images in a specific chapter called pixel data. The data elements of the pixel module have group number 0028 and are responsible for describing how to read the image pixels. The next table shows the different data elements :

Tag VR Description
(0028, 0002) US Samples PerPixel : number of color channels; grey = 1
(0028, 0004) CS PhotometricInterpretation : MONOCHROME1 -> 0 = white ;
MONOCHROME2 -> 0 = black ; YBR_FULL -> YCbCr space
(0028, 0006) US PlanarConfiguration : 0 = interlaced color pixels ; 1 = separated pixels
(0028, 0008) IS NumberOfFrames : number of frames in the image; multi-frame >1
(0028, 0010) US Rows : height of the frame
(0028, 0011) US Columns : width of the frame
(0028, 0100) US BitsAllocated : space allocated in the buffer (usually 16)
(0028, 0101) US BitsStored : how many allocated space is used (in CT usually 12)
(0028, 0102) US HighBit : the bit number of the last bit used (in CT usually 11)
(0028, 0103) US PixelRepresentation : unsigned = 0 (default) ; signed = 1
(0028, 1050) DS WindowCenter :
(0028, 1051) DS WindowWidth :
(0028, 1052) DS RescaleIntercept :
(0028, 1053) DS RescaleSlope :
(7FE0, 0010) OB Image Pixel Data : (for CT -> VR = OW : other word)

The group number of the image data element is 7FE0 to be sure that this element is the last in the DICOM object. It is usually a very long data element and can be easily skipped if we want to read only the headers.

The Image Plane Module defines the direction of the image with reference to the patient body. It also gives the dimensions of the pixels in mm. The corresponding data element has tag 0020, 0037. DICOM defines a Reference Coordinate System (RCS) of the patient body.

X-direction is from Right to Left in the Axial (transversal) Cut. Y-direction is from Front (Anterior) to Back (Posterior) in the Sagittal Cut. Z-direction is from feet to head in Coronal Cut. The following letters are assigned to the ends of each direction :

  • [R] – Right – X decreases
  • [L] – Left – X increases
  • [A] – Anterior – Y decreases
  • [P] – Posterior – Y increases
  • [F] – Feet – Z decreases
  • [H] – Head – Z increases

These letters are usually displayed on the sides of a DICOM viewer. If the patient is in an oblique position, there can be letter combinations like [PR] for Posterior Right or [ALH] for Anterior Left Head.
onformance Statement

DICOM Conformance Statement

DICOM requires that a Conformance Statement must be written for each device or program claiming to be DICOM conformant. The format and content of a Conformance Statement is defined in the standard itself.

Links

Additional informations about the DICOM standard are available at the following websites :

Hybrid iOS app’s

Posted on by

Native iOS app’s are built with the platform SDK provided by Apple (Xcode/Objective-C / Swift). The main advantage of native applications is their performance because they are compiled into machine code.

Mobile Web iOS app’s are built with server-side technologies (PHP, Node.js, ASP.NET) that are mobile-optimized to render HTML well on iPhones and iPads. Mobile app’s load within the mobile browser Safari like every other website. They generally require an Internet connection to work, but it’s also possible to use cache technologies to use them off-line and you can install them with an icon on the iOS home screen. Mobile Web app’s for iOS are faster and easier to develop and to maintain than native iOS app’s.

Hybrid iOS app’s

Hybrid iOS app’s are somewhere between native and web app’s. The bulk of hybrid iOS app’s is written with cross-compatible web technologies (HTML5, CSS and JavaScript), the same languages used to write web app’s. Hybrid app’s run inside a native container on the device using the UIWebView or WKWebView classes.  Some native code is used however to allow the app to access the wider functionality of the device and to produce a more refined user experience. The advantage of this approach is obvious: only a portion of native code has to be re-written to make the app work on another type of device, for instance on Android, Blackberry or Windows Mobile.

Some developer consider hybrid iOS app’s as beeing the best of both worlds. Great examples of hybrid iOS app’s are Facebook and LinkedIn.

Hybrid iOS app tools

There are numerous tools available to create hybrid app’s, not only for iOS, but for all mobile platforms. The most important tools to embed HTML5, CSS and Javascript in mobile app’s are :

  • PhoneGap : a mobile development framework created by Nitobi, which was purchased by Adobe in 2011. The latest version is 4.0.0.
  • Apache Cordova : a free and open-source platform for building native mobile applications using HTML, CSS and JavaScript, underlying PhoneGap. Apache Cordova graduated in October 2012 as a top level project within the Apache Software Foundation (ASF). The latest version is 5.0.0.
  • BridgeIt : an open source mobile technology sponsored by ICEsoft Technologies Inc.
  • MoSync : free, easy-to-use, open-source tools for building cross-platform mobile apps (MoSync Reload 1.1 and MoSync SDK 3.3.1).
  • Ionic : the final release of Ionic 1.0.0 (uranium-unicorn) was released on May 12, 2015.
  • CocoonJS : a platform to test, accelerate, deploy and monetize your HTML5 apps and games on all mobile devices with many interesting features to help you deliver great web products faster.
  • ChocolateChip-UI : the tool uses standard Web technologies and is built on top of the popular & familiar jQuery library.
  • Sencha-Touch : the leading (very expensive) cross-platform mobile web application framework based on HTML5 and JavaScript for creating universal mobile apps.
  • Kendo UI : everything for building web and mobile apps with HTML5 and JavaScript.
  • AppGyver (Steroids, Supersonic, Composer) : a combination of great CSS defaults (from the Ionic Framework) with the best native APIs (from PhoneGap), adding a boatload of extra features on top.

There are also some tools and platforms available which use other technologies than HTML5 +CSS + Javascript :

  • Titanium : write in JavaScript, run native everywhere at the speed of mobile, with no hybrid compromises.
  • Xamarin : share the same C# code on iOS, Android, Windows, Mac and more.
  • RhoMobile Suite : gain the ease of consumer smartphone platforms, without sacrificing the critical data functionality of enterprise solutions.
  • Corona : designed to enable super-fast development. You develop in Lua, a fast and easy-to-learn language with elegant API’s and powerful workflows.
  • Meteor : discover the easiest way to build amazing web and mobile apps in JavaScript.

WebViews

The tools to create hybrid app’s give you access to the underlying operating system calls or to underlying hardware functionality. Howver you do not really need these tools if you want only deploy a web app as a native app. All you need is the bare minimal code to launch a Web View and load your Web App as local resources.

UIWebView

To embed web content in an iOS application you can use the UIWebView class. To do so, you simply create a UIWebView object, attach it to a window, and send it a request to load web content. You can also use this class to move back and forward in the history of webpages, and you can even set some web content properties programmatically.

The steps to create a minimal demo to load this web content from an external webserver are the following :

  1. Create an Xcode Swift project with a single view application.
  2. Open the Main.storyboard file and drag the WebView UI element from the object library to the Interface Builder view.
  3. Open the assistant editor to display the ViewController.swift file, ctrl-click-drag the WebView behind the class ViewController text line to create an IBOutlet named mywebView : 
     @IBOutlet weak var mywebView: UIWebView!
  4. Define the url of the remote website : 
    let url = "http://www.canchy.eu"
  5. Add the following code to the viewDidLoad function : 
    let requestURL = NSURL(string:url)
let request = NSURLRequest(URL: requestURL!)
mywebView.loadRequest(request)
  6. Run the project :
Remote

Remote website displayed in iOS Simulator

The website loads, but it looks awful. The reason is that the UIWebView doesn’t handle things that Safari does by default. Telling the program to scale pages is easy. We need to add the following line of code :

mywebView.scalesPageToFit = true

The whole script of the ViewController.swift file looks now as follows :

View

ViewController.swift script for RemoteWeb

The layout is still not perfect, but you can now pinch the view to zoom in and out. Holding down the alt key and click-dragging the view allows you to perform this action in the simulator. We will enhance the scaling in a further chapter.

Note that for a very simple app like the present one it’s not necessary to import the webkit framework. UIWebView has about a dozen methods you can use, but to get about 160 methods you need the webkit classes.

Project

Project window with local web content

To include the web content into the iOS app, we add the folder canchy with html files, css files, javascript files, images and photos into the project window.

The three first steps to create a minimal demo to load local web content are the same as those for the remote content.

The next steps are the following :

4. Define the path for the local content with the NSBundle.mainBundle() method :

  • pathForResource
  • ofType
  • inDirectory

5. Create an URL object with this path with the NSURL.fileURLWithPath() method

6. Create a Request object with this URL with the NSURLRequest() method.

7. Scale the page with the scalesPageToFit method.

8. Load the Request object with the loadRequest() method.

9. Run the project.

The result is the same as with the remote content. The layout is not adapted to the screen. We will fix that in the last chapter.

The complete script of the ViewController.swift file is shown below :

 

local

ViewController.swift script for local web content

WKWebView

With iOS 8 and Mac OSX Yosemite, Apple released the new WKWebView class, which is faster and more performant than the UIWebView class. WKWebView uses the same Nitro Javascript engine as the Safari browser.

To create an hybrid iOS app with the WKWebView class, the procedure to access content on an external web-server is the same as for the UIWebView class. Only the code in the ViewController.swift file is slightly different.

WK

ViewController.swift script for remote web content with WKWebView

We need to import the WebKit framework, because the WKWebView class is now part of the WebKit itself.

Remote

Remote website displayed in iOS Simulator

By default the website display in WKWebView is better adapted to the screen size,  compared to the UIWebView.

The worst issue of the WKWebView class is that it doesn’t allow loading local files from the file:// protocol like the UIWebView class. There are some workarounds available, most of them use an embedded local HTTP server to serve the local files. The most renowned solutions are the following :

XWebView uses a very tiny embedded http server, whereas the Cordova WKWebView Engine uses the more versatile GCDWebServer.

GCDWebServer

GCDWebServer is a modern and lightweight GCD (Grand Central Dispatch) based HTTP 1.1 server designed to be embedded in OS X & iOS app’s. It was written from scratch by Pierre-Olivier Latour (swisspol) with the following features :

  • four core classes: server, connection, request and response
  • no dependencies on third-party source code
  • full support for both IPv4 and IPv6
  • HTTP compression with gzip
  • chunked transfer encoding
  • JSON parsing and serialization
  • fully asynchronous handling of incoming HTTP requests

WKWebView versus UIWebView

Both WKWebView and UIWebView in iOS8 support WebGL which allows rendering 3D and 2D graphics on WebView. The performance gains are significant (greater than 2x) in WebGL applications when using WKWebView, compared to UIWebView.

You can use the WebView Rendering App available in Apple AppStore to test any website performance between UIWebView and WkWebView. An In-App debug console for your UIWebView & WKWebView classes is available at Github.

CORS

If a javascript on a webpage displayed in UIWebView or WKWebView is running from domain abc.com and would like to request a resource via AJAX (XmlHttpRequest or XDomainRequest) from domain efg.com, this is a cross-origin request. Historically, for security reasons, these types of requests have been prohibited by browsers.

The Cross Origin Resource Sharing (CORS) specification, now a W3C recommendation, provides a browser-supported mechanism to make web requests to another domain in a secure manner. To allow AJAX requests across domain boundaries, you need to add the following headers to your server :

Access-Control-Allow-Origin.*
Access-Control-Allow-Headers : Accept, Origin, Content-Type
Access-Control-Allow-Methods : GET, POST, PUT, DELETE, OPTION

Size the web views

Xcode provides an auto layout function. By clicking the second icon (pin) from the left in the storyboard, a popup window opens to set the spacing contraints to the nearest neighbours. By clicking the dotted red lines leading from the small square at the top to four textboxes, you can define these constraints. I set the top border to 20 points and the right and left border to 16 points.

Constraints

Adding constraints to execute the auto layout function in the storyboard

By clicking the button “Add 3 Constraints” the values are entered and displayed with the selected values in the View Controller Scene.

Constraints

Viewing the layout constraints in the View Controller Scene

The result is a correct display of the webpage in the iOS Simulator with a free toolbar of 20 points at the top of the web view.

Display

Webpage view with auto layout

Links

iOS Xcode Project

Posted on by

Last update : September 18, 2015

Xcode Project

This topic refers to my recent post about iOS Development and provides more detailed informations about iOS Xcode 6.3 projects. An Xcode project is the source for an iOS app; it’s the entire collecton of files and settings needed to construct the app. An iOS app is based on event-driven programming.

To create a new project in Xcode, the menu File -> New -> Project leads to a dialog window to chose a project template.

new

Template selection for a new Xcode project

The Single View Application in the iOS templates is a good starting point to create a simple app, for example the classic HelloWorld demo.

Helloworld

Xcode HelloWorld Demo Project

The name of the app (HelloWorld) is entered as Product Name. Spaces are legal in an app name, we could also name the project Hello World. Other punctuations in the product name can however lead to problems. The product name is used by Xcode to fill in the blank in several places, including some filenames.

My name is entered as Organization Name and my website domain name web3.lu is used as Organization Identifier. The unique bundle Identifier is automatically set to web3.lu.HelloWorld by the system.

The selected language is Objective-C, the other possibility is Swift. This choice is not binding, you can mix Objective-C and Swift code files. The selected device is iPhone, other possibilities are iPad or universal for both iPhone and iPad. The flag “Use Core Data” remains unchecked in a simple project.

Clicking the next button shows a file selection window where you can select or create a location (an Xcode workspace folder) and place the project under version control in a Git repository, which is however design overkill for a small tutorial project.  Clicking the create button generates the skeleton of a simple app, with precompiled files and settings, based on the selected template. If you have not yet an Apple Development Account, a warning message says “no signing identity found”.

Xcode Project Window

The different files and parameters of an Xcode project can be classified as :

  • source files that are to be compiled
  • .storyboard or .xib files, graphically describing interface objects
  • resources such as icons, images, sounds, …
  • settings : instructions to the compiler and linker
  • frameworks with system classes

This is a lot of embodied information that is presented in the Xcode IDE Project Window in graphical form. This window can be configured in the following parts to let you access, edit and navigate your code and to get reports about the progress of building and debugging an app :

  • Menu Bar
  • Tool Bar
  • Left-hand Sidebar : Navigator Pane
  • Right-hand Sidebar : Utilities Pane
  • Middle main area : Editor Pane, or simply “Editor”
  • Middle bottom area : Debugger Pane
Xcode Project Window

Xcode Project Window

A project widow is powerful and elaborate. The different panes and subviews can be shown or hidden inside the View Menu with the corresponding submenus. The width and height of the panes can be changed by dragging the edges. Keyboard shortcuts can be associated to panes to show, hide or switch them easily. Usually all these parts are not displayed at the same time, except very briefly in rather an extreme manner. By control-clicking a area in the Xcode project window, a shortcut menu appears to select help articles.

Menu Bar

The Menu Bar features the following menus :

  • Xcode
  • File
  • Edit
  • View
  • Find
  • Navigate
  • Editor
  • Product
  • Debug
  • Source Control
  • Window
  • Help
Xcode IDE Menubar

Xcode IDE Menubar

Toolbar

The toolbar features the following parts :

  • a build / run and stop button
  • a scheme and destination selector (pop-up menu)
  • an activity viewer (report field)
  • three icons to select the standard, assistant or version editor
  • three icons to show / hide the navigator, utilities or debug areas
Xcode IDE Toolbar

Xcode IDE Toolbar

Navigator Pane

xcode_navigationThe primary mechanism of the navigator pane at left-hand is for controlling what you see in the main area of the project window. You select something in the Navigator pane, and that thing is displayed in the editor of the project window. The Navigator pane itself can display eight different sets of information; thus, there are actually eight navigators represented by the eight icons across its top.

  • Project Navigator : basic navigation through the files of a project
  • Symbol (Hierarchical) Navigator : a symbol is typically the name of a class or method
  • Find (Search) Navigator : to find text globally, even in frameworks
  • Issue Navigator : needed when the code has issues
  • Test Navigator : list test files and run individual test methods
  • Debug Navigator : to track possible misbehavior of the app
  • Breakpoint Navigator : lists all the breakpoints
  • Report (Log) Navigator : lists the recent major actions, such as building or running

At the bottom of the navigator pane is a filter which lets you limit what files are shown. Below the search filed is the current search scope.

 

Utilities Pane

The utilities pane at right-hand contains inspectors in the top half that provide information about the current selection or its settings; in some cases, these inspectors let you change those settings. There are four main cases :

  • a code file is edited : you can toggle between File Inspector and Quick Help.
  • a storyboard file is edited : in addition to the File Inspector and the Quick Help tabs, the following additional inspectors are available : Identity, Attributes, Size and Connections.
  • an asset catalog is edited : in addition to the File Inspector and the Quick Help tabs, the Attribute Inspector lets you define which variants of an image are listed.
  • the view hierarchy is being debugged : in addition to the File Inspector and the Quick Help tabs, the Object Inspector and the Size Inspector are available.
Xcode IDE Inspectors (5 examples)

Xcode IDE Inspectors (5 examples)

In the bottom half the utilities pane contains four libraries that function as a source of objects you may need while editing your project :

  • File Template Library
  • Code Snippet Library
  • Object Library
  • Media Library

You can toggle between these four libraries. The object library is the most important. Press spacebar to see help pop-ups describing a library item.

Xcode IDE libraries (4 examples)

Xcode IDE libraries (4 examples)

Editor

In the middle of the project window is the editor. This is where you get actual work done, reading and writing your code or designing your interface in a .storyboard or .xib file. The editor is the core of the project window. You can hide the navigator pane, the utilities pane, and the debug pane, but there is no such thing as a project window without an editor.

The editor provides its own form of navigation, the jump bar across the top which show you hierarchically what file is currently being edited. The jump bar allows you to switch to a different file and it displays also a pop-up menu, which has also a filter field.

Xcode IDE Editor jumpbar

Xcode IDE Editor jumpbar

To edit more than one file simultaneously, or to obtain multiple views of a single file, you can split the editor window using assistants, tabs and secondary windows. The menus View -> Navigators and File -> Tab or File -> Window allow to activate the splitting. You can determine how assistant panes are to be arranged with the Menu View -> Assistant Editor submenu. The assistant pane bears a special relationship to the primary editor pane (tracking).

Xcode IDE Editor

Xcode IDE Editor

Debugger

The debug navigator displays the call stacks of a paused app. You can debug Swift or C-based code as well as OpenGL frames. The debug navigator opens automatically whenever you pause your application (by choosing menu Debug -> Pause), or if it hits a breakpoint.

Xcode IDE Debugger

Xcode IDE Debugger

The debug navigator shows threads with the following icons :

  • No icon means the thread is running normally
  • A yellow status icon means that the thread is blocked and waiting on a lock or condition
  • A red status icon means that you suspended the thread. A suspended thread does not execute code when you resume your application
  • A gray icon means that thread or block is part of the recorded backtrace and is not currently executing

Anatomy of an Xcode Project

The first item in the Project Navigator represents the project itself. The most important file (archive, folder) in the project folder is HelloWorld.xcodeproj.  All the Xcode knowledge about the project is stored in this file.

Based on the iOS SDK 8.3, a project HelloWorld has two targets :
HelloWorld and HelloWorldTests.
A target is a collection of parts along with rules and settings for how to build a product from them. The test target is a special executable whose purpose is to test the app’s code.

The HelloWorld target includes the following files :

  • AppDelegate class with .h and .m files
  • ViewController class with .h and .m files
  • Main.storyboard file
  • Images.xcassets folder with icons (asset catalog)
  • LaunchScreen.xib file
  • Info.plist file
  • a subfolder Supporting Files with a main.m file and an Info.plist file

The HelloWorldTests target includes the following files :

  • HelloWorldTests.m implementation file
  • a subfolder Supporting Files with an Info.plist file

It’s important to know that groups (like the group Supporting Files) in the project navigator don’t necessarily correspond to folders in the project directory. The Supporting Files group is just a way to clump some items together in the project navigator to locate them easily. To make a new group, use the Menu File -> New -> Group.

The LaunchScreen.xib file is not necessary and can be deleted if a launch screen picture is included in the asset catalog.

The two products which will be created in the project are HelloWorld.app and HelloWorldTests.xctest.

The project and targets are specified by the following parameter sets :

  • General
  • Capabilities
  • Info
  • Build Settings
  • Build Phases
  • Build Rules

You can add more targets to a project, for example a custom framework to factor common code into a single locus or an application extension (examples : content for the notification center, photo editing interfaces, …).

The anatomy of a Xcode project changed with Xcode 4.2.  Prior to this version, an iOS Xcode Project included the following items :

  • a folder xxx.xcodeproj
  • a file main.m
  • a file xxx_Prefix.ch
  • a file xxx-Info.plist
  • a file MainWindow.xib
  • a folder classes with .m and .h files
  • a folder resources with pictures and data

Build a project (Phases, Settings, Configurations)

To build a project is to compile its code and assemble the compiled code, together with various resources, into the app. To run a project is to launch the built app, in the Simulator or on a connected device. Running the app automatically build it first if necessary.

Click at the tab Build Phase at the top of the target editor window to view the stages by which the app is built. The build phases are both a report to the developer and a set of instructions to the Xcode IDE. If you change the build phases, you change the build process.

Xcode IDE Buildphases

Xcode IDE Build Phases

There are four build phases :

  • Target Dependencies
  • Compile Sources
  • Link Binary with Libraries
  • Copy Bundle Resources (copying doesn’t mean making an identical copy, certain types of files are treated in special ways)

You can add build phases with the menu Editor -> Add Build Phase, for example Add Run Script Build Phase to run a custom shell script late in the build process. To check the option “Show environment variables in build log” is then a useful choice.

Another aspect of how a target knows how to build the app is Build Settings. By clciking the tab Build Settings at the top of the target editor window you will find a long list of settings :

  • Architectures
  • Build Locations
  • Build Options
  • Code Signing
  • Deployment
  • Kernel Module
  • Linking
  • Packaging
  • Search Paths
  • Testing
  • Versioning
  • Apple LLVM 6.1 (Code generation, Custom Compiler Flags, Language, Language – C++, Language – Modules, Language – Objective C, Preprocessing, Warning Policies, Warnings – All languages, Warnings – C++, Warnings – Objective C, Warnings – Objective C and ARC)
  • Asset Catalog Compiler – Options
  • Interface Builder Storyboard Compiler – Options
  • Interface Builder XIB Compiler – Options
  • OSACompile – Build Options
  • Static Analyzer (Analysis Policy, Generic Issues, Issues – Objective C, Issues – Security)
  • User Defined
xcode_buildsettings

Xcode IDE Build Settings

You can define what and how build settings are displayed by selecting Basic / All or Combined / Levels. There are multiple lists of build setting values, though only one such list applies when a particular build is performed. Each list is called a configuration. By default there are two configurations :

  • Debug : used through the development process
  • Release : used for late-stage and performance testing, before submitting the app to the Apple App Store
Xcode IDE Configurations

Xcode IDE Configurations

The defaults of the build settings are usually acceptable and need not be changed.

Schemes and Destinations

xcode_schemeTo tell the Xcode IDE which configuration to use during a particular build is determined by a scheme. A scheme unites a target with a build configuration. A new project commes by default with a single scheme named after the project.

The menu Product -> Scheme -> Edit Scheme shows the current scheme. You can also show the scheme by using the scheme pop-up menu in the Project Window Toolbar.

A scheme has the following actions :

  • Build
  • Run
  • Test
  • Profile
  • Analyze
  • Archive
Xcode IDE destinations

Xcode IDE destinations

Hierarchically appended to each scheme listed in the scheme pop-up menu are the destinations. A destination is a machine that can run the app. This can be a real device connected to the Mac computer running the Xcode IDE or a virtual device simulated in the Simulator.

The menu Window -> Devices allow you to download and install additionaliOS SDK’s and to manage the devices to appear as destinations in the scheme popu-up menu.

Xcode Flow and Hierarchy

Most of the work in an app is done by the UIApplicationMain function which is automatically called in the project’s main.m source file within an autorelease pool (memory management with Automatic Reference Counting : ARC) . An application object is created and a run loop is launched that delivers input events to the app.

The other files in an Xcode project do the following tasks :

  • AppDelegate class with AppDelegate.h (header) and AppDelegate.m (implementation) files. This class creates an AppDelegate object as an entry point to the application. When the AppDelegate object notices that the application is launched it creates the ViewController object.
  • ViewController class with ViewController.h and ViewController.m files. This class is responsible for controlling and managing a view. The generated ViewController object is responsible for setting up the view described in Main.storyboard and showing it on the screen to the user.
  • Main.storyboard file is the view that the ViewController class is managing. The Main.storyboard file is created and modified with a visual designer, called “Interface Builder”, in the Xcode IDE.

The implementation file AppDelegate.m contains skeletons of important predefined methods :

  • application didFinishLaunchingWithOptions
  • applicationWillResignActive
  • applicationDidEnterBackground
  • applicationWillEnterForeground
  • applicationDidBecomeActive
  • applicationWillTerminate

You can add additional code to these methods that you want to be executed when the methods are called.

Xcode Storyboard, Screen, Scene, Canvas, View

An Xcode storyboard is the visual representation of the app’s user interface, showing screens of content and the transitions between them. The background of the storyboard is the canvas.

In a single view application, the storyboard contains only one scene. The arrow that points to the left of the scene on the canvas is the storyboard entry point, which means that this scene is loaded first when the app starts. If you have more than one scene, you can zoom the canvas in and  out with the menu Editor -> Canvas -> Zoom to see the whole content.

Xcode scene entry point

Xcode scene entry point

To adapt the generic scene in the canvas to real devices in different orientations, you must create an adaptive interface with the AutoLayout engine. The four icons Align, Pin, Resolve Issues and Resize Behavior allow to fix and manage constraints to adapt the interface. Use the assistant editor in the preview mode with the wAny and hAny icons to check the adapted interface.

Xcode IDE auto

Xcode IDE AutoLayout engine tools

Xcode IDE Library with Interface Elements

Xcode IDE Interface Elements

The library of objects provides UI elements (views, buttons, text labels, gesture controllers, …) to arrange the user interface. The size of UI elements can be modified by dragging its resize handles (small white squares) on the canvas.

The UIScreen object represents the physical iPhone or iPad screen. The UIWindow object provides drawing support for the screen. UIView objects are attached to the UIWindow object and draw their contents when directed to do so by the window. The visual interface of an app is essentially a set of UIView objects (views), which are themselves managed by UIViewController objects. UIViewController objects interact with views to determine what’s displayed by the views, handle any interactions with the user, and perform the logic of a program.

The views have following properties :

  • Views represent a single item (button, slider, image, text field, …) on the user interface, cover a specific area on the screen and can be configured to respond to touch events.
  • Views can be nested inside other views, which lead to the notion of a view hierarchy. They are referred as subviews (childs) or superviews (parents). Subviews are drawn and positioned relative to their superview. At the top is the window object.
  • Views are not the place where the bulk of a program logic resides.

UIKit views are grouped in the following general categories :

  • Content : image, text, …
  • Collections : group of views
  • Controls : buttons, sliders, switches, …
  • Bars : toolbar, navigation, tabs, …
  • Input : search, info, …
  • Containers : scroll, …
  • Modal : alerts, action sheets, …

The storyboard is not the only way to program an interface, you can also use .xib files or custom code. Storyboard and .xib files are converted to a bundle of NIB files at compilation.

Anatomy of an App

An app file is a special kind of folder called a package, and a special kind of package called a bundle. Use the Finder to locate the HelloWorld.app on the Mac computer. By default it is located inside a build folder in the user directory at Library/Developer/Xcode/DerivedData/.

Right clicking on the filename HelloWorld.app opens a pop-up menu with the submenu “Show Package Contents“. The following items are inside the bundle :

  • HelloWorld (exec)
  • PkgInfo
  • Info.plist
  • Folder Base.lproj including LaunchScreen.nib and Main.storyboardc

Bilingual Targets

It is legal for a target to be a bilingual target that contains both Objective-C and Swift code. To assure communication between the two languages, Xcode provides bridging headers.

Links

Additional informations about Xcode projects are available at the websites with the following links :

iOS Development

Posted on by

Last update : September 10, 2015

Operating System

iOS is the operating system that runs on iPad, iPhone and iPod devices. The operating system manages the device hardware and provides the technologies required to implement native apps.

The iOS architecture is layered in four levels :

  • Cocoa Touch (at the top level)
  • Media
  • Core services
  • Core OS (at the bottom level)

At the highest level, iOS acts as an intermediate between the underlying hardware and the apps.

iOS Development

To develop applications for iOS devices the following tools are required :

  • Mac computer running OS X 10.9.4 or later
  • Xcode
  • iOS SDK
  • Apple Developer Program
  • Documentation

Xcode

Xcode is an integrated development environment (IDE) created by Apple for developing software for OS X and iOS devices. First released in 2003, the latest stable release is version 6.4 and is available via the Mac App Store free of charge for OS X Yosemite users. Xcode 7 is available as beta version. Xcode is installed into the /Applications directory.

welcome

Welcome Screen of the Xcode IDE

Xcode is used in two ways. It is not only the name for the suite of developer tools, but also the name of an application within that suite : an Xcode project.

The program code to develop an iOS App is embedded in an Xcode project which is saved itself in an Xcode workspace. A workspace is a container that encompasses multiple projects that share common resources.

The result of the development process is called product, specified by an Xcode target. Projects can contain one or more targets, each of which produces one product.  Usually there are 2 targets : a release version  and tests. The targets can also be a plain and light version of an app for the Apple Store.

An Xcode scheme defines a collection of targets to build, a configuration to use when building, and a collection of tests to execute. Introduced with Xcode 4, schemes are a powerful way to control how you build, debug, test, analyze, profile, and deploy your application. You can have as many schemes as you want, but only one can be active at a time. Xcode uses build settings to specify aspects of the build process followed to generate a product. A build setting is a variable that determines how build tasks are performed.

Another concept of Xcode are templates. Xcode includes the following built-in app templates for developing common types of iOS apps, such as games, with preconfigured interface and source code files :

  • Single View Application
  • Master-Detail Application
  • Page-Based Application
  • Tabbed Application
  • Game
  • Cocoa Touch Framework
  • Cocoa Touch Static Library
  • In-App Purchase
  • Empty

Since Snow Leopard (Xcode 3.2), Xcode uses the LLVM compiler, based on the open source LLVM.org project. The LLVM compiler uses the Clang front end to parse source code and turn it into an interim format.

Xcode supports the following program files :

  • xxx.h : headers (interfaces)
  • xxx.m : Objective-C implementations
  • xxx.mm : Objective-C++ implementations
  • xxx.swift : Swift implementations
  • xxx.c :  C implementations
  • xxx.cpp : C++ implementations
xcode

Xcode Editor, Storybuilder and Utilities windows

The developed app can be tested on a real iOS device or in the iOS simulator integrated in Xcode.

iOS SDK

The iOS SDK is a software development kit developed by Apple and released in February 2008 to develop native applications for iOS devices. The initial name was iPhone SDK.

The main features of the iOS SDK are :

  • Objective-C
  • Swift
  • Cocoa Touch
  • Frameworks

Apple Developer Program

To get everything you need to develop and distribute your iOS apps, you must enroll in an Apple Developer Program. The iOS Developer Program costs 99$ per year. After registration, payment and acceptance by Apple, I did my first login to the Apple Developer Member Center with my Apple ID on April 24, 2015.

Apple Developer Member Center Login Window

Apple Developer Member Center Login Window

id

Registrated iOS Development Agent

ios_id

Signing Identities for iOS Development and Distribution

iOS Apps must be signed by the developer to deploy them on an iOS device. To test a signed app on a real device, you must registrate this device. You can registrate up to 100 iOS devices in your development account. The devices must be connected to the Mac computer running Xcode to test and install an app.

To register an iOS device for development, you must know its UDID (Unique Device Identifier). There are several possibilities to get this UDID when the device is connected to the Mac Computer :

  • with iTunes running on a Mac
  • with the Mac USB Inspector
  • with Xcode running on a Mac
usb

Get the iOS UDID with the USB Inspector on a Mac Computer

iphone

Get the iOS UDID in Xcode

Without connection an iOS device to a Mac computer, it’s possible to access the webpage get.udid.io to reveal it.

I registrated my iPhone 5 and my iPad 2 in my iOS development account.

register

Registration of an iPad and an iPhone in the iOS Development Program

 

 

add

Review and confirmation of the provided informations

 

After reviewing and confirming the informations, the registration was complete.

complete

Completed Registration

 

Documentation

The iOS Developer Library is the most important documentation resource to help developers. The library contains API references, programming guides, release notes, technical notes, sample code and other documents.

The tutorial Start Developing iOS Apps Today is he perfect starting point for creating apps that run on iPad, iPhone, and iPod touch.

Cocoa and Cocoa Touch

Cocoa is Apple’s native object-oriented application programming interface (API) for the OS X operating system. Cocoa Touch is the API for iOS. Cocoa and Cocoa Touch follows a Model-View-Controller (MVC) software architecture.

Objective-C

Objective-C is a general-purpose, object-oriented programming language that adds Smalltalk-style messaging to the C programming language. It is the main programming language used by Apple for the OS X and iOS operating systems. Objective-C was originally developed in the early 1980s. It was selected as the main language used by NeXT for its NeXTSTEP operating system, from which OS X and iOS are derived.

Swift

Swift is a multi-paradigm, compiled programming language launched by Apple in 2014 for iOS and OS X development. Swift is intended to be more resilient to erroneous code than Objective-C, and also more concise. It uses the Objective-C runtime, allowing C, Objective-C, C++ and Swift code to run within a single program.

Frameworks

The system interfaces to the iOS Technologies are delivered by Apple in the iOS SDK in special packages called Frameworks. These are directories that contain shared libraries and the resources needed to support that library. The main iOS Frameworks provided are the following :

Links

Additional useful informations about iOS development are provided at the websites referenced hereafter :

CMakeLists.txt

Posted on by

Last update : June 13, 2015

A CMakelists.txt file is the only thing needed by CMake to generate makefiles for many platforms and IDEs. CMake is a cross-platform free and open-source configurator for managing the build process of software using a compiler-independent method. It is designed to support directory hierarchies and applications that depend on multiple libraries. It is used in conjunction with native build environments such as make, Apple’s Xcode, and Microsoft Visual Studio. CMake has minimal dependencies, requiring only a C++ compiler on its own build system. It refers to the entire family of tools : CMake, CTest, CDash, and CPack.

CMake development began in the year 1999 in response to the need for a cross-platform build environment for the Insight Segmentation and Registration Toolkit (ITK). The project was funded by the United States National Library of Medicine (NLM) as part of the Visible Human Project. It was inspired by the Visualization Toolkit (VTK) at Kitware who maintains the CMake software. The latest version of CMake is  3.2.2 released on April 14, 2015.

The ability to build a directory tree outside the source tree is a key feature of CMake, ensuring that if a build directory is removed, the source file remains unaffected.

A CMake generator translates the platform-agnostic CMakeLists.txt file and produces a platform-dependent build system that you can use to compile the project. CMake can find dependencies, do conditional builds and even set different compile or link flags depending on the choice of different options by the user.

During a build with CMake there are three directories involved :

  • source dir
  • build dir
  • install dir

CMake source directory

The source directory is where the project’s sources are stored. This is the directory to which you extract the project source archive or to where you checked out the sources from a version control system.  Typically a source is any file that is explicitly modified by the developer. The source directory also contains the files which describe the build to CMake : a bunch of CMakeLists.txt files in the source directory and probably in several sub-directories. Eventually additional CMake scripts with the extension .cmake are stored in a special CMake directory. By default CMake does not alter any file in the source directory and doesn’t add new ones.

CMake build directory

The build directory is where all compiler outputs are stored, which includes both object files as well as final executables and libraries. CMake also stores several files of its own there, including its cache. You can have more than one build directory for the same source directory with different build options. The concept to have a build directory separated from the source directory is called Out of source Build. Its much easier to convince yourself that your build has been cleaned since you can simply delete the build folder and start over again.

CMake install directory

CMake is able to copy all relevant files for the build project to an install directory.

CMake GUI

The most basic CMake frontend is the CMake console which is available on all platforms. CMake has also a GUI frontend called cmake-gui.

CMake build options

I mainly use CMake with Visual Studio C++ 2010 and with Xcode on Mac OSX Yosemite.

There are three Visual Studio 2010 generators :

  • Visual Studio 10 2010 : creates project files for the x86 (32bit) processor, running also on x64 processors
  • Visual Studio 10 2010 IA64 : creates project files for the x64 processor
  • Visual Studio 10 2010 Win64 : creates project files for the Itanium processor

Visual Studio 2010 itself is a 32bit program.

There is only one Xcode generator.

CMake Language Syntax

CMake has its own basic scripting language. A listfile may contain only commands and comments. Comments start with a # character and stop at the end of a line. The names of commands are case insensitive, the arguments are case sensitive. A list of all commands is available at the CMake website. The main commands are :

  • add_definitions
  • add_executable
  • add_library
  • cmake_minimum_required
  • find_library
  • include_directories
  • link_directories
  • message
  • project
  • set
  • set_property
  • source_group
  • target_link_libraries

The basic type in CMake is a string. The SET command is used to set the value of a variable to some string. It takes two arguments: the name of the variable and its new value. To access the value of a variable, you perform a substitution with the syntax ${variable name}.

Examples :

# create a list of strings
set (VAR a b c)
# use the system version of BOOST
set (USE_SYSTEM_BOOST ON)
# use CACHE to let user set a value in CMake GUI
set (USE_SYSTEM_SQLITE OFF CACHE BOOL "Don't use the system version")

Finding dependencies

CMake can automatically search for the location of dependency libraries to include in the project.

CMake Cross-Compiling

Cross-compiling is supported by CMake starting with version 2.6.0. Cross compiling means that the software is built for a different system than the one which does the build. This means

  • CMake cannot autodetect the target system
  • Usually the executables don’t run on the build host
  • The build process has to use a different set of include files and libraries for building, i.e. not the native ones

CMake Example

The following example shows the CMakeLists.txt file of the OrthancWebViewer 1.0 project. The following parameters are used :

  1. parameters of the build : set (VAR ON CACHE BOOL “some text”)
  2. parameters to fine-tune linking against system libraries  :
    set (VAR ON CACHE BOOL “some text”)
  3. distribution specific settings : set (VAR OFF CACHE BOOL “some text”)
  4. include resources and abcde.cmake files
  5. check the availability of the Orthanc SDK
  6. add specific definitions
  7. set (CORE_SOURCES …)
  8. add libraries and set target properties
  9. install targets
  10. add UnitTests

The following figures show the CMake GUI on Windows and Mac OSX handling the OrthancWebViewer project.

CMake

CMake version 3.0.1 on Windows 8.1

CMake

CMake version 3.2.3 on Mac OSX

On Mac OSX Cmake generated a CMakeCache.txt file in the Build folder and a CMakeOutput.log file in the Build/CMakeFiles folder.

CMake links

The following list provides links to websites with addition informations about Cmake :

Installation de Festival TTS sur Debian

Posted on by

Last update : April 9, 2015

Suite à l’installation du système Festival TTS sur mon MacBook Air il y a trois mois, je viens de l’installer sur mon laptop avec système d’exploitation Debian 7 Linux. Les différentes archives du système Festival ont été téléchargées et décomprimées avec ARC.

Décompression d'un archive Festival

Décompression d’une archive Festival

J’ai suivi ensuite la même procédure que sur Mac OSX, à savoir

  • création d’un répertoire Festival-TTS sur le desktop avec les sous-répertoires festival, speech_tools et festvox
  • compilation des programmes dans l’ordre speech_tools, festival, festvox
  • installation des voix et dictionnaires dans les sous-répertoires lib/voices et lib/dicts du répertoire festival
Configuration du

Configuration du programme speech_tools

La compilation du programme speech_tools s’est arrêtée avec les messages d’erreur

/usr/bin/ld: cannot find -lcurses
/usr/bin/ld: cannot find -lncurses

L’installation de la bibliothèque libncurses5-dev a réglé ce problème. La suite de la compilation s’est passée sans autres erreurs, abstraction faite de plusieurs avertissements concernant des variables spécifiées, mais non utilisées .

Il a été possible de démarrer le programme Festival avec la commande

/Desktop/Festival-TTS/festival/bin/festival

mais la synthèse d’une phrase de test

festival> (SayText "Hello, how are you")

a produit l’erreur

Linux: can't open /dev/dsp

Parmi les remèdes trouvés sur le net, j’ai opté pour la solution

apt-get install oss-compat
modprobe snd-pcm-oss

qui a été couronnée de succès.

Il ne restait plus que la configuration des différents chemins d’accès pour mettre le système Festival tout à fait opérationnel. Les commandes suivantes ont été ajoutées au script ~/.bashrc :

FESTIVALDIR="/home/mbarnig/Desktop/Festival-TTS/festival"
FESTVOXDIR="/home/mbarnig/Desktop/Festival-TTS/festvox"
ESTDIR="/home/mbarnig/Desktop/Festival-TTS/speech_tools"
PATH="$FESTIVALDIR/bin:$PATH"
PATH="$ESTDIR/bin:$PATH"
export PATH
export FESTIVALDIR
export FESTVOXDIR
export ESTDIR
Pat

Variables d’environnement et PATH du système Festival

Ca marche!

Lancement

Lancement du programme Festival TTS sur Debian Linux Wheezy

Le chargement respectivement la compilation d’une nouvelle voix, comme le luxembourgeois, ne réussit que si la voix anglaise kal_diphon est présente, si non une erreur “unbound variable rfs_info” se produit.